encounter/adk-python
0
0
Fork 0
mirror of https://github.com/encounter/adk-python.git synced 2026-07-09 18:19:28 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: Fix docstring and update module public name list for generating API references

Browse Source 
To fix https://github.com/google/adk-docs/issues/131

PiperOrigin-RevId: 783080206
This commit is contained in:
Xiang (Sean) Zhou
2025-07-14 16:16:57 -07:00
committed by Copybara-Service
parent 62a611956f
commit dea1ee14ab
15 changed files with 168 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/google/adk/agents/__init__.py
+5
View File
@@ -13,6 +13,7 @@
# limitations under the License.
from .base_agent import BaseAgent
from .invocation_context import InvocationContext
from .live_request_queue import LiveRequest
from .live_request_queue import LiveRequestQueue
from .llm_agent import Agent
@@ -29,4 +30,8 @@ __all__ = [
'LoopAgent',
'ParallelAgent',
'SequentialAgent',
'InvocationContext',
'LiveRequest',
'LiveRequestQueue',
'RunConfig',
]
src/google/adk/agents/invocation_context.py
+1 -1
View File
@@ -149,7 +149,7 @@ class InvocationContext(BaseModel):
"""The running streaming tools of this invocation."""
transcription_cache: Optional[list[TranscriptionEntry]] = None
"""Caches necessary, data audio or contents, that are needed by transcription."""
"""Caches necessary data, audio or contents, that are needed by transcription."""
run_config: Optional[RunConfig] = None
"""Configurations for live agents under this invocation."""
src/google/adk/agents/llm_agent.py
+11 -9
View File
@@ -168,9 +168,9 @@ class LlmAgent(BaseAgent):
"""Controls content inclusion in model requests.
Options:
default: Model receives relevant conversation history
none: Model receives no prior history, operates solely on current
instruction and input
default: Model receives relevant conversation history
none: Model receives no prior history, operates solely on current
instruction and input
"""
# Controlled input/output configurations - Start
@@ -179,8 +179,9 @@ class LlmAgent(BaseAgent):
output_schema: Optional[type[BaseModel]] = None
"""The output schema when agent replies.
NOTE: when this is set, agent can ONLY reply and CANNOT use any tools, such as
function tools, RAGs, agent transfer, etc.
NOTE:
When this is set, agent can ONLY reply and CANNOT use any tools, such as
function tools, RAGs, agent transfer, etc.
"""
output_key: Optional[str] = None
"""The key in session state to store the output of the agent.
@@ -195,9 +196,9 @@ class LlmAgent(BaseAgent):
planner: Optional[BasePlanner] = None
"""Instructs the agent to make a plan and execute it step by step.
NOTE: to use model's built-in thinking features, set the `thinking_config`
field in `google.adk.planners.built_in_planner`.
NOTE:
To use model's built-in thinking features, set the `thinking_config`
field in `google.adk.planners.built_in_planner`.
"""
code_executor: Optional[BaseCodeExecutor] = None
@@ -206,7 +207,8 @@ class LlmAgent(BaseAgent):
Check out available code executions in `google.adk.code_executor` package.
NOTE: to use model's built-in code executor, use the `BuiltInCodeExecutor`.
NOTE:
To use model's built-in code executor, use the `BuiltInCodeExecutor`.
"""
# Advance features - End
src/google/adk/code_executors/base_code_executor.py
+14 -19
View File
@@ -12,6 +12,8 @@
# See the License for the specific language governing permissions and
# limitations under the License.
from __future__ import annotations
import abc
from typing import List
@@ -42,42 +44,35 @@ class BaseCodeExecutor(BaseModel):
"""
optimize_data_file: bool = False
"""
If true, extract and process data files from the model request
"""If true, extract and process data files from the model request
and attach them to the code executor.
Supported data file MimeTypes are [text/csv].
Supported data file MimeTypes are [text/csv].
Default to False.
"""
stateful: bool = False
"""
Whether the code executor is stateful. Default to False.
"""
"""Whether the code executor is stateful. Default to False."""
error_retry_attempts: int = 2
"""
The number of attempts to retry on consecutive code execution errors. Default to 2.
"""
"""The number of attempts to retry on consecutive code execution errors. Default to 2."""
code_block_delimiters: List[tuple[str, str]] = [
('```tool_code\n', '\n```'),
('```python\n', '\n```'),
]
"""
The list of the enclosing delimiters to identify the code blocks.
For example, the delimiter ('```python\n', '\n```') can be
used to identify code blocks with the following format:
"""The list of the enclosing delimiters to identify the code blocks.
```python
print("hello")
```
For example, the delimiter ('```python\\n', '\\n```') can be
used to identify code blocks with the following format::
```python
print("hello")
```
"""
execution_result_delimiters: tuple[str, str] = ('```tool_output\n', '\n```')
"""
The delimiters to format the code execution result.
"""
"""The delimiters to format the code execution result."""
@abc.abstractmethod
def execute_code(
src/google/adk/runners.py
+6 -4
View File
@@ -122,8 +122,9 @@ class Runner:
) -> Generator[Event, None, None]:
"""Runs the agent.
NOTE: This sync interface is only for local testing and convenience purpose.
Consider using `run_async` for production usage.
NOTE:
This sync interface is only for local testing and convenience purpose.
Consider using `run_async` for production usage.
Args:
user_id: The user ID of the session.
@@ -350,7 +351,7 @@ class Runner:
This feature is **experimental** and its API or behavior may change
in future releases.
.. note::
.. NOTE::
Either `session` or both `user_id` and `session_id` must be provided.
"""
if session is None and (user_id is None or session_id is None):
@@ -433,9 +434,10 @@ class Runner:
"""Finds the agent to run to continue the session.
A qualified agent must be either of:
- The agent that returned a function call and the last user message is a
function response to this function call.
- The root agent;
- The root agent.
- An LlmAgent who replied last and is capable to transfer to any other agent
in the agent hierarchy.
src/google/adk/tools/apihub_tool/apihub_toolset.py
+38 -39
View File
@@ -35,27 +35,25 @@ from .clients.apihub_client import APIHubClient
class APIHubToolset(BaseToolset):
"""APIHubTool generates tools from a given API Hub resource.
Examples:
Examples::
```
apihub_toolset = APIHubToolset(
apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
service_account_json="...",
tool_filter=lambda tool, ctx=None: tool.name in ('my_tool',
'my_other_tool')
)
apihub_toolset = APIHubToolset(
apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
service_account_json="...",
tool_filter=lambda tool, ctx=None: tool.name in ('my_tool',
'my_other_tool')
)
# Get all available tools
agent = LlmAgent(tools=apihub_toolset)
```
# Get all available tools
agent = LlmAgent(tools=apihub_toolset)
**apihub_resource_name** is the resource name from API Hub. It must include
API name, and can optionally include API version and spec name.
- If apihub_resource_name includes a spec resource name, the content of that
spec will be used for generating the tools.
- If apihub_resource_name includes only an api or a version name, the
first spec of the first version of that API will be used.
API name, and can optionally include API version and spec name.
- If apihub_resource_name includes a spec resource name, the content of that
spec will be used for generating the tools.
- If apihub_resource_name includes only an api or a version name, the
first spec of the first version of that API will be used.
"""
def __init__(
@@ -78,44 +76,45 @@ class APIHubToolset(BaseToolset):
):
"""Initializes the APIHubTool with the given parameters.
Examples:
```
apihub_toolset = APIHubToolset(
apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
service_account_json="...",
)
Examples::
# Get all available tools
agent = LlmAgent(tools=[apihub_toolset])
apihub_toolset = APIHubToolset(
apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
service_account_json="...",
)
apihub_toolset = APIHubToolset(
apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
service_account_json="...",
tool_filter = ['my_tool']
)
# Get a specific tool
agent = LlmAgent(tools=[
...,
apihub_toolset,
])
```
# Get all available tools
agent = LlmAgent(tools=[apihub_toolset])
apihub_toolset = APIHubToolset(
apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
service_account_json="...",
tool_filter = ['my_tool']
)
# Get a specific tool
agent = LlmAgent(tools=[
...,
apihub_toolset,
])
**apihub_resource_name** is the resource name from API Hub. It must include
API name, and can optionally include API version and spec name.
- If apihub_resource_name includes a spec resource name, the content of that
spec will be used for generating the tools.
- If apihub_resource_name includes only an api or a version name, the
first spec of the first version of that API will be used.
Example:
* projects/xxx/locations/us-central1/apis/apiname/...
* https://console.cloud.google.com/apigee/api-hub/apis/apiname?project=xxx
Args:
apihub_resource_name: The resource name of the API in API Hub.
Example: `projects/test-project/locations/us-central1/apis/test-api`.
access_token: Google Access token. Generate with gcloud cli `gcloud auth
auth print-access-token`. Used for fetching API Specs from API Hub.
Example: ``projects/test-project/locations/us-central1/apis/test-api``.
access_token: Google Access token. Generate with gcloud cli
``gcloud auth auth print-access-token``. Used for fetching API Specs from API Hub.
service_account_json: The service account config as a json string.
Required if not using default service credential. It is used for
creating the API Hub client and fetching the API Specs from API Hub.
src/google/adk/tools/application_integration_tool/application_integration_toolset.py
+35 -37
View File
@@ -12,6 +12,8 @@
# See the License for the specific language governing permissions and
# limitations under the License.
from __future__ import annotations
import logging
from typing import List
from typing import Optional
@@ -42,43 +44,39 @@ logger = logging.getLogger("google_adk." + __name__)
# TODO(cheliu): Apply a common toolset interface
class ApplicationIntegrationToolset(BaseToolset):
"""ApplicationIntegrationToolset generates tools from a given Application
Integration or Integration Connector resource.
Example Usage:
```
# Get all available tools for an integration with api trigger
application_integration_toolset = ApplicationIntegrationToolset(
project="test-project",
location="us-central1"
integration="test-integration",
triggers=["api_trigger/test_trigger"],
service_account_credentials={...},
)
Example Usage::
# Get all available tools for a connection using entity operations and
# actions
# Note: Find the list of supported entity operations and actions for a
connection
# using integration connector apis:
#
https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata
application_integration_toolset = ApplicationIntegrationToolset(
project="test-project",
location="us-central1"
connection="test-connection",
entity_operations=["EntityId1": ["LIST","CREATE"], "EntityId2": []],
#empty list for actions means all operations on the entity are supported
actions=["action1"],
service_account_credentials={...},
)
# Get all available tools for an integration with api trigger
application_integration_toolset = ApplicationIntegrationToolset(
project="test-project",
location="us-central1"
integration="test-integration",
triggers=["api_trigger/test_trigger"],
service_account_credentials={...},
)
# Feed the toolset to agent
agent = LlmAgent(tools=[
...,
application_integration_toolset,
])
```
# Get all available tools for a connection using entity operations and
# actions
# Note: Find the list of supported entity operations and actions for a
# connection using integration connector apis:
# https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata
application_integration_toolset = ApplicationIntegrationToolset(
project="test-project",
location="us-central1"
connection="test-connection",
entity_operations=["EntityId1": ["LIST","CREATE"], "EntityId2": []],
#empty list for actions means all operations on the entity are supported
actions=["action1"],
service_account_credentials={...},
)
# Feed the toolset to agent
agent = LlmAgent(tools=[
...,
application_integration_toolset,
])
"""
def __init__(
@@ -122,11 +120,11 @@ class ApplicationIntegrationToolset(BaseToolset):
Raises:
ValueError: If none of the following conditions are met:
- `integration` is provided.
- `connection` is provided and at least one of `entity_operations`
or `actions` is provided.
- ``integration`` is provided.
- ``connection`` is provided and at least one of ``entity_operations``
or ``actions`` is provided.
Exception: If there is an error during the initialization of the
integration or connection client.
integration or connection client.
"""
super().__init__(tool_filter=tool_filter)
self.project = project
src/google/adk/tools/application_integration_tool/integration_connector_tool.py
+2 -3
View File
@@ -45,13 +45,12 @@ class IntegrationConnectorTool(BaseTool):
* Generates request params and body
* Attaches auth credentials to API call.
Example:
```
Example::
# Each API operation in the spec will be turned into its own tool
# Name of the tool is the operationId of that operation, in snake case
operations = OperationGenerator().parse(openapi_spec_dict)
tool = [RestApiTool.from_parsed_operation(o) for o in operations]
```
"""
EXCLUDE_FIELDS = [
src/google/adk/tools/base_tool.py
+9 -9
View File
@@ -49,11 +49,11 @@ class BaseTool(ABC):
def _get_declaration(self) -> Optional[types.FunctionDeclaration]:
"""Gets the OpenAPI specification of this tool in the form of a FunctionDeclaration.
NOTE
- Required if subclass uses the default implementation of
`process_llm_request` to add function declaration to LLM request.
- Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
Gemini.
NOTE:
- Required if subclass uses the default implementation of
`process_llm_request` to add function declaration to LLM request.
- Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
Gemini.
Returns:
The FunctionDeclaration of this tool, or None if it doesn't need to be
@@ -66,10 +66,10 @@ class BaseTool(ABC):
) -> Any:
"""Runs the tool with the given arguments and context.
NOTE
- Required if this tool needs to run at the client side.
- Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
Gemini.
NOTE:
- Required if this tool needs to run at the client side.
- Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
Gemini.
Args:
args: The LLM-filled arguments.
src/google/adk/tools/base_toolset.py
+5 -4
View File
@@ -76,10 +76,11 @@ class BaseToolset(ABC):
async def close(self) -> None:
"""Performs cleanup and releases resources held by the toolset.
NOTE: This method is invoked, for example, at the end of an agent server's
lifecycle or when the toolset is no longer needed. Implementations
should ensure that any open connections, files, or other managed
resources are properly released to prevent leaks.
NOTE:
This method is invoked, for example, at the end of an agent server's
lifecycle or when the toolset is no longer needed. Implementations
should ensure that any open connections, files, or other managed
resources are properly released to prevent leaks.
"""
def _is_tool_selected(
src/google/adk/tools/bigquery/__init__.py
+3 -3
View File
@@ -20,11 +20,11 @@ definition. The rationales to have customized tool are:
1. BigQuery APIs have functions overlaps and LLM can't tell what tool to use
2. BigQuery APIs have a lot of parameters with some rarely used, which are not
LLM-friendly
LLM-friendly
3. We want to provide more high-level tools like forecasting, RAG, segmentation,
etc.
etc.
4. We want to provide extra access guardrails in those tools. For example,
execute_sql can't arbitrarily mutate existing data.
execute_sql can't arbitrarily mutate existing data.
"""
from .bigquery_credentials import BigQueryCredentialsConfig
src/google/adk/tools/langchain_tool.py
+2 -3
View File
@@ -41,14 +41,13 @@ class LangchainTool(FunctionTool):
name: Optional override for the tool's name
description: Optional override for the tool's description
Examples:
```python
Examples::
from langchain.tools import DuckDuckGoSearchTool
from google.genai.tools import LangchainTool
search_tool = DuckDuckGoSearchTool()
wrapped_tool = LangchainTool(search_tool)
```
"""
_langchain_tool: Union[BaseTool, object]
src/google/adk/tools/mcp_tool/mcp_toolset.py
+25 -26
View File
@@ -61,28 +61,27 @@ class MCPToolset(BaseToolset):
that can be used by an agent. It properly implements the BaseToolset
interface for easy integration with the agent framework.
Usage:
```python
toolset = MCPToolset(
connection_params=StdioServerParameters(
command='npx',
args=["-y", "@modelcontextprotocol/server-filesystem"],
),
tool_filter=['read_file', 'list_directory'] # Optional: filter specific tools
)
Usage::
# Use in an agent
agent = LlmAgent(
model='gemini-2.0-flash',
name='enterprise_assistant',
instruction='Help user accessing their file systems',
tools=[toolset],
)
toolset = MCPToolset(
connection_params=StdioServerParameters(
command='npx',
args=["-y", "@modelcontextprotocol/server-filesystem"],
),
tool_filter=['read_file', 'list_directory'] # Optional: filter specific tools
)
# Cleanup is handled automatically by the agent framework
# But you can also manually close if needed:
# await toolset.close()
```
# Use in an agent
agent = LlmAgent(
model='gemini-2.0-flash',
name='enterprise_assistant',
instruction='Help user accessing their file systems',
tools=[toolset],
)
# Cleanup is handled automatically by the agent framework
# But you can also manually close if needed:
# await toolset.close()
"""
def __init__(
@@ -103,12 +102,12 @@ class MCPToolset(BaseToolset):
Args:
connection_params: The connection parameters to the MCP server. Can be:
`StdioConnectionParams` for using local mcp server (e.g. using `npx` or
`python3`); or `SseConnectionParams` for a local/remote SSE server; or
`StreamableHTTPConnectionParams` for local/remote Streamable http
server. Note, `StdioServerParameters` is also supported for using local
mcp server (e.g. using `npx` or `python3` ), but it does not support
timeout, and we recommend to use `StdioConnectionParams` instead when
``StdioConnectionParams`` for using local mcp server (e.g. using ``npx`` or
``python3``); or ``SseConnectionParams`` for a local/remote SSE server; or
``StreamableHTTPConnectionParams`` for local/remote Streamable http
server. Note, ``StdioServerParameters`` is also supported for using local
mcp server (e.g. using ``npx`` or ``python3`` ), but it does not support
timeout, and we recommend to use ``StdioConnectionParams`` instead when
timeout is needed.
tool_filter: Optional filter to select specific tools. Can be either: - A
list of tool names to include - A ToolPredicate function for custom
src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py
+8 -8
View File
@@ -12,6 +12,8 @@
# See the License for the specific language governing permissions and
# limitations under the License.
from __future__ import annotations
import json
import logging
from typing import Any
@@ -39,8 +41,8 @@ logger = logging.getLogger("google_adk." + __name__)
class OpenAPIToolset(BaseToolset):
"""Class for parsing OpenAPI spec into a list of RestApiTool.
Usage:
```
Usage::
# Initialize OpenAPI toolset from a spec string.
openapi_toolset = OpenAPIToolset(spec_str=openapi_spec_str,
spec_str_type="json")
@@ -55,7 +57,6 @@ class OpenAPIToolset(BaseToolset):
agent = Agent(
tools=[openapi_toolset.get_tool('tool_name')]
)
```
"""
def __init__(
@@ -70,8 +71,8 @@ class OpenAPIToolset(BaseToolset):
):
"""Initializes the OpenAPIToolset.
Usage:
```
Usage::
# Initialize OpenAPI toolset from a spec string.
openapi_toolset = OpenAPIToolset(spec_str=openapi_spec_str,
spec_str_type="json")
@@ -86,7 +87,6 @@ class OpenAPIToolset(BaseToolset):
agent = Agent(
tools=[openapi_toolset.get_tool('tool_name')]
)
```
Args:
spec_dict: The OpenAPI spec dictionary. If provided, it will be used
@@ -96,10 +96,10 @@ class OpenAPIToolset(BaseToolset):
spec_str_type: The type of the OpenAPI spec string. Can be "json" or
"yaml".
auth_scheme: The auth scheme to use for all tools. Use AuthScheme or use
helpers in `google.adk.tools.openapi_tool.auth.auth_helpers`
helpers in ``google.adk.tools.openapi_tool.auth.auth_helpers``
auth_credential: The auth credential to use for all tools. Use
AuthCredential or use helpers in
`google.adk.tools.openapi_tool.auth.auth_helpers`
``google.adk.tools.openapi_tool.auth.auth_helpers``
tool_filter: The filter used to filter the tools in the toolset. It can be
either a tool predicate or a list of tool names of the tools to expose.
"""
src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py
+4 -6
View File
@@ -70,13 +70,12 @@ class RestApiTool(BaseTool):
* Generates request params and body
* Attaches auth credentials to API call.
Example:
```
Example::
# Each API operation in the spec will be turned into its own tool
# Name of the tool is the operationId of that operation, in snake case
operations = OperationGenerator().parse(openapi_spec_dict)
tool = [RestApiTool.from_parsed_operation(o) for o in operations]
```
"""
def __init__(
@@ -92,13 +91,12 @@ class RestApiTool(BaseTool):
"""Initializes the RestApiTool with the given parameters.
To generate RestApiTool from OpenAPI Specs, use OperationGenerator.
Example:
```
Example::
# Each API operation in the spec will be turned into its own tool
# Name of the tool is the operationId of that operation, in snake case
operations = OperationGenerator().parse(openapi_spec_dict)
tool = [RestApiTool.from_parsed_operation(o) for o in operations]
```
Hint: Use google.adk.tools.openapi_tool.auth.auth_helpers to construct
auth_scheme and auth_credential.