Found docs updates needed from ADK python release v1.22.1 to v1.23.0

[xuanyang15]

google/adk-python@v1.22.1...v1.23.0

1. Add Data Agent tool to the Google Cloud tools index page.

Doc file: docs/tools/google-cloud/index.md

Current state:

The list of Google Cloud tools does not include the new Data Agents tool.

Proposed Change:

Add a new card for 'Data Agents' pointing to '/adk-docs/tools/google-cloud/data-agent/'.
Example HTML:

Data Agents

Analyze data using natural language with Data Agents

Reasoning:
New Data Agent toolset introduced in v1.23.0 needs to be discoverable in the Google Cloud tools index.

Reference: src/google/adk/tools/data_agent/data_agent_toolset.py

2. Create documentation for the new DebugLoggingPlugin.

Doc file: docs/observability/debug-logging.md

Current state:

No documentation for the new DebugLoggingPlugin.

Proposed Change:

Create a new documentation page for DebugLoggingPlugin.

Structure:

1. Overview: Explains that DebugLoggingPlugin captures detailed interaction data (LLM requests/responses, tool calls, events, session state) to a YAML file for debugging.
2. Usage:

   from google.adk.plugins import DebugLoggingPlugin
   
   debug_plugin = DebugLoggingPlugin(output_path="debug_logs.yaml")
   runner = Runner(agent=my_agent, plugins=[debug_plugin])

3. Output Format: Describe the YAML structure (per-invocation documents).
4. Configuration: Document parameters output_path, include_session_state, include_system_instruction.

Reasoning:
New DebugLoggingPlugin is a significant feature for observability and debugging that requires dedicated documentation.

Reference: src/google/adk/plugins/debug_logging_plugin.py

3. Document environment variables for trace content capture and privacy.

Doc file: docs/observability/cloud-trace.md

Current state:

The documentation does not mention environment variables for controlling data capture in traces.

Proposed Change:

Add a section "Privacy and Data Capture" explaining how to control the logging of sensitive content in traces.

Explain two environment variables:

1. ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS: Set to 'false' or '0' to disable capturing potentially PII data (LLM requests/responses/tool args) in ADK spans. Defaults to 'true'.
2. OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: Set to 'true' or '1' to enable logging of prompt/response content in GenAI instrumented spans.

Also mention that ADK tracing now aligns with OpenTelemetry Semantic Conventions for Generative AI.

Reasoning:
New tracing implementation introduces environment variables to control data capture, which is critical for privacy and compliance. Users need to know how to configure this.

Reference: src/google/adk/telemetry/tracing.py

4. Document adk eval_set CLI commands.

Doc file: docs/evaluate/index.md

Current state:

The documentation mentions adk eval but not the adk eval_set commands for creating and managing eval sets via CLI.

Proposed Change:

Add a section "Managing Eval Sets via CLI" (or similar) describing the new commands:

• adk eval_set create: Creates an empty EvalSet.
• adk eval_set add_eval_case: Adds eval cases to an eval set, e.g., from a conversation scenarios file.

Mention that these commands allow programmatic creation of evaluation datasets.

Reasoning:
New CLI commands adk eval_set create and adk eval_set add_eval_case allow users to manage evaluation datasets from the command line, complementing the web UI approach.

Reference: src/google/adk/cli/cli_tools_click.py

5. Document Express Mode deployment for Agent Engine.

Doc file: docs/deploy/agent-engine/deploy.md

Current state:

The documentation for deploying to Agent Engine does not mention support for Vertex AI Express Mode (using an API key).

Proposed Change:

Add a section or note about deploying with Express Mode.
Mention the --api_key option for adk deploy agent_engine.
Explain that this initializes vertexai with the API key instead of project/location credentials.

Reasoning:
The CLI now supports deploying to Agent Engine with an API key (Express Mode), enabling usage without full GCP project credentials setup in some cases. This option should be documented.

Reference: src/google/adk/cli/cli_deploy.py

6. Document Custom Metrics configuration for evaluation.

Doc file: docs/evaluate/criteria.md

Current state:

The documentation lists standard evaluation criteria but does not mention how to define custom metrics using Python code.

Proposed Change:

Add a section "Custom Metrics" explaining how to define metrics backed by custom Python functions.
Show how to configure them in test_config.json using the custom_metrics field with code_config pointing to the function path.
Include the JSON example from EvalConfig docstring.

Reasoning:
New feature custom_metrics in EvalConfig allows users to define their own evaluation logic using Python functions. This is a powerful extensibility feature that should be documented.

Reference: src/google/adk/evaluation/eval_config.py

7. Update MCP Tools docs with StreamableHTTP and timeout params.

Doc file: docs/tools-custom/mcp-tools.md

Current state:

The documentation for McpToolset mentions StdioConnectionParams and SseConnectionParams but omits StreamableHTTPConnectionParams in the overview. It also doesn't mention the new timeout configuration options.

Proposed Change:

Update the McpToolset class overview to include StreamableHTTPConnectionParams as a connection option.
Add a section or note about configuring timeouts (timeout, sse_read_timeout) in connection parameters for better stability in production.

Reasoning:
StreamableHTTPConnectionParams is a supported and important connection method (especially for Cloud Run). New timeout parameters were added to connection params to handle network issues better. These should be documented.

Reference: src/google/adk/tools/mcp_tool/mcp_session_manager.py

8. Update LiteLLM docs with file upload support and Gemini warning.

Doc file: docs/agents/models/litellm.md

Current state:

The documentation covers basic usage but doesn't mention file handling capabilities or the warning about using Gemini via LiteLLM.

Proposed Change:

1. Mention that file inputs (images, PDFs, etc.) are automatically handled for supported providers (OpenAI, Azure) by uploading them as files when necessary.
2. Add a note about the warning when using LiteLlm(model="gemini/...") suggesting the native Gemini model class for better performance.

Reasoning:
LiteLLM integration has been updated to support automatic file uploads for OpenAI/Azure, and now warns users when using Gemini models via LiteLLM instead of the native integration. These are important for usability and performance.

Reference: src/google/adk/models/lite_llm.py

9. Document include_plugins parameter for AgentTool

Doc file: docs/agents/multi-agents.md

Current state:

The documentation for AgentTool does not mention the include_plugins parameter.

Proposed Change:

Add a note or update the AgentTool example to mention the include_plugins parameter.
Explain that include_plugins (default: True) controls whether the child agent inherits plugins from the parent runner. Setting it to False allows for isolated execution.

Reasoning:
New parameter include_plugins added to AgentTool allows controlling plugin propagation in multi-agent setups. This is important for configuring agent isolation.

Reference: src/google/adk/tools/agent_tool.py

10. Update logging guide to reference logging plugins.

Doc file: docs/observability/logging.md

Current state:

docs/observability/logging.md focuses on standard Python logging configuration.

Proposed Change:

Add a section "Logging Plugins" or "Advanced Debugging" that links to the new DebugLoggingPlugin documentation.
Also briefly mention LoggingPlugin for console-based summary logging.

Reasoning:
Users looking for logging information should be made aware of the dedicated logging plugins available in ADK.

Reference: src/google/adk/plugins/logging_plugin.py