Found docs updates needed from ADK python release v1.24.0 to v1.24.1
- Dominant language
- Shell
- Stars
- 1.5k
- Forks
- 1.3k
- Avg merge
- 7d 1h
- Merged PRs (30d)
- 34
Description
Release comparison: https://github.com/google/adk-python/compare/v1.24.0...v1.24.1
### 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
> ```python
> 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
> ```python
> 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
### 2. **Summary of the change**
**Doc file**: docs/evaluate/index.md
**Current state**:
> (Does not mention Agent Simulator or Tool Simulation)
>
> ...
> ### User Simulation
> ...
**Proposed Change**:
> Add a new section "Tool Simulation" or "Agent Simulator" linking to the new page.
>
> ## Tool Simulation / Agent Simulator
> When evaluating agents, it is often useful to simulate tool outputs rather than calling real APIs. This allows for:
> - Deterministic testing
> - Fault injection (errors, latency)
> - Cost savings
>
> The [Agent Simulator](./agent-simulator.md) provides a flexible way to mock tools and inject behaviors.
**Reasoning**:
Users looking at evaluation docs should be aware of the new Agent Simulator capability for mocking tools during evaluation.
**Reference**: src/google/adk/tools/agent_simulator/agent_simulator_engine.py
### 3. **Summary of the change**
**Doc file**: docs/plugins/index.md
**Current state**:
> * [**Logging**](https://github.com/google/adk-python/blame/main/src/google/adk/plugins/logging_plugin.py):
> Log important information at each agent workflow callback point.
**Proposed Change**:
> * [**Agent Simulator**](/adk-docs/evaluate/agent-simulator/):
> Simulate tool behaviors, mock responses, and inject faults (errors, latency) for testing and evaluation.
> * [**Logging**]...
**Reasoning**:
The Agent Simulator is available as a prebuilt plugin (`AgentSimulatorPlugin`), so it should be listed in the Plugins documentation.
**Reference**: src/google/adk/tools/agent_simulator/agent_simulator_plugin.py
### 4. **Summary of the change**
**Doc file**: docs/tools-custom/mcp-tools.md
**Current state**:
> 48:
> 49: The following examples demonstrate how to use `McpToolset` within the `adk web` development environment. For scenarios where you need more fine-grained control over the MCP connection lifecycle or are not using `adk web`, refer to the "Using MCP Tools in your own Agent out of `adk web`" section later in this page.
> 50:
> 51: ### Example 1: File System MCP Server
**Proposed Change**:
> 48:
> 49: The following examples demonstrate how to use `McpToolset` within the `adk web` development environment. For scenarios where you need more fine-grained control over the MCP connection lifecycle or are not using `adk web`, refer to the "Using MCP Tools in your own Agent out of `adk web`" section later in this page.
> 50:
> 51: ### Handling Progress Updates
> 52:
> 53: For long-running tools, `McpToolset` supports a `progress_callback`. This allows you to receive real-time updates from the MCP server. You can provide a simple callback function or a factory that creates callbacks with access to the runtime context (e.g., to update session state).
> 54:
> 55: ```python
> 56: async def my_progress_callback(progress: float, total: float, message: str):
> 57: print(f"Progress: {progress}/{total} - {message}")
> 58:
> 59: toolset = McpToolset(
> 60: connection_params=...,
> 61: progress_callback=my_progress_callback
> 62: )
> 63: ```
> 64:
> 65: ### Example 1: File System MCP Server
**Reasoning**:
The `McpToolset` and `McpTool` classes now support a `progress_callback` parameter for handling progress notifications from MCP servers. This is useful for long-running operations.
**Reference**: src/google/adk/tools/mcp_tool/mcp_toolset.py
### 5. **Summary of the change**
**Doc file**: docs/integrations/cloud-trace.md
**Current state**:
> If you click on one of the traces, you will see the waterfall view of the detailed process, similar to what we see in the web development UI with `adk web` command.
>
> 
>
> ## Resources
**Proposed Change**:
> If you click on one of the traces, you will see the waterfall view of the detailed process, similar to what we see in the web development UI with `adk web` command.
>
> 
>
> ### Captured Attributes
>
> ADK automatically enriches traces with the following attributes to help you filter and analyze your agent's behavior:
> - `gen_ai.agent.name`: The name of the agent being executed.
> - `user.id`: The ID of the user interacting with the agent.
> - `gcp.vertex.agent.invocation_id`: The unique ID of the invocation.
> - `gcp.vertex.agent.event_id`: The ID of the specific event.
> - `gen_ai.conversation.id`: The session ID.
>
> ## Resources
**Reasoning**:
New telemetry attributes (`gen_ai.agent.name`, `user.id`, etc.) have been added to tracing spans. Documenting them helps users understand what data is available for filtering and debugging.
**Reference**: src/google/adk/telemetry/tracing.py
Contributor guide
Assessment
This issue has not been assessed yet.