Why Agent Testing Is Different

Traditional software testing assumes determinism: given input X, function returns Y. Every time. AI agents violate this assumption at every level.

The same prompt produces different tool call sequences on different runs. The LLM might search the web first one time, check the database first the next. It might call a tool with slightly different arguments. It might take 5 steps or 12 steps to complete the same task.

This non-determinism doesn't mean you can't test agents. It means you need different testing strategies — ones that validate behavior rather than exact outputs.

The Testing Pyramid for Agents

Agent testing has three layers, from fastest/cheapest to slowest/most-expensive:

Layer 1: Tool Unit Tests (Fast, Deterministic)

Test each tool in isolation. This is regular unit testing — no LLM involved:

import pytest
from unittest.mock import patch, MagicMock

# Test the tool function directly
def test_search_products_valid_query():
    """Tool returns formatted results for valid queries."""
    results = search_products(query="laptop", category="electronics", limit=5)
    assert isinstance(results, str)
    assert len(results) > 0

def test_search_products_empty_results():
    """Tool handles no results gracefully."""
    results = search_products(query="xyznonexistent", limit=5)
    assert "no results" in results.lower() or results == "[]"

def test_search_products_sql_injection():
    """Tool rejects SQL injection attempts."""
    with pytest.raises(ValueError, match="dangerous SQL"):
        search_products(query="'; DROP TABLE products; --")

# Test with mocked external dependencies
@patch("httpx.AsyncClient.get")
async def test_github_tool_404(mock_get):
    """Tool handles missing repos gracefully."""
    mock_get.return_value = MagicMock(status_code=404)
    result = await fetch_github_repo("nonexistent", "repo")
    assert "not found" in result.lower()

@patch("httpx.AsyncClient.get")
async def test_github_tool_timeout(mock_get):
    """Tool handles timeouts gracefully."""
    mock_get.side_effect = httpx.TimeoutException("timeout")
    result = await fetch_github_repo("owner", "repo")
    assert "error" in result.lower() or "timeout" in result.lower()

Tool tests should cover: valid inputs, edge cases, error conditions, and security boundaries. These tests run in milliseconds and catch most integration bugs.

Layer 2: Agent Behavior Tests (Medium Speed, Semi-Deterministic)

Test that the agent calls the right tools in response to specific prompts. Use temperature=0 and mock tool responses to reduce non-determinism:

from langchain_core.messages import HumanMessage, AIMessage, ToolMessage
from unittest.mock import AsyncMock

async def test_agent_uses_search_for_research_query():
    """Agent should call web_search when asked to research a topic."""
    # Mock the tools to track calls
    mock_search = AsyncMock(return_value="Result 1: LangGraph is popular...")
    mock_read = AsyncMock(return_value="Page content about LangGraph...")

    with patch.dict(tool_registry, {
        "web_search": mock_search,
        "read_webpage": mock_read
    }):
        result = await research_app.ainvoke({
            "messages": [HumanMessage(content="Research LangGraph adoption in 2026")],
            "notes": [], "sources": []
        }, config={"recursion_limit": 10})

    # Verify the agent used search (not just generated an answer)
    assert mock_search.called, "Agent should have searched the web"
    # Verify it produced a final answer
    last_msg = result["messages"][-1]
    assert not last_msg.tool_calls, "Final message should be a response, not a tool call"

async def test_agent_handles_search_failure():
    """Agent should recover when search tool fails."""
    mock_search = AsyncMock(return_value="Search failed: timeout. Try again later.")

    with patch.dict(tool_registry, {"web_search": mock_search}):
        result = await research_app.ainvoke({
            "messages": [HumanMessage(content="Find latest Python release notes")],
            "notes": [], "sources": []
        }, config={"recursion_limit": 10})

    # Agent should still produce an answer (from its training data)
    last_msg = result["messages"][-1]
    assert last_msg.content, "Agent should produce a response despite search failure"

Layer 3: End-to-End Evaluation (Slow, Expensive, Essential)

Run the agent against a suite of real tasks and evaluate quality. This is where LLM-as-judge comes in:

from langchain_openai import ChatOpenAI
import json

evaluator = ChatOpenAI(model="gpt-4o", temperature=0)

test_cases = [
    {
        "input": "Compare the pricing of GPT-4o and Claude 3.5 Sonnet",
        "criteria": [
            "Mentions specific pricing numbers for both models",
            "Information is current (2026 pricing, not 2024)",
            "Includes per-token or per-million-token costs",
            "Notes any differences in pricing tiers or features"
        ]
    },
    {
        "input": "Find the top 3 trending Python repos on GitHub this week",
        "criteria": [
            "Lists exactly 3 repositories",
            "Includes repo names with owner/repo format",
            "Mentions star counts or trending metrics",
            "Repos are actually Python projects"
        ]
    }
]

async def evaluate_agent(agent_app, test_case: dict) -> dict:
    """Run agent and evaluate output against criteria."""
    result = await agent_app.ainvoke({
        "messages": [HumanMessage(content=test_case["input"])]
    })
    agent_output = result["messages"][-1].content

    eval_prompt = f"""Evaluate this AI agent's response against the criteria.
    Score each criterion as PASS or FAIL with a brief explanation.

    Agent output:
    {agent_output}

    Criteria:
    {json.dumps(test_case['criteria'], indent=2)}

    Return JSON: {{"scores": [{{"criterion": "...", "pass": true/false, "reason": "..."}}], "overall_pass": true/false}}"""

    eval_result = await evaluator.ainvoke([HumanMessage(content=eval_prompt)])
    return json.loads(eval_result.content)

Debugging Agent Reasoning

When an agent fails, the hardest question is why. The agent took 12 steps, called 8 tools, and produced a wrong answer. Which step went wrong?

LangSmith: The Agent Debugger

LangSmith (by LangChain) is the most comprehensive agent debugging tool. It captures every step of your agent's execution:

# Enable LangSmith tracing (set env vars)
# LANGCHAIN_TRACING_V2=true
# LANGCHAIN_API_KEY=your-key
# LANGCHAIN_PROJECT=my-agent-debug

# Every agent invocation is now traced:
# - Each LLM call with full prompts and responses
# - Each tool call with arguments and results
# - Token counts and latency per step
# - The full state at each graph node

# You can also add custom metadata to traces:
result = await agent.ainvoke(
    {"messages": [HumanMessage(content="...")]},
    config={
        "metadata": {
            "test_case": "pricing_comparison",
            "run_id": "test-2026-03-16"
        }
    }
)

DIY Tracing with Callbacks

If you don't want to use LangSmith, build your own tracing:

from langchain_core.callbacks import BaseCallbackHandler
from datetime import datetime

class AgentTracer(BaseCallbackHandler):
    def __init__(self):
        self.steps = []

    def on_llm_start(self, serialized, prompts, **kwargs):
        self.steps.append({
            "type": "llm_call",
            "timestamp": datetime.now().isoformat(),
            "prompt_tokens": sum(len(p.split()) for p in prompts)
        })

    def on_tool_start(self, serialized, input_str, **kwargs):
        self.steps.append({
            "type": "tool_call",
            "tool": serialized.get("name", "unknown"),
            "input": input_str[:200],
            "timestamp": datetime.now().isoformat()
        })

    def on_tool_end(self, output, **kwargs):
        if self.steps and self.steps[-1]["type"] == "tool_call":
            self.steps[-1]["output"] = str(output)[:200]
            self.steps[-1]["success"] = "error" not in str(output).lower()

    def print_trace(self):
        for i, step in enumerate(self.steps):
            print(f"Step {i+1} [{step['type']}]: {step.get('tool', 'LLM')} → {step.get('output', '')[:80]}")

tracer = AgentTracer()
result = await agent.ainvoke(state, config={"callbacks": [tracer]})
tracer.print_trace()

Common Failure Modes (And How to Fix Them)

Failure	Symptom	Fix
Infinite loop	Agent keeps calling the same tool with same args	Set recursion_limit + add "if no results found, try different approach" to system prompt
Tool selection error	Agent calls wrong tool for the task	Improve tool descriptions — they're the #1 signal for tool selection
Argument hallucination	Agent passes invalid args to tools	Use Pydantic validation + constrain with enums where possible
Context overflow	Agent forgets early findings	Implement summary memory (Lesson 5) + inject key facts into system prompt
Premature termination	Agent stops before completing the task	Add explicit completion criteria to the system prompt
Cost explosion	Agent takes 50+ steps on a simple task	Set max_steps + cost ceiling + alert on anomalies

The Evaluation Loop

Testing agents isn't a one-time activity. It's a continuous loop:

Define test cases with clear success criteria
Run the agent against all test cases
Evaluate outputs (automated + LLM-as-judge)
Log failures with full traces
Fix the root cause (prompt, tools, or architecture)
Re-run to confirm the fix doesn't break other cases

This is the same loop as traditional testing, just with different tools. The key difference: you need a much larger test suite because non-deterministic systems can pass 9 out of 10 runs and fail the 10th. Run each test case at least 3 times.

For observability and monitoring tools, check tools.skila.ai for reviews of LangSmith, Langfuse, Braintrust, and other agent debugging platforms.

Testing and Debugging AI Agents

Related Resources