/building-pydantic-ai-agents

Testing and Debugging

Read this file when the user wants deterministic tests, custom test models, request inspection, or runtime debugging.

Test Agent Behavior

Use TestModel for fast deterministic tests and FunctionModel for custom response logic.

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel

agent = Agent('openai:gpt-5.2')

with agent.override(model=TestModel()):
    result = agent.run_sync('test prompt')
    assert result.output == 'success (no tool calls)'

from pydantic_ai import Agent, ModelResponse, TextPart
from pydantic_ai.models.function import FunctionModel

agent = Agent('openai:gpt-5.2')


def custom_model(messages, info):
    return ModelResponse(parts=[TextPart(content='mocked response')])


with agent.override(model=FunctionModel(custom_model)):
    result = agent.run_sync('test prompt')

Default split:

• TestModel when you want automatic valid outputs
• FunctionModel when you need exact behavior for assertions, failures, or retries

Debug a Failed Agent Run

Use capture_run_messages() when the user needs the exact request/response history that led to a failure.

from pydantic_ai import Agent, UnexpectedModelBehavior, capture_run_messages

agent = Agent('openai:gpt-5.2')

with capture_run_messages() as messages:
    try:
        agent.run_sync('Please get me the volume of a box with size 6.')
    except UnexpectedModelBehavior:
        print(messages)

Use this for in-process debugging. It is a better fit than broad logging when the user wants to inspect one failing run.

Debug and Validate Agent Behavior

Use Logfire when the user wants observability across agent runs, tools, and model requests.

import logfire

logfire.configure()
logfire.instrument_pydantic_ai()
logfire.instrument_httpx(capture_all=True)

Good uses:

• tracing tool calls
• validating what was sent to the provider
• understanding structured-output failures
• production observability