Found docs updates needed from ADK python release v2.6.3 to v2.7.0

[adk-bot]

Compare URL: google/adk-python@v2.6.3...v2.7.0

Feature Changes

1. Document card_request_interceptors in A2aRemoteAgentConfig

Doc file: docs/a2a/quickstart-consuming.md

Current state:

Request Interceptors

You can inject a list of request_interceptors to add middleware logic to A2A requests:

• before_request: Executed before the agent starts processing. You can modify the A2AMessage, or return an ADK Event to immediately abort the request and return that event to the caller.
• after_request: Executed after the agent has processed the request. You can modify the resulting ADK Event, or return None to filter out and drop the event entirely.

Proposed Change:

Request Interceptors

You can inject a list of request_interceptors to add middleware logic to A2A requests:

• before_request: Executed before the agent starts processing. You can modify the A2AMessage, or return an ADK Event to immediately abort the request and return that event to the caller.
• after_request: Executed after the agent has processed the request. You can modify the resulting ADK Event, or return None to filter out and drop the event entirely.

Card Request Interceptors

You can inject a list of card_request_interceptors to add middleware logic specifically for the remote agent card fetch request:

• before_request: An async hook returning per-invocation configuration (A2aCardRequestConfig) for the agent card request. It is called before fetching the card from an http(s) URL, allowing you to inject headers (e.g., an auth token from session state). This is ignored for static AgentCard or file-path sources.

Reasoning:
The v2.7.0 release adds a new feature card_request_interceptors to A2aRemoteAgentConfig to allow users to intercept the HTTP request that fetches the remote agent card and inject custom headers (such as authentication tokens). This needs to be documented in the advanced configuration section alongside request_interceptors.

Reference: src/google/adk/a2a/agent/config.py

2. Document that A2aAgentExecutor's runner argument accepts a callable factory

Doc file: docs/a2a/quickstart-exposing.md

Current state:

from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor

executor = A2aAgentExecutor(
runner=my_runner,
config=A2aAgentExecutorConfig(...),
force_new_version=True
)

Proposed Change:

from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor

executor = A2aAgentExecutor(
runner=my_runner, # This can now be a callable/factory!
config=A2aAgentExecutorConfig(...),
force_new_version=True
)

• runner: The Runner instance that executes the agent. You can also pass a callable (factory function) that returns a Runner (or awaits one), which is useful for lazy initialization or dynamic runner creation per-request.

Reasoning:
The A2aAgentExecutor signature was updated to accept Runner | Callable[..., Runner | Awaitable[Runner]] for its runner argument. This allows developers to pass a runner factory for lazy or dynamic instantiation per A2A request, which should be documented for advanced A2A configurations.

Reference: src/google/adk/a2a/executor/a2a_agent_executor.py

3. Document that Function Tools can return media content in their responses

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

Current state:

The preferred return type for a Function Tool is a dictionary in Python, a
Map or custom Record or POJO in Java, an object in TypeScript, or a
Map or Data Class in Kotlin. This allows you to structure the response
with key-value pairs, providing context and clarity to the LLM. If your function
returns a type other than a dictionary or map, the framework automatically wraps
it into a dictionary with a single key named "result".

Proposed Change:

The preferred return type for a Function Tool is a dictionary in Python, a
Map or custom Record or POJO in Java, an object in TypeScript, or a
Map or Data Class in Kotlin. This allows you to structure the response
with key-value pairs, providing context and clarity to the LLM. If your function
returns a type other than a dictionary or map, the framework automatically wraps
it into a dictionary with a single key named "result".

You can also return media content (such as images or video) as part of your function response. ADK will ensure that these media files are preserved and sent directly back to the model (supported across Gemini, Anthropic, LiteLLM, Apigee, and OCI models).

Reasoning:
The v2.7.0 release introduces the ability for function tools to return media (images and other media) directly back to the model. This should be explicitly mentioned in the "Return type" section of the function tools documentation so developers know they can include media in their tool responses.

Reference: src/google/adk/a2a/converters/part_converter.py

4. Document agent_executor_factory argument for to_a2a

Doc file: docs/a2a/quickstart-exposing.md

Current state:

• agent (required): The primary ADK agent instance you want to expose via the A2A protocol.
• host (optional): The host used to build the A2A RPC URL advertised in the generated agent card. Defaults to "localhost".
• port (optional): The port used in that same URL. Defaults to 8000. to_a2a() does not bind a port itself, so this must match the port you actually serve on (see the uvicorn --port flag below), or the advertised card will point somewhere unreachable.
• push_config_store (optional): A custom store implementation for managing A2A push notifications. If not provided, the system defaults to an in-memory store (InMemoryPushNotificationConfigStore).

Proposed Change:

• agent (required): The primary ADK agent instance you want to expose via the A2A protocol.
• host (optional): The host used to build the A2A RPC URL advertised in the generated agent card. Defaults to "localhost".
• port (optional): The port used in that same URL. Defaults to 8000. to_a2a() does not bind a port itself, so this must match the port you actually serve on (see the uvicorn --port flag below), or the advertised card will point somewhere unreachable.
• push_config_store (optional): A custom store implementation for managing A2A push notifications. If not provided, the system defaults to an in-memory store (InMemoryPushNotificationConfigStore).
• agent_executor_factory (optional): A factory function that creates an A2aAgentExecutor. This allows for deeper customization of the executor (e.g., passing an A2aAgentExecutorConfig with custom data converters or interceptors) when using the to_a2a() helper.

Reasoning:
The to_a2a() function signature was updated in v2.7.0 to include a new agent_executor_factory parameter. This provides developers a way to customize the A2A executor (such as configuring interceptors or custom message converters) while still using the convenient to_a2a() function. It needs to be documented along with the other optional parameters.

Reference: src/google/adk/a2a/utils/agent_to_a2a.py

5. Document that the Python standard library is blocked in Agent Config code references

Doc file: docs/agents/config.md

Current state:

Known limitations {#known-limitations}

The Agent Config feature is experimental and includes the following
limitations:

• Model support: Only Gemini models are currently supported.
  Integration with third-party models is in progress.
• Programming language: The Agent Config feature currently supports
  Python and Java code for tools and other functionality requiring programming code.

Proposed Change:

Known limitations {#known-limitations}

The Agent Config feature is experimental and includes the following
limitations:

• Security restrictions: When using code references in your YAML configurations (e.g., for tools, callbacks, or custom agents), the entire Python standard library is blocked by default to prevent arbitrary code execution vulnerabilities. You must reference your own agent package, google.adk, or an installed third-party package instead.
• Model support: Only Gemini models are currently supported.
  Integration with third-party models is in progress.
• Programming language: The Agent Config feature currently supports
  Python and Java code for tools and other functionality requiring programming code.

Reasoning:
The v2.7.0 release introduces a security enhancement that blocks the entire Python standard library in agent-config YAML code references to prevent arbitrary code execution. This needs to be documented in the limitations or security section for users building YAML-based agents.

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

6. Document native task mode and execution mode options for LlmAgent in Python

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

Current state:

Manage agent context

Control whether the agent receives the prior conversation history.

• include_contents (Optional, Default: 'default'): Determines if the
  contents (history) are sent to the LLM.
  • 'default': The agent receives the relevant conversation history.
  • 'none': The agent receives no prior contents. It operates based solely
    on its current instruction and any input provided in the current turn
    (useful for stateless tasks or enforcing specific contexts).

Proposed Change:

Manage agent context

Control whether the agent receives the prior conversation history.

• include_contents (Optional, Default: 'default'): Determines if the
  contents (history) are sent to the LLM.
  • 'default': The agent receives the relevant conversation history.
  • 'none': The agent receives no prior contents. It operates based solely
    on its current instruction and any input provided in the current turn
    (useful for stateless tasks or enforcing specific contexts).

Configure execution mode

You can control how the agent interacts with the user and other agents using the mode parameter.

• chat (default for an agent used as a sub-agent): The agent participates in a multi-turn conversation with the user and is reachable from peer agents via transfer_to_agent.
• single_turn (default for an agent used as a node in a workflow): The agent completes its task in a single turn without chatting with the user.
• task: A task agent that chats with the user to accomplish a task. In contrast to single_turn, it can interact with the user across turns to complete the work, but it will automatically wrap its final output and signal completion when finished.

=== "Python"

```python
task_agent = LlmAgent(
    # ... other params
    mode="task",
)
```

Reasoning:
The v2.7.0 release adds native task mode support to the Python LlmAgent, alongside the chat and single_turn modes. This needs to be documented so developers understand how to configure agent delegation modes for different workflows.

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

7. Document the new FileArtifactService for local filesystem artifact persistence

Doc file: docs/artifacts/index.md

Current state:

• An in-memory service for testing or temporary storage (e.g., InMemoryArtifactService in Python, defined in google.adk.artifacts.in_memory_artifact_service.py).
• A service for persistent storage using Google Cloud Storage (GCS) (e.g., GcsArtifactService in Python, defined in google.adk.artifacts.gcs_artifact_service.py).

Proposed Change:

• An in-memory service for testing or temporary storage (e.g., InMemoryArtifactService in Python, defined in google.adk.artifacts.in_memory_artifact_service.py).
• A service for persistent storage on a local filesystem (e.g., FileArtifactService in Python, defined in google.adk.artifacts.file_artifact_service.py).
• A service for persistent storage using Google Cloud Storage (GCS) (e.g., GcsArtifactService in Python, defined in google.adk.artifacts.gcs_artifact_service.py).

FileArtifactService

Supported in ADKPython v2.7.0

FileArtifactService is an implementation of BaseArtifactService that persists artifacts to the local filesystem. This provides a balance between the transience of InMemoryArtifactService and the external dependencies of GcsArtifactService, making it ideal for local testing, debugging, and deployments where a shared persistent disk is available.

You specify a root directory when initializing the service, and artifacts are safely organized within that folder based on app_name, user_id, and session_id.

=== "Python"

```python
import os
from google.adk.artifacts.file_artifact_service import FileArtifactService

# Create a directory for artifacts
os.makedirs("/tmp/adk_artifacts", exist_ok=True)

# Initialize the File Artifact Service
file_service_py = FileArtifactService(root_dir="/tmp/adk_artifacts")
print(f"Python FileArtifactService initialized at: {file_service_py.root_dir}")

# Pass the service to the Runner
# runner = Runner(agent=my_agent, app_name="my_app", artifact_service=file_service_py, session_service=session_service)
```

Reasoning:
The FileArtifactService was added in v2.7.0 to allow persisting artifacts to the local filesystem. This needs to be documented alongside the other artifact services (InMemory and GCS).

Reference: src/google/adk/artifacts/file_artifact_service.py