Create integration page for environment simulation

[zyantw]

Staged: shared link in internal tracker
Logo link: https://www.flaticon.com/free-icon/simulation_5376499

Agent's PR: #1257 and #1259

--

Technical Code Verification & Citations (google/adk-python)

All module names, class definitions, method signatures, parameter names, default values, and validation behaviors were verified against the google/adk-python GitHub repository:

Factory Interface & Entry Points

• Source File: src/google/adk/tools/environment_simulation/environment_simulation_factory.py
• Class: EnvironmentSimulationFactory (Line 33)
• Methods:
  • create_callback(config: EnvironmentSimulationConfig): Returns an asynchronous callback Callable[[BaseTool, Dict[str, Any], Any], Awaitable[Optional[Dict[str, Any]]]] suitable for before_tool_callback (Lines 37–58).
  • create_plugin(config: EnvironmentSimulationConfig): Returns an instance of EnvironmentSimulationPlugin for registration with App(plugins=[...]) (Lines 61–74).

Configuration Objects & Validation Logic

• Source File: src/google/adk/tools/environment_simulation/environment_simulation_config.py
• Classes:
  • InjectedError (Lines 42–53):
    • injected_http_error_code: int
    • error_message: str
  • InjectionConfig (Lines 56–81):
    • injection_probability: float = 1.0
    • match_args: Optional[Dict[str, Any]] = None
    • injected_latency_seconds: float = Field(default=0.0, le=120.0)
    • random_seed: Optional[int] = None
    • injected_error: Optional[InjectedError] = None
    • injected_response: Optional[Dict[str, Any]] = None
    • Validator (Lines 72–80): Enforces that exactly one of injected_error or injected_response is provided.
  • MockStrategy (Lines 84–94):
    • MOCK_STRATEGY_UNSPECIFIED = 0
    • MOCK_STRATEGY_TOOL_SPEC = 1 (Standard LLM-powered schema mock)
    • MOCK_STRATEGY_TRACING = 2 (Deprecated, historical replay)
  • ToolSimulationConfig (Lines 97–123):
    • tool_name: str
    • injection_configs: List[InjectionConfig] = Field(default_factory=list)
    • mock_strategy_type: MockStrategy = MockStrategy.MOCK_STRATEGY_UNSPECIFIED
    • Validator (Lines 111–122): Enforces that if injection_configs is empty, mock_strategy_type cannot be MOCK_STRATEGY_UNSPECIFIED.
  • EnvironmentSimulationConfig (Lines 126–170):
    • tool_simulation_configs: List[ToolSimulationConfig]
    • simulation_model: str = "gemini-2.5-flash"
    • simulation_model_configuration: genai_types.GenerateContentConfig (defaults to ThinkingConfig(10240))
    • tracing: Optional[str] = None
    • environment_data: Optional[str] = None
    • Validator (Lines 157–170): Enforces that tool_simulation_configs is non-empty and contains unique tool_name entries.

Plugin Execution Lifecycle

• Source File: src/google/adk/tools/environment_simulation/environment_simulation_plugin.py
• Class: EnvironmentSimulationPlugin(BasePlugin) (Line 31)
• Lifecycle Hook: async def before_tool_callback(self, tool: BaseTool, tool_args: dict[str, Any], tool_context: ToolContext) -> Optional[Dict[str, Any]] (Lines 39–43).

Simulation Engine & Connection Analysis

• Source Files:
  • src/google/adk/tools/environment_simulation/environment_simulation_engine.py
  • src/google/adk/tools/environment_simulation/tool_connection_analyzer.py
  • src/google/adk/tools/environment_simulation/tool_connection_map.py
• Functionality:
  • Inspects tool schemas using ToolConnectionAnalyzer.
  • Identifies StatefulParameter instances (creating_tools, consuming_tools).
  • Maintains state storage across consecutive tool invocations during agent runs.