Update ADK doc according to issue #1256 - 1 - Agent Simulator

[adk-bot]

1. Summary of the change

Doc file: docs/evaluate/agent-simulator.md

Current state:

File does not exist.

Proposed Change:

Create a new documentation page for the Agent Simulator.

Content outline:

Agent Simulator

The Agent Simulator allows you to simulate and test agent behaviors by mocking tool outputs and injecting faults (latency, errors) without invoking real tools.

Key Features

• Tool Mocking: Define mock strategies (Tool Spec or Tracing) to generate tool responses.
• Fault Injection: Inject latency, errors, or custom responses with defined probabilities.
• Connection Analysis: Automatically analyze tool connections using an LLM.

Automatic Connection Analysis

The Agent Simulator uses an LLM to analyze the schemas of your tools and identify "stateful parameters" (e.g., IDs created by one tool and used by another). This allows the simulator to maintain a consistent state across tool calls.

• Creating Tools: Tools that generate new resources (e.g., create_ticket) will have their output captured.
• Consuming Tools: Tools that operate on resources (e.g., get_ticket) will be validated against the captured state.

Configuration

Explain AgentSimulatorConfig, ToolSimulationConfig, and InjectionConfig.

Example Configuration

from google.adk.tools.agent_simulator.agent_simulator_config import AgentSimulatorConfig, ToolSimulationConfig, InjectionConfig, MockStrategy

config = AgentSimulatorConfig(
    tool_simulation_configs=[
        ToolSimulationConfig(
            tool_name="my_tool",
            injection_configs=[
                InjectionConfig(
                    injection_probability=0.5,
                    injected_error=InjectedError(
                        injected_http_error_code=500,
                        error_message="Internal Server Error"
                    )
                )
            ],
            mock_strategy_type=MockStrategy.MOCK_STRATEGY_TOOL_SPEC
        )
    ]
)

Usage

Explain how to use it as a Plugin or Callback.

Using as a Plugin

from google.adk.tools.agent_simulator.agent_simulator_factory import AgentSimulatorFactory

plugin = AgentSimulatorFactory.create_plugin(config)
runner = InMemoryRunner(agent=agent, plugins=[plugin])

Reasoning:
The v1.24.1 release introduces the Agent Simulator, a major new feature for testing and simulation. A new documentation page is required to explain its configuration, usage, and features like automatic connection analysis and stateful simulation.

Reference: src/google/adk/tools/agent_simulator/agent_simulator_engine.py

[joefernandez]

recommend adding this to /adk-docs/docs/integrations/ directory (not /eval), and linking to it from the main Eval page

[jcwriter74]

• All changes recommended are added to https://github.com/google/adk-docs/pull/1257/changes

• Including new section for using the Agent Simulator as a Callback; below:

## Using as a Callback
To use the Agent Simulator as a callback, create a callback function using `AgentSimulatorFactory.create_callback(config)`. This can be used as a `before_tool_callback` or `after_tool_callback`.

```python
from google.adk.tools.agent_simulator.agent_simulator_factory import AgentSimulatorFactory

callback = AgentSimulatorFactory.create_callback(config)
# Use the callback in your tool setup

[jcwriter74]

recommend adding this to /adk-docs/docs/integrations/ directory (not /eval), and linking to it from the main Eval page

@joefernandez what Eval page? would it be creating a new md in /adk-docs/docs/integrations/ ?

[jcwriter74]

recommend adding this to /adk-docs/docs/integrations/ directory (not /eval), and linking to it from the main Eval page

• Already added to the /adk-docs/docs/integrations/ -[x]
• Linking to it from the main Eval page -[]

[zyantw]

Closing with: #2174