From 55a9bf8d5dbb4eb46058b7359611263e181d655a Mon Sep 17 00:00:00 2001 From: Prashant Patare <35198693+prashantpatare@users.noreply.github.com> Date: Thu, 14 May 2026 03:29:56 +0530 Subject: [PATCH 1/3] docs: add integration guide for Agent Identity Auth Manager (#1755) * docs: add integration guide for Agent Identity Auth Manager * docs: reformat agent-identity.md to match integration guidelines * docs: update agent-identity.md based on review * docs: add icon for agent identity integration * docs: fix icon format for agent identity integration * Edits to Agent Identity integration page for docs conventions * Revise agent-identity.md for clarity and updates Updated the documentation for the Agent Identity Auth Manager to clarify features and improve readability. * Revise Agent Identity documentation for OAuth flow Updated the Agent Identity documentation for clarity and added details on OAuth consent flow handling. * Refactor agent-identity.md for clarity and formatting Updated formatting and improved clarity in the documentation for the Agent Identity Auth Manager. * Clarify OAuth consent flow and credential handling Updated the OAuth consent flow section for clarity and added details on handling the continue URI and credential finalization. * Refine text for clarity in agent-identity.md Clarify language and improve readability in the Agent Identity documentation. * Update Agent Identity auth provider configuration details Revised instructions for configuring the Agent Identity auth provider and handling user consent flow, including code examples and clarifications. * add proper spacing * Updated card title and formatting * Update agent-identity.md --------- Co-authored-by: Prashant Patare Co-authored-by: Kristopher Overholt Co-authored-by: Joe Fernandez --- docs/integrations/agent-identity.md | 131 ++++++++++++++++++++ docs/integrations/assets/agent-identity.svg | 10 ++ 2 files changed, 141 insertions(+) create mode 100644 docs/integrations/agent-identity.md create mode 100644 docs/integrations/assets/agent-identity.svg diff --git a/docs/integrations/agent-identity.md b/docs/integrations/agent-identity.md new file mode 100644 index 0000000000..ea27834caf --- /dev/null +++ b/docs/integrations/agent-identity.md @@ -0,0 +1,131 @@ +--- +catalog_title: Google Cloud Agent Identity +catalog_description: Manage OAuth tokens and API keys for your agents +catalog_icon: /integrations/assets/agent-identity.svg +catalog_tags: ["google"] +--- + +# Agent Identity Auth Manager for ADK + +
+ Supported in ADKPython v1.30.0Preview +
+ +The [Google Cloud Agent +Identity](https://docs.cloud.google.com/iam/docs/agent-identity-overview) +service provides a streamlined, Google-managed solution for managing the +complete lifecycle of auth credentials, including storing credential +configurations, generating and storing tokens, and auditing access. This +approach allows for a secure and simplified agent development experience. + +!!! example "Preview release" + + The Agent Identity Auth Manager feature is a Preview release. For more + information, see the [launch stage + descriptions](https://cloud.google.com/products#product-launch-stages). + +## Use cases + +- **Simplified OAuth Flow**: Manage the complete lifecycle of auth credentials + without building custom infrastructure. +- **Secure Exchange and Storage of Tokens**: Securely store credential + configurations and exchange tokens. +- **Audit Logging**: View and audit access to stored credentials. + +## Prerequisites + +- A [Google Cloud + project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) +- One or more Agent Identity [auth + providers](https://cloud.google.com/iam/docs/manage-auth-providers) created in + your project +- The caller identity must have the + [`iamconnectors.user`](https://docs.cloud.google.com/iam/docs/roles-permissions/iamconnectors#iamconnectors.user) + role or equivalent permissions +- Authentication configured via [Application Default + Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials) + (`gcloud auth application-default login`) + +## Installation + +Install the `agent-identity` extra package group to download the necessary +client libraries. + +```bash +pip install "google-adk[agent-identity]" +``` + +## Use with agent + +Follow these steps to use the Agent Identity Auth Manager within ADK: + +### Register auth provider + +To enable ADK to determine which `BaseAuthProvider` to use for a given +`CustomAuthScheme`, register the `GcpAuthProvider` instance with the +`CredentialManager`. This needs to be done only once in the agent code. + +```python +from google.adk.auth.credential_manager import CredentialManager +from google.adk.integrations.agent_identity import GcpAuthProvider + +CredentialManager.register_auth_provider(GcpAuthProvider()) +``` + +### Configure tools + +Configure the Agent Identity auth provider using a `GcpAuthProviderScheme` +object, then pass it to the `auth_scheme` parameter of any supported `Tool` or +`Toolset`. The following example shows usage with `McpToolset`, but +`GcpAuthProviderScheme` also works with other tools like +`AuthenticatedFunctionTool`. See the [GCP Auth +sample](https://github.com/google/adk-python/tree/main/contributing/samples/gcp_auth) +for a complete example. + +```python +from google.adk.integrations.agent_identity import GcpAuthProviderScheme +from google.adk.tools.mcp import McpToolset + +auth_scheme = GcpAuthProviderScheme( + name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME", + # continue_uri is only needed for 3-legged OAuth flows. This URI receives + # the redirect after user consent and must be hosted by your application. + continue_uri=CONTINUE_URI +) + +toolset = McpToolset( + connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"), + auth_scheme=auth_scheme, +) +``` + +### Handle OAuth consent + +- **Detecting the Auth Request**: Similar to the existing flow, whenever user + consent is required, a `FunctionCall` event named `adk-request-credential` + is generated containing the `auth_uri` field. The user app should open + the `auth_uri` in a popup window to continue the user consent flow. +- **Continue URI Handler**: + - Once the user completes the OAuth consent flow on the third-party + provider's website, the system redirects to the `continue_uri` + callback defined earlier in the `GcpAuthProviderScheme`. The agent + application service must implement this redirect. To finalize issuance, + your handler must submit a POST request to the credentials endpoint: + `https://iamconnectorcredentials.googleapis.com/v1alpha/{connector_name}/credentials:finalize`. + - After credentials are successfully finalized, the web application should + resume the agent by sending a FunctionResponse. For a sample + implementation, refer to the [sample + code](https://docs.cloud.google.com/iam/docs/auth-with-3lo#resume-conversation). + Unlike the native user consent flow, no authorization code is required to + resume the agent. + - For more details, refer to the [sample handler + implementation](https://docs.cloud.google.com/iam/docs/auth-with-3lo#validation-endpoint). +- **Resume the conversation**: Irrespective of the status of the consent flow + (successful or unsuccessful), the agent app should resume the agent to + complete the conversation turn. The ADK automatically determines whether + consent was successfully completed and raise an error if it was not. + +## Resources + +- [Google Cloud Agent Identity Overview](https://docs.cloud.google.com/iam/docs/agent-identity-overview) +- [Sample agent code](https://github.com/google/adk-python/tree/main/contributing/samples/gcp_auth) diff --git a/docs/integrations/assets/agent-identity.svg b/docs/integrations/assets/agent-identity.svg new file mode 100644 index 0000000000..dfc631a44b --- /dev/null +++ b/docs/integrations/assets/agent-identity.svg @@ -0,0 +1,10 @@ + + + + + + + + + + From 47896dd8500bb7174248fbebf25e9b628249891a Mon Sep 17 00:00:00 2001 From: Kristopher Overholt Date: Wed, 13 May 2026 17:55:28 -0500 Subject: [PATCH 2/3] Update CLI reference docs for ADK 1.33.0 (#1752) --- docs/api-reference/cli/_sources/index.rst.txt | 2 +- .../cli/_static/documentation_options.js | 2 +- docs/api-reference/cli/genindex.html | 4 ++-- docs/api-reference/cli/index.html | 10 +++++----- docs/api-reference/cli/objects.inv | Bin 2111 -> 2111 bytes docs/api-reference/cli/search.html | 4 ++-- 6 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/api-reference/cli/_sources/index.rst.txt b/docs/api-reference/cli/_sources/index.rst.txt index 99a05d1f5a..30119d3206 100644 --- a/docs/api-reference/cli/_sources/index.rst.txt +++ b/docs/api-reference/cli/_sources/index.rst.txt @@ -1,7 +1,7 @@ ADK CLI documentation ===================== -This page contains the auto-generated command-line reference for ADK 1.32.0. +This page contains the auto-generated command-line reference for ADK 1.33.0. .. contents:: :local: diff --git a/docs/api-reference/cli/_static/documentation_options.js b/docs/api-reference/cli/_static/documentation_options.js index 255a4578a8..689193966e 100644 --- a/docs/api-reference/cli/_static/documentation_options.js +++ b/docs/api-reference/cli/_static/documentation_options.js @@ -1,5 +1,5 @@ const DOCUMENTATION_OPTIONS = { - VERSION: '1.32.0', + VERSION: '1.33.0', LANGUAGE: 'en', COLLAPSE_INDEX: false, BUILDER: 'html', diff --git a/docs/api-reference/cli/genindex.html b/docs/api-reference/cli/genindex.html index ee7ce0275d..c76897bf85 100644 --- a/docs/api-reference/cli/genindex.html +++ b/docs/api-reference/cli/genindex.html @@ -4,11 +4,11 @@ - Index — ADK CLI 1.32.0 documentation + Index — ADK CLI 1.33.0 documentation - + diff --git a/docs/api-reference/cli/index.html b/docs/api-reference/cli/index.html index 022a9304a3..83d1bad898 100644 --- a/docs/api-reference/cli/index.html +++ b/docs/api-reference/cli/index.html @@ -5,11 +5,11 @@ - ADK CLI documentation — ADK CLI 1.32.0 documentation + ADK CLI documentation — ADK CLI 1.33.0 documentation - + @@ -43,7 +43,7 @@

ADK CLI documentationΒΆ

-

This page contains the auto-generated command-line reference for ADK 1.32.0.

+

This page contains the auto-generated command-line reference for ADK 1.33.0.