docs(integrations): fix unresolvable imports and stale API claims - #2031
docs(integrations): fix unresolvable imports and stale API claims#2031GWeale wants to merge 1 commit into
Conversation
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
koverholt
left a comment
koverholt
left a comment
There was a problem hiding this comment.
Thanks for the PR and fixes throughout the integration pages. 🎉 There are lots of excellent finds in here, like bad imports, deprecated APIs, and settings that are now default and no longer need to be set explicitly.
I left some inline comments to address/fix: one blocking issue in gcs.md and a naming/wording fix in cloud-trace.md, plus minor non-blocking comments in code-exec-agent-runtime.md and reflect-and-retry.md.
| === "Python" | ||
|
|
||
| If you are using the `AdkApp` abstraction, you can enable cloud tracing by adding `enable_tracing=True`: | ||
| If you are using the Vertex AI SDK `AdkApp` abstraction, you can enable cloud tracing by adding `enable_tracing=True`: |
There was a problem hiding this comment.
Since the platform rename from "Vertex AI" to "Agent Platform" a few months ago (#1673), we're avoiding adding any new instances of "Vertex AI" to the docs in prose (realizing that vertexai will still appear in some literal code and imports), so either replace this with:
the Agent Platform SDK
AdkAppabstraction
or revert to:
the
AdkAppabstraction
| ``` | ||
| The output will be presented to you as: | ||
| ```tool_outputs | ||
| ```tool_output |
There was a problem hiding this comment.
This is a great find, and the changes in this PR are correct. No changes need here.
Just a heads-up that the upstream sample this is based on (https://github.com/google/adk-python/blob/main/contributing/samples/code_execution/agent_engine_code_execution/agent.py) still has the same bug in that it uses the tool_outputs delimiter instead of tool_output.
|
|
||
| With this configuration, if any tool called by an agent returns an error, the | ||
| request is updated and tried again, up to a maximum of 3 attempts, per tool. | ||
| With this configuration, if any tool called by an agent *raises* an exception, |
There was a problem hiding this comment.
Wording nit: "raises an exception" is Python phrasing, but this page has support for both Python and Go. Could we make it language-neutral?
| * **`throw_exception_if_retry_exceeded`**: (optional) If set to `False`, the | ||
| system does not raise an error if the final retry attempt fails. Default | ||
| value is `True`. |
There was a problem hiding this comment.
Not introduced by this PR, but throw_exception_if_retry_exceeded defaulting to True is the Python default. The Go equivalent WithErrorIfRetryExceeded defaults to false, so the two SDKs behave differently once retries are exhausted (Python raises the original error; Go returns a guidance message instead). There are other issues on this page that apply only to Python and don't refer to how the Go SDK handles this, so this is not a blocker for this PR, optionally cleanup here or we can address in a future PR.
| * **`tracking_scope`**: (optional) A `TrackingScope` value, imported from | ||
| `google.adk.plugins.reflect_retry_tool_plugin` (it is not re-exported from | ||
| `google.adk.plugins`): |
There was a problem hiding this comment.
This parenthetical:
(it is not re-exported from
google.adk.plugins)
reads a bit like a review note. Since the bullet already gives the exact import path, the "not re-exported" clause is redundant. Suggest dropping it.
| ### GCS Storage Tools (`GCSToolset`) | ||
|
|
||
| Tool | Description | ||
| ---- | ----------- | ||
| `gcs_get_bucket` | Get metadata information about a GCS bucket. | ||
| `gcs_list_objects` | List object names in a GCS bucket. Supports optional prefix filtering and pagination. | ||
| `gcs_get_object_metadata` | Get metadata properties of a specific GCS object (blob). | ||
| `gcs_create_object` | Create a new object (blob) in a bucket from in-memory string data or a local file upload. | ||
| `gcs_get_object_data` | Get content of a GCS object as a string, or download it directly to a local file. | ||
| `gcs_delete_objects` | Delete multiple GCS objects (blobs) from a bucket. | ||
| `get_bucket` | Get metadata information about a GCS bucket. | ||
| `list_objects` | List object names in a GCS bucket. Supports optional prefix filtering and pagination. | ||
| `get_object_metadata` | Get metadata properties of a specific GCS object (blob). | ||
| `create_object` | Create a new object (blob) in a bucket from in-memory string data or a local file upload. Requires `Capabilities.READ_WRITE`. | ||
| `get_object_data` | Get content of a GCS object as a string, or download it directly to a local file. | ||
| `delete_objects` | Delete multiple GCS objects (blobs) from a bucket. Requires `Capabilities.READ_WRITE`. | ||
|
|
||
| ### GCS Admin Tools (`GCSAdminToolset`) | ||
|
|
||
| Tool | Description | ||
| ---- | ----------- | ||
| `gcs_list_buckets` | List GCS bucket names in a Google Cloud project. | ||
| `gcs_create_bucket` | Create a new GCS bucket in a specific location. | ||
| `gcs_update_bucket` | Update properties of a GCS bucket (e.g. versioning or uniform bucket-level access). | ||
| `gcs_delete_bucket` | Delete a GCS bucket (bucket must be empty first). | ||
| `list_buckets` | List GCS bucket names in a Google Cloud project. | ||
| `create_bucket` | Create a new GCS bucket in a specific location. Requires `Capabilities.READ_WRITE`. | ||
| `update_bucket` | Update properties of a GCS bucket (e.g. versioning or uniform bucket-level access). Requires `Capabilities.READ_WRITE`. | ||
| `delete_bucket` | Delete a GCS bucket (bucket must be empty first). Requires `Capabilities.READ_WRITE`. |
There was a problem hiding this comment.
This change is incorrect and should be reverted. It makes the tool tables no longer match the actual tool names, so please restore the gcs_ prefixes before merging.
These tables list the tools as exposed to the model, and those names keep the gcs_ prefix. GCSToolset/GCSAdminToolset set tool_name_prefix="gcs", and LlmAgent calls get_tools_with_prefix(), so the function declarations the model receives are gcs_get_bucket, gcs_list_buckets, etc. (matching the upstream sample READMEs). Removing the prefix here makes the table no longer match what the model sees or what shows up in traces.
I think the confusion is that tool_filter matches the unprefixed names (filtering happens in get_tools() before the prefix is applied), so tool_filter=['gcs_get_bucket'] yields an empty toolset while ['get_bucket'] works. That's a real issue, but it's about tool_filter and this page doesn't use tool_filter anywhere.
Could we restore the gcs_ prefixes in both tables, keep the new Requires Capabilities.READ_WRITE notes (those are correct), and add a note/callout below the table to capture the difference:
!!! note
The tool names listed here are the ones exposed to the model (prefixed with `gcs_`).
When using `tool_filter`, reference the unprefixed names such as `get_bucket`.
2 participants
18 integration pages documented imports that raise, methods with the wrong
signature, or tool names that do not exist. Verified against
google/adk-python@ main — every rewritten import was executed, and everysignature and default introspected. 56 Python blocks, 0 syntax failures after
(2 before).
Imports and calls that could not work
agent-identity.md—google.adk.tools.mcpdoes not exist; it isgoogle.adk.tools.mcp_tool. Also adds the missingStreamableHTTPConnectionParamsimport.agent-registry.md— the documented install could not importAgentRegistry:agent_registry.py:35imports agent-identityunconditionally at module scope. Now documents
pip install "google-adk[a2a,agent-identity]".apigee-api-hub.md—tools=toolset.get_tools()passed a coroutine(
APIHubToolset.get_toolsis async), raisingTypeError. Passes the toolset.cloud-trace.md—AdkAppisvertexai.agent_engines.AdkApp, notgoogle.adk.apps;maybe_set_otel_providerslives ingoogle.adk.telemetry.setupand is not re-exported.freeplay.md—Appis ingoogle.adk.apps, notgoogle.adk.runners.skills-registry.md—google.adk.integrations.gcp_skill_registrydoes notexist; the module is
google.adk.integrations.skill_registry.Claims that did not match the code
skills-registry.md—search_skills/get_skillareasyncandkeyword-only, and
get_skillhas noversionparameter.gcs.md— every documented tool name carried agcs_prefix the real toolslack, so the documented
tool_filteryielded an empty toolset.reflect-and-retry.md— a tool that returns an error is not retried bydefault (only raised exceptions are);
max_retries=3gives 4 attempts, not 3,which the page's own text already said;
TrackingScopeis not exported fromgoogle.adk.plugins.agent-registry.md—header_provideronly affectsget_mcp_toolset;RemoteA2aAgenthas no header field.application-integration.md—tool_name_prefix/tool_instructionsareaccepted and then discarded on the
integration=path.code-exec-agent-runtime.md— named a class that does not exist, and saidtool_outputswhere the executor emitstool_output.mlflow-scorers.md— the class isLLMRegistry, notLlmRegistry.api-registry.md—google.adk.tools.api_registryis deprecated in favour ofgoogle.adk.integrations.api_registry.windsor-ai.md—ADK_ENABLE_JSON_SCHEMA_FOR_FUNC_DECLis on by default andno longer needs setting.
temporal.md,computer-use.md,cisco-ai-defense.md— top-levelawait,unused imports, and
Appused without importing it.Also adds the
is_final_response()content guard where it was missing(
phoenix.md,future-agi.md).