AG2 provides a built-in TestConfig utility in the ag2.testing module to help you write unit tests for your agents. It allows you to mock LLM responses and simulate tool execution scenarios without making actual API calls.
Wrap TestConfig in TrackingConfig to inspect what the framework sends to the model. Each entry in calls records one attempted call, including attempts that raise an exception. Its messages tuple contains the complete ordered event input, while prompt, tools, dependencies, and variables retain the call's settings.
Message snapshots copy events and their supported mutable payloads, including input metadata and provider replay data. Later changes to live history or an application's original data do not change earlier snapshots. Snapshot events remain ordinary event objects; treat them as observations rather than modifying them. The existing mock still records each call's original last message. For compatibility, ModelCall equality compares its existing settings fields; assert call.messages explicitly to compare message snapshots. Dependencies and variables retain their existing shallow-copy behavior.
To mock LLM answers, you can use TestConfig in place of a standard model configuration. Pass the expected responses as arguments to TestConfig. Each argument represents the mocked response for a sequential turn in the conversation.
importpytestfromag2importAgentfromag2.testingimportTestConfig@pytest.mark.asyncioasyncdeftest_mock_llm_answer():# Provide a TestConfig with the mocked string responseagent=Agent("test_agent")# Ask the agent, passing the TestConfigres=awaitagent.ask("Hi!",config=TestConfig("This is a mocked response."),)# The agent returns the mocked responseassertres.body=="This is a mocked response."
You can also use TestConfig to yield tool calls. This allows you to test both successful tool execution and error handling. By providing a ToolCallEvent as the first response and a string as the final response, you can simulate a complete agent-tool interaction loop.
importpytestfromag2importAgentfromag2.eventsimportToolCallEventfromag2.testingimportTestConfig@pytest.mark.asyncioasyncdeftest_tool_success():# Define a tooldefmy_tool()->str:return"tool execution result"agent=Agent("test_agent",tools=[my_tool])# Configure TestConfig to first return a ToolCallEvent, then a final string answertest_config=TestConfig(ToolCallEvent(name="my_tool"),"final result",)res=awaitagent.ask("Please use my_tool",config=test_config)# After the tool is called and succeeds, the agent returns the second mocked eventassertres.body=="final result"
importpytestfromag2importAgentfromag2.eventsimportToolCallEventfromag2.testingimportTestConfig@pytest.mark.asyncioasyncdeftest_tool_raise_exc():# Define a tool that raises an errordeffailing_tool()->str:raiseValueError("Something went wrong")test_config=TestConfig(ToolCallEvent(name="failing_tool"),"result",)agent=Agent("test_agent",config=test_config,tools=[failing_tool],)withpytest.raises(ValueError,match="Something went wrong"):awaitagent.ask("Hi!")
importpytestfromag2importAgentfromag2.eventsimportToolCallEventfromag2.exceptionsimportToolNotFoundErrorfromag2.testingimportTestConfig@pytest.mark.asyncioasyncdeftest_tool_not_found():# Mock the LLM returning a tool call for "unregistered_tool"test_config=TestConfig(ToolCallEvent(name="unregistered_tool"))# Agent is created WITHOUT any toolsagent=Agent("test_agent",config=test_config)withpytest.raises(ToolNotFoundError,match="Tool `unregistered_tool` not found"):awaitagent.ask("Hi!")
TestFilesClient is an in-memory Files API. Pass it to TestConfig(files=...), and what your code uploads through FilesAPI can be read, listed and deleted without a provider.