Found docs updates needed from ADK python release v2.0.0 to v2.2.0

[xuanyang15]

1. Update Environment Toolset file operations descriptions to match tool capabilities and constraints

Doc file: docs/integrations/environment-toolset.md

Current state:

File operations

The LocalEnvironment implementation includes the following tools an
agent can run within a local compute environment:

• ReadFile: Read an existing text file based on agent instructions.
• EditFile: Edit an existing text file based on agent instructions.
• WriteFile: Create a new text file based on agent instructions.
• Execute: Execute terminal commands, including running installers,
  shell scripts, and program code, based on agent instructions.

Proposed Change:

File operations

The LocalEnvironment implementation includes the following tools an
agent can run within a local compute environment:

• ReadFile: Read an existing text file based on agent instructions. It supports reading specific line ranges (start_line, end_line) to manage context window limits.
• EditFile: Perform surgical text replacements in an existing file. It requires an exact old_string that appears exactly once in the file, replacing it with a new_string.
• WriteFile: Create or overwrite a text file based on agent instructions. Use this for new files or full rewrites.
• Execute: Execute terminal commands, including running installers,
  shell scripts, and program code, based on agent instructions. It is recommended to use ReadFile instead of shell commands (like cat, head, tail) for file reading.

Reasoning:
The release introduces the actual implementation of these tools with specific behaviors: ReadFile supports line ranges (start_line, end_line), EditFile requires exact unique string matching, WriteFile is meant for full rewrites, and ExecuteTool explicitly warns against using it for file reading. Updating the descriptions will help users understand how to properly utilize them.

Reference: src/google/adk/tools/environment/_edit_file_tool.py, src/google/adk/tools/environment/_execute_tool.py, src/google/adk/tools/environment/_read_file_tool.py, src/google/adk/tools/environment/_write_file_tool.py

2. Document the new request_input tool in Human-in-the-loop workflow pattern

Doc file: docs/workflows/patterns.md

Current state:

• ADK Primitives Used (Conceptual):
  • Interaction: Can be implemented using a custom Tool that pauses execution and sends a request to an external system (e.g., a UI, ticketing system) waiting for human input. The tool then returns the human's response to the agent.
  • Workflow: Could use LLM-Driven Delegation (transfer_to_agent) targeting a conceptual "Human Agent" that triggers the external workflow, or use the custom tool within an LlmAgent.
  • State/Callbacks: State can hold task details for the human; callbacks can manage the interaction flow.
  • Note: ADK doesn't have a built-in "Human Agent" type, so this requires custom integration.

Proposed Change:

• ADK Primitives Used:
  • Interaction: Use the built-in request_input tool (from google.adk.tools import request_input) which allows the agent to pause execution, ask the user a question with a specific response schema, and wait for their input. Alternatively, you can implement a custom Tool that sends a request to an external system.
  • Workflow: Could use LLM-Driven Delegation (transfer_to_agent) targeting a conceptual "Human Agent" that triggers the external workflow, or use the request_input tool within an LlmAgent.
  • State/Callbacks: State can hold task details for the human; callbacks can manage the interaction flow.

Reasoning:
The ADK now includes a built-in request_input tool that handles proactive clarification and input requests from users natively, removing the need for a fully custom tool to achieve this basic human-in-the-loop interaction.

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

3. Add AutoTracingPlugin to the list of Prebuilt Plugins

Doc file: docs/plugins/index.md

Current state:

Prebuilt Plugins

ADK includes several plugins that you can add to your agent workflows
immediately:

• Reflect and Retry Tools:
  Tracks tool failures and intelligently retries tool requests.
• BigQuery Analytics:
  Enables agent logging and analysis with BigQuery.
• Context Filter:
  Filters the generative AI context to reduce its size.
• Global Instruction:
  Plugin that provides global instructions functionality at the App level.
• Save Files as Artifacts:
  Saves files included in user messages as Artifacts.
• Logging:
  Log important information at each agent workflow callback point.

Proposed Change:

Prebuilt Plugins

ADK includes several plugins that you can add to your agent workflows
immediately:

• Auto Tracing:
  Auto-instruments in-scope Python functions with OpenTelemetry spans for detailed, function-level observability and debugging.
• Reflect and Retry Tools:
  Tracks tool failures and intelligently retries tool requests.
• BigQuery Analytics:
  Enables agent logging and analysis with BigQuery.
• Context Filter:
  Filters the generative AI context to reduce its size.
• Global Instruction:
  Plugin that provides global instructions functionality at the App level.
• Save Files as Artifacts:
  Saves files included in user messages as Artifacts.
• Logging:
  Log important information at each agent workflow callback point.

Reasoning:
The release introduces a new AutoTracingPlugin that automatically monkey-patches Python functions to emit OpenTelemetry spans. Adding this to the list of prebuilt plugins makes users aware of this new observability feature.

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

4. Mention AutoTracingPlugin in Agent activity traces documentation

Doc file: docs/observability/traces.md

Current state:

| invoke_agent | Client / Internal Span | Describes GenAI agent invocation over a remote service or locally. Represents the lifecycle of an agent interaction.| gen_ai.agent.name, gen_ai.system |
| invoke_workflow | Child Span | Describes the invocation of a multi-step agentic workflow. | gen_ai.workflow.name, gen_ai.system|
| execute_tool | Child Span | Represents the execution of a specific tool or function call requested by the GenAI system.| gen_ai.tool.name, gen_ai.system|
| generate_content {model.name} | Internal Span | Represents the invocation of the underlying language model (via the GenAI SDK) to generate content. It tracks the request parameters, response details, and usage metrics. | gen_ai.operation.name, gen_ai.system, gen_ai.request.model, gen_ai.agent.name, gen_ai.conversation.id, user.id, gen_ai.request.top_p, gen_ai.request.max_tokens, gen_ai.response.finish_reasons, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens |

---

Proposed Change:

| invoke_agent | Client / Internal Span | Describes GenAI agent invocation over a remote service or locally. Represents the lifecycle of an agent interaction.| gen_ai.agent.name, gen_ai.system |
| invoke_workflow | Child Span | Describes the invocation of a multi-step agentic workflow. | gen_ai.workflow.name, gen_ai.system|
| execute_tool | Child Span | Represents the execution of a specific tool or function call requested by the GenAI system.| gen_ai.tool.name, gen_ai.system|
| generate_content {model.name} | Internal Span | Represents the invocation of the underlying language model (via the GenAI SDK) to generate content. It tracks the request parameters, response details, and usage metrics. | gen_ai.operation.name, gen_ai.system, gen_ai.request.model, gen_ai.agent.name, gen_ai.conversation.id, user.id, gen_ai.request.top_p, gen_ai.request.max_tokens, gen_ai.response.finish_reasons, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens |

Function-Level Tracing

For deeper, function-level visibility into your agent's execution, ADK offers the AutoTracingPlugin. When added to your agent runner, this plugin automatically monkey-patches Python functions to emit granular OpenTelemetry spans for internal function calls, capturing arguments and return values. See Prebuilt Plugins for more details.

---

Reasoning:
The new AutoTracingPlugin adds an important layer of detailed observability that complements the standard Semantic Convention spans described on the traces.md page. Mentioning it here ensures users looking for deeper trace waterfalls are aware of the capability.

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

5. Add get_drop_stats() to Troubleshooting section in BigQuery Agent Analytics documentation

Doc file: docs/integrations/bigquery-agent-analytics.md

Current state:

1. Check ADK version: Ensure google-adk>=1.24.0 is in your requirements.
   Earlier versions do not flush pending events before the serverless runtime
   suspends the process.

2. Enable debug logging: Add the following to the top of your agent.py to
   surface any silent errors:

   import logging
   logging.basicConfig(level=logging.INFO)
   logging.getLogger("google_adk").setLevel(logging.DEBUG)

3. Check IAM permissions: The Agent Runtime service account needs
   roles/bigquery.dataEditor on the target table and roles/bigquery.jobUser
   on the project. For cross-project logging, also ensure the BigQuery API
   is enabled in the source project and the service account has
   bigquery.tables.updateData on the destination table.

4. Verify plugin initialization: In Cloud Logging, filter by
   resource.type="reasoning_engine" and look for plugin startup messages or
   error logs.

5. Use immediate flush for debugging: Set batch_size=1 and
   batch_flush_interval=0.1 in BigQueryLoggerConfig to rule out buffering
   issues.

Proposed Change:

1. Check ADK version: Ensure google-adk>=1.24.0 is in your requirements.
   Earlier versions do not flush pending events before the serverless runtime
   suspends the process.

2. Enable debug logging: Add the following to the top of your agent.py to
   surface any silent errors:

   import logging
   logging.basicConfig(level=logging.INFO)
   logging.getLogger("google_adk").setLevel(logging.DEBUG)

3. Check IAM permissions: The Agent Runtime service account needs
   roles/bigquery.dataEditor on the target table and roles/bigquery.jobUser
   on the project. For cross-project logging, also ensure the BigQuery API
   is enabled in the source project and the service account has
   bigquery.tables.updateData on the destination table.

4. Verify plugin initialization: In Cloud Logging, filter by
   resource.type="reasoning_engine" and look for plugin startup messages or
   error logs.

5. Use immediate flush for debugging: Set batch_size=1 and
   batch_flush_interval=0.1 in BigQueryLoggerConfig to rule out buffering
   issues.

6. Monitor for dropped events: The plugin provides a get_drop_stats() method that returns dropped-row counts aggregated by reason (e.g., queue_full, retry_exhausted, arrow_prep_failed, non_retryable, unexpected_error). You can export these counters to your monitoring to detect data loss before it surfaces as missing rows.

Reasoning:
The BigQueryAgentAnalyticsPlugin has been updated to track dropped event stats, resolving issues with duplicate spans or silent drops. Documenting get_drop_stats() under troubleshooting helps users verify and monitor if rows are being lost during the ingestion process.

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

6. Add deprecation warning to Agent Config documentation

Doc file: docs/agents/config.md

Current state:

Build agents with Agent Config

Supported in ADKPython v1.11.0Java v0.3.0Go v0.3.0Experimental

The ADK Agent Config feature lets you build an ADK workflow without writing
code. An Agent Config uses a YAML format text file with a brief description of
the agent, allowing just about anyone to assemble and run an ADK agent.

Proposed Change:

Build agents with Agent Config

Supported in ADKPython v1.11.0Java v0.3.0Go v0.3.0Experimental

!!! warning "Deprecated"
The YAML-based Agent Config feature (from_config and the associated JSON schemas) is deprecated and will be removed in future versions. Please use programmatic generation or standard Python definitions to configure your agents.

The ADK Agent Config feature lets you build an ADK workflow without writing
code. An Agent Config uses a YAML format text file with a brief description of
the agent, allowing just about anyone to assemble and run an ADK agent.

Reasoning:
The Agent Config schemas (e.g. AgentConfig, BaseAgentConfig, LlmAgentConfig) and the from_config loading utility have been marked as deprecated in the codebase. Users need to be warned that this experimental YAML feature will be removed in future versions so they can transition to programmatic definitions.

Reference: src/google/adk/agents/agent_config.py, src/google/adk/agents/config_agent_utils.py

7. Add strong deprecation warning for Sequential, Parallel, and Loop agents

Doc file: docs/agents/workflow-agents/index.md

Current state:

!!! note "Alternative: graph-based workflows"

Starting in ADK 2.0, template workflows have been superseded

by more flexible workflow structures, including
[graph-based workflows](/workflows/graphs/) and
[dynamic workflows](/workflows/dynamic/).
These workflow architectures provide more control, flexibility
and capability to evolve your agent workflows over time.

Proposed Change:

!!! warning "Deprecated: Template Workflows"

Starting in ADK 2.0, template workflow agents (`SequentialAgent`, `ParallelAgent`, and `LoopAgent`) are **deprecated** and will be removed in a future version. 

Please migrate your orchestration logic to the more flexible workflow structures, including [graph-based workflows](/workflows/graphs/) using the `Workflow` class, and [dynamic workflows](/workflows/dynamic/). These workflow architectures provide more control, flexibility, and capability to evolve your agent workflows over time.

Reasoning:
The SequentialAgent, ParallelAgent, and LoopAgent classes have been explicitly marked with the @deprecated decorator in the codebase. The documentation should be updated from a "superseded" note to a strong deprecation warning so users start migrating to the Workflow class.

Reference: src/google/adk/agents/loop_agent.py, src/google/adk/agents/parallel_agent.py, src/google/adk/agents/sequential_agent.py

8. Add history_config to RunConfig Parameter Quick Reference in streaming guide

Doc file: docs/streaming/dev-guide/part4.md

Current state:

Parameter	Type	Purpose	Platform Support	Reference
response_modalities	list[str]	Control output format (TEXT or AUDIO)	Both	Details
streaming_mode	StreamingMode	Choose BIDI or SSE mode	Both	Details
session_resumption	SessionResumptionConfig	Enable automatic reconnection	Both	Details
context_window_compression	ContextWindowCompressionConfig	Unlimited session duration	Both	Details
max_llm_calls	int	Limit total LLM calls per session	Both	Details
save_live_blob	bool	Persist audio/video streams	Both	Details
custom_metadata	dict[str, Any]	Attach metadata to invocation events	Both	Details
support_cfc	bool	Enable compositional function calling	Gemini (2.x models only)	Details
speech_config	SpeechConfig	Voice and language configuration	Both	Part 5: Voice Configuration
input_audio_transcription	AudioTranscriptionConfig	Transcribe user speech	Both	Part 5: Audio Transcription
output_audio_transcription	AudioTranscriptionConfig	Transcribe model speech	Both	Part 5: Audio Transcription
realtime_input_config	RealtimeInputConfig	VAD configuration	Both	Part 5: Voice Activity Detection
proactivity	ProactivityConfig	Enable proactive audio	Gemini (native audio only)	Part 5: Proactivity and Affective Dialog
enable_affective_dialog	bool	Emotional adaptation	Gemini (native audio only)	Part 5: Proactivity and Affective Dialog

Proposed Change:

Parameter	Type	Purpose	Platform Support	Reference
response_modalities	list[str]	Control output format (TEXT or AUDIO)	Both	Details
streaming_mode	StreamingMode	Choose BIDI or SSE mode	Both	Details
session_resumption	SessionResumptionConfig	Enable automatic reconnection	Both	Details
context_window_compression	ContextWindowCompressionConfig	Unlimited session duration	Both	Details
history_config	HistoryConfig	Configures the exchange of history between the client and the server	Both	N/A
max_llm_calls	int	Limit total LLM calls per session	Both	Details
save_live_blob	bool	Persist audio/video streams	Both	Details
custom_metadata	dict[str, Any]	Attach metadata to invocation events	Both	Details
support_cfc	bool	Enable compositional function calling	Gemini (2.x models only)	Details
speech_config	SpeechConfig	Voice and language configuration	Both	Part 5: Voice Configuration
input_audio_transcription	AudioTranscriptionConfig	Transcribe user speech	Both	Part 5: Audio Transcription
output_audio_transcription	AudioTranscriptionConfig	Transcribe model speech	Both	Part 5: Audio Transcription
realtime_input_config	RealtimeInputConfig	VAD configuration	Both	Part 5: Voice Activity Detection
proactivity	ProactivityConfig	Enable proactive audio	Gemini (native audio only)	Part 5: Proactivity and Affective Dialog
enable_affective_dialog	bool	Emotional adaptation	Gemini (native audio only)	Part 5: Proactivity and Affective Dialog

Reasoning:
The release introduces a new history_config property in RunConfig to configure the exchange of history between the client and the server. Adding it to the RunConfig parameter quick reference table ensures developers are aware of this new configuration capability.

Reference: src/google/adk/agents/run_config.py

9. Add rubric_based_multi_turn_trajectory_quality_v1 to the Criteria table

Doc file: docs/evaluate/criteria.md

Current state:

multi_turn_trajectory_quality_v1 | Evaluates the overall trajectory of the conversation | No | No | Yes | Yes
multi_turn_tool_use_quality_v1 | Evaluates function calls made during a conversation | No | No | Yes | Yes

Proposed Change:

multi_turn_trajectory_quality_v1 | Evaluates the overall trajectory of the conversation | No | No | Yes | Yes
multi_turn_tool_use_quality_v1 | Evaluates function calls made during a conversation | No | No | Yes | Yes
rubric_based_multi_turn_trajectory_quality_v1 | LLM-judged overall trajectory quality based on custom rubrics | No | Yes | Yes | Yes

Reasoning:
A new rubric_based_multi_turn_trajectory_quality_v1 criterion was introduced to expand multi-turn trajectory evaluation. It needs to be listed in the overview table.

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

10. Add detailed section for rubric_based_multi_turn_trajectory_quality_v1 criterion

Doc file: docs/evaluate/criteria.md

Current state:

hallucinations_v1

Proposed Change:

rubric_based_multi_turn_trajectory_quality_v1

This criterion assesses the overall trajectory of an agent's behavior across an entire multi-turn conversation using an LLM-as-a-judge against a user-defined set of rubrics.

When To Use This Criterion?

Use this criterion when you want to evaluate the quality of an agent's behavior across an entire multi-turn conversation, including intermediate tool calls, function responses, and final textual replies. It is ideal for evaluating multi-step tasks like itinerary planning or troubleshooting, where success is defined by following specific guidelines across multiple turns.

Details

This evaluator provides a flexible way to evaluate a full dialogue history based on specific rules you define as rubrics. For example, you could define rubrics such as "The agent correctly called the flight search tool with the user-specified parameters" and "The agent confirmed the details before finalizing."

Unlike single-turn evaluators that assess each invocation independently, this evaluator accumulates the full dialogue history and performs a single LLM-based evaluation using the complete conversation context on the last turn. The LLM judge produces a binary verdict (yes or no) indicating whether the agent's trajectory satisfied each rubric property. The overall score is the average of all individual rubric scores.

How To Use This Criterion?

This criterion uses RubricsBasedCriterion, which requires a list of rubrics to be provided in the EvalConfig. Each rubric should be defined with a unique ID and its content.

Example EvalConfig entry:

{
  "criteria": {
    "rubric_based_multi_turn_trajectory_quality_v1": {
      "threshold": 1.0,
      "judge_model_options": {
        "judge_model": "gemini-flash-latest"
      },
      "rubrics": [
        {
          "rubric_id": "flight_search_called",
          "rubric_content": {
            "text_property": "The agent correctly called the flight search tool with the user-specified origin, destination, and dates."
          }
        },
        {
          "rubric_id": "booking_confirmed",
          "rubric_content": {
            "text_property": "The agent confirmed the booking details with the user before finalizing the reservation."
          }
        }
      ]
    }
  }
}

Output And How To Interpret

The criterion outputs an overall score between 0.0 and 1.0, where 1.0 indicates that the agent's trajectory satisfied all rubrics, and 0.0 indicates that no rubrics were satisfied. Higher values are better.

hallucinations_v1

Reasoning:
The RubricBasedMultiTurnTrajectoryEvaluator evaluates full multi-turn conversations against custom rubrics. Adding a section for it explains to users how to configure and use this new feature.

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

11. Remove deprecated staging_bucket and adk_app flags from BQAA deployment guide

Doc file: docs/integrations/bigquery-agent-analytics.md

Current state:

PROJECT_ID=your-gcp-project-id
LOCATION=us-central1

adk deploy agent_engine \
    --project=$PROJECT_ID \
    --region=$LOCATION \
    --staging_bucket=gs://your-staging-bucket \
    --display_name="My BQ Analytics Agent" \
    --adk_app=agent.app \
    my_bq_agent

!!! tip "--adk_app flag"

The `--adk_app` flag specifies the module path and variable name of the
`App` object (in the format `module.variable`). In this example, `agent.app`
refers to the `app` variable in `agent.py`. This ensures the deployment
correctly picks up the plugin configuration.

Proposed Change:

PROJECT_ID=your-gcp-project-id
LOCATION=us-central1

adk deploy agent_engine \
    --project=$PROJECT_ID \
    --region=$LOCATION \
    --display_name="My BQ Analytics Agent" \
    my_bq_agent

Reasoning:
The --staging_bucket and --adk_app flags for the adk deploy agent_engine command have been deprecated and their usage is no longer required or supported by the new container-based deployment process. The tip block explaining --adk_app has also been removed.

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

12. Update programatic deployment in BQAA guide to match container-based deployment changes

Doc file: docs/integrations/bigquery-agent-analytics.md

Current state:

import vertexai
from my_bq_agent.agent import app

PROJECT_ID = "your-gcp-project-id"
LOCATION = "us-central1"
STAGING_BUCKET = "gs://your-staging-bucket"

vertexai.init(
    project=PROJECT_ID, location=LOCATION, staging_bucket=STAGING_BUCKET
)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)

remote_app = client.agent_engines.create(
    agent=app,
    config={
        "display_name": "My BQ Analytics Agent",
        "staging_bucket": STAGING_BUCKET,
        "requirements": [
            "google-adk[bigquery]",
            "google-cloud-aiplatform[agent_engines]",
            "google-cloud-bigquery-storage",
            "pyarrow",
            "opentelemetry-api",
            "opentelemetry-sdk",
        ],
    },
)
print(f"Deployed agent: {remote_app.api_resource.name}")

Proposed Change:

import vertexai

PROJECT_ID = "your-gcp-project-id"
LOCATION = "us-central1"

vertexai.init(
    project=PROJECT_ID, location=LOCATION
)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)

remote_app = client.agent_engines.create(
    config={
        "display_name": "My BQ Analytics Agent",
        "source_packages": ["agents/my_bq_agent", "Dockerfile"],
        "agent_framework": "google-adk"
    },
)
print(f"Deployed agent: {remote_app.api_resource.name}")

Reasoning:
Agent Engine programatic deployment has shifted away from code-based initialization (passing agent=app, requirements, and staging_bucket) to a Docker/Container-based approach where dependencies and code are packaged inside a Dockerfile. Providing the updated SDK equivalent deployment prevents users from utilizing deprecated attributes.

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

13. Document the --allow-unsafe-unpickling flag for session database migration

Doc file: docs/sessions/session/migrate.md

Current state:

=== "SQLite"

```bash
adk migrate session \
  --source_db_url=sqlite:///source.db \
  --dest_db_url=sqlite:///dest.db
```

=== "PostgreSQL"

```bash
adk migrate session \
  --source_db_url=postgresql://localhost:5432/v0 \
  --dest_db_url=postgresql://localhost:5432/v1
```

Proposed Change:

=== "SQLite"

```bash
adk migrate session \
  --source_db_url=sqlite:///source.db \
  --dest_db_url=sqlite:///dest.db
```

=== "PostgreSQL"

```bash
adk migrate session \
  --source_db_url=postgresql://localhost:5432/v0 \
  --dest_db_url=postgresql://localhost:5432/v1
```

Unsafe Pickle Loading

By default, the migration tool uses a restricted unpickler that only allows loading safe built-in types and ADK-specific classes. If you have custom types stored in your legacy v0 database (for example, custom EventActions), the migration will fail with an UnpicklingError.

You can bypass this restriction by passing the --allow-unsafe-unpickling flag to the adk migrate session command. Warning: Only use this flag if you fully trust the source database content, as loading arbitrary pickles can lead to arbitrary code execution.

adk migrate session \
  --source_db_url=sqlite:///source.db \
  --dest_db_url=sqlite:///dest.db \
  --allow-unsafe-unpickling

Reasoning:
The migration script was updated to use a restricted unpickler for security reasons, and introduced the --allow-unsafe-unpickling flag to support migrating custom objects. Users need to be aware of this flag in case their migration fails due to blocked globals.

Reference: src/google/adk/sessions/migration/migrate_from_sqlalchemy_pickle.py, src/google/adk/cli/cli_tools_click.py