Found docs updates needed from ADK python release v1.20.0 to v1.21.0
- Dominant language
- Shell
- Stars
- 1.5k
- Forks
- 1.3k
- Avg merge
- 7d 1h
- Merged PRs (30d)
- 34
Description
This issue outlines the necessary documentation updates for the ADK Python release from v1.20.0 to v1.21.0. You can see the full list of changes in the [compare link](https://github.com/google/adk-python/compare/v1.20.0...v1.21.0).
Here are the recommended changes:
1. **[Feature] Add documentation for the new Interactions API support.**
The newly released Gemini [Interactions API](https://ai.google.dev/gemini-api/docs/interactions) is now supported in ADK. A new page should be created to document this feature.
**Proposed Change**:
Create a new file `docs/agents/interactions-api.md` with the following content:
```markdown
# Using the Gemini Interactions API
The Gemini Interactions API provides stateful conversation capabilities, allowing you to chain interactions using a `previous_interaction_id` instead of sending the full conversation history with each request. This can be more efficient for long conversations.
To enable the Interactions API, set the `use_interactions_api=True` parameter in the `Gemini` model configuration.
## Example
```python
from google.adk.agents.llm_agent import Agent
from google.adk.models.google_llm import Gemini
root_agent = Agent(
model=Gemini(
model="gemini-2.5-flash",
use_interactions_api=True,
),
name="interactions_test_agent",
description="An agent for testing the Interactions API integration",
instruction="You are a helpful assistant.",
)
```
For a more detailed example, see the [Interactions API sample](https://github.com/google/adk-python/tree/main/contributing/samples/interactions_api).
```
Also, add a link to this new page in the `mkdocs.yml` file under the "Agents" section.
**Reasoning**:
This is a major new feature that provides a new way to interact with Gemini models. The documentation should explain what it is, how to use it, and provide an example.
**Reference**:
- `src/google/adk/models/google_llm.py`
- `src/google/adk/flows/llm_flows/interactions_processor.py`
- `contributing/samples/interactions_api/`
2. **[Feature] Document the new `Gemma3Ollama` model integration.**
A new model integration for running Gemma 3 models with Ollama has been added.
**Proposed Change**:
In `docs/agents/models.md`, add a new subsection under the "Ollama Integration" section.
**Current state**:
The "Ollama Integration" section explains how to use Ollama with the `ollama_chat` provider in `LiteLlm`.
**Proposed Change**:
Add the following subsection:
```markdown
### Using Gemma3Ollama
For Gemma 3 models running on Ollama, you can use the `Gemma3Ollama` model class, which provides better support for Gemma 3's function calling capabilities.
```python
from google.adk.agents.llm_agent import Agent
from google.adk.models import Gemma3Ollama
root_agent = Agent(
model=Gemma3Ollama(model="ollama/gemma3:12b"),
name="gemma_agent",
instruction="You are a helpful assistant.",
)
```
For a complete example, see the [hello_world_gemma3_ollama sample](https://github.com/google/adk-python/tree/main/contributing/samples/hello_world_gemma3_ollama).
```
**Reasoning**:
This new model class provides a better experience for using Gemma 3 models with Ollama, and it should be documented.
**Reference**:
- `src/google/adk/models/gemma_llm.py`
- `contributing/samples/hello_world_gemma3_ollama/`
3. **[Feature] Document `add_session_to_memory` on `CallbackContext` and `ToolContext`.**
A new method `add_session_to_memory` has been added to `CallbackContext` and `ToolContext` to allow for explicit saving of the session to memory.
**Proposed Change**:
In `docs/sessions/memory.md`, add a new section.
**Current state**:
The documentation explains how to use `memory_service.add_session_to_memory(session)`.
**Proposed Change**:
Add the following section:
```markdown
### Explicitly Saving to Memory from Callbacks and Tools
You can now explicitly trigger saving the current session to memory from within a callback or a tool by using the `add_session_to_memory()` method on the `CallbackContext` or `ToolContext`.
#### From a Callback
```python
async def auto_save_session_to_memory_callback(callback_context: CallbackContext):
await callback_context.add_session_to_memory()
agent = Agent(
...
after_agent_callback=auto_save_session_to_memory_callback,
)
```
#### From a Tool
```python
async def my_tool(tool_context: ToolContext) -> str:
# ... do some work ...
await tool_context.add_session_to_memory()
return "Work done and session saved to memory."
```
```
**Reasoning**:
This new feature provides a more convenient way to save the session to memory, and it should be documented.
**Reference**:
- `src/google/adk/agents/callback_context.py`
- `src/google/adk/tools/tool_context.py`
4. **[Feature] Update `BigQueryAgentAnalyticsPlugin` documentation for v2.0.**
The `BigQueryAgentAnalyticsPlugin` has been significantly updated. The documentation needs to be updated to reflect the new API and features.
**Proposed Change**:
In `docs/tools/google-cloud/bigquery-agent-analytics.md`, update the code samples and configuration options to reflect the new v2.0 API.
**Current state**:
The documentation is for the old version of the plugin.
**Proposed Change**:
The entire document should be reviewed and updated. Key changes include:
- The plugin initialization has changed.
- The configuration options in `BigQueryLoggerConfig` have been updated.
- The schema of the BigQuery table has been updated.
- New features like multi-modal content logging and GCS offloading have been added.
Please refer to the source code for the new API and update the documentation accordingly.
**Reasoning**:
The plugin has been completely rewritten, and the documentation is now out of date.
**Reference**:
- `src/google/adk/plugins/bigquery_agent_analytics_plugin.py`
5. **[Feature] Document OpenAPI Toolset enhancements.**
`OpenAPIToolset` and `RestApiTool` have been enhanced with new features: `header_provider`, `ssl_verify`, and `tool_name_prefix`.
**Proposed Change**:
In `docs/tools-custom/openapi-tools.md`, add a new section for advanced configuration.
**Current state**:
The documentation explains the basic usage of `OpenAPIToolset`.
**Proposed Change**:
Add the following section:
```markdown
## Advanced Configuration
### Custom Headers with `header_provider`
You can provide a callable to `header_provider` to dynamically add custom headers to every API request. The callable receives the `ReadonlyContext` and should return a dictionary of headers.
```python
def my_header_provider(context: ReadonlyContext) -> dict[str, str]:
return {"X-Request-ID": context.invocation_id}
toolset = OpenAPIToolset(
spec_dict=openapi_spec,
header_provider=my_header_provider,
)
```
### SSL Certificate Verification with `ssl_verify`
You can configure SSL certificate verification for all tools in the toolset using the `ssl_verify` parameter. This is useful for environments with custom CA certificates.
```python
toolset = OpenAPIToolset(
spec_dict=openapi_spec,
ssl_verify="/path/to/ca.pem",
)
```
### Tool Name Prefix with `tool_name_prefix`
You can add a prefix to all tool names generated by the toolset using the `tool_name_prefix` parameter. This is useful for avoiding name collisions when using multiple OpenAPI specs.
```python
toolset = OpenAPIToolset(
spec_dict=openapi_spec,
tool_name_prefix="my_api",
)
```
```
**Reasoning**:
These new features provide more flexibility and control over the OpenAPI tools, and they should be documented.
**Reference**:
- `src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py`
- `src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py`
6. **[Feature] Document Spanner `QueryResultMode.DICT_LIST`.**
The Spanner tool now supports returning query results as a list of dictionaries.
**Proposed Change**:
In `docs/tools/built-in-tools.md`, update the Spanner section to include information about `QueryResultMode.DICT_LIST`.
**Current state**:
The documentation for the Spanner toolset is minimal.
**Proposed Change**:
Add the following to the Spanner section:
```markdown
The `execute_sql` tool can now return results as a list of dictionaries. To enable this, set `query_result_mode=QueryResultMode.DICT_LIST` in `SpannerToolSettings`.
```python
from google.adk.tools.spanner.settings import QueryResultMode, SpannerToolSettings
from google.adk.tools.spanner.spanner_toolset import SpannerToolset
tool_settings = SpannerToolSettings(query_result_mode=QueryResultMode.DICT_LIST)
spanner_toolset = SpannerToolset(spanner_tool_settings=tool_settings)
```
```
**Reasoning**:
This new feature provides a more convenient way to work with Spanner query results, and it should be documented.
**Reference**:
- `src/google/adk/tools/spanner/settings.py`
- `src/google/adk/tools/spanner/query_tool.py`
7. **[Feature] Document Application Integration `connection_template_override`.**
The `ApplicationIntegrationToolset` now has a `connection_template_override` parameter.
**Proposed Change**:
In `docs/tools/google-cloud-tools.md`, update the `ApplicationIntegrationToolset` section.
**Current state**:
The documentation for `ApplicationIntegrationToolset` does not mention this parameter.
**Proposed Change**:
Add a note about the `connection_template_override` parameter to the `ApplicationIntegrationToolset` section.
```python
connector_tool = ApplicationIntegrationToolset(
project="test-project",
location="us-central1",
connection="test-connection",
connection_template_override="MyExecuteConnection",
)
```
**Reasoning**:
This new parameter allows users to override the default connection template, which should be documented.
**Reference**:
- `src/google/adk/tools/application_integration_tool/application_integration_toolset.py`
8. **[Feature] Document JSON Schema for Function Tool Declaration.**
A new feature has been added to `build_function_declaration` that uses Pydantic's JSON schema generation.
**Proposed Change**:
In `docs/tools-custom/function-tools.md`, add a new section.
**Current state**:
The documentation explains how to define function signatures.
**Proposed Change**:
Add a new section about the JSON schema-based function declaration.
```markdown
## Simplified Tool Declaration with JSON Schema (Experimental)
ADK now offers a simplified way to declare function tools by generating a JSON schema from your function's signature using Pydantic. This feature can be enabled via a feature flag.
When enabled, `build_function_declaration` will automatically generate a JSON schema for your function's parameters, which simplifies the declaration process and provides more accurate type information to the LLM.
This feature is currently experimental and can be enabled by setting the `ADK_ENABLE_JSON_SCHEMA_FOR_FUNC_DECL` environment variable to `true`.
```
**Reasoning**:
This new feature simplifies the process of creating function tools and should be documented.
**Reference**:
- `src/google/adk/tools/_automatic_function_calling_util.py`
- `src/google/adk/tools/_function_tool_declarations.py`
Contributor guide
Assessment
This issue has not been assessed yet.