diff --git a/docs/integrations/agent-identity.md b/docs/integrations/agent-identity.md new file mode 100644 index 0000000000..4346f34ae3 --- /dev/null +++ b/docs/integrations/agent-identity.md @@ -0,0 +1,78 @@ +--- +catalog_title: Agent Identity +catalog_description: Manage access-token lifecycle with the Google Cloud Agent Identity Credentials service +catalog_icon: /integrations/assets/adk.png +catalog_tags: ["auth", "google-cloud"] +--- + +# Agent Identity + +
+ Supported in ADKPython v1.31.0Experimental +
+ +Agent Identity manages the lifecycle of access tokens by using the Google Cloud +Agent Identity Credentials service. Use this integration when your agent needs +to authenticate to protected tools or services without implementing the full +credential retrieval and refresh flow yourself. + +## Install + +Install ADK with the Agent Identity extra: + +```bash +pip install "google-adk[agent-identity]" +``` + +## Register the provider + +Register `GcpAuthProvider` with the `CredentialManager` once during application +startup: + +```python +from google.adk.auth.credential_manager import CredentialManager +from google.adk.integrations.agent_identity import GcpAuthProvider + +CredentialManager.register_auth_provider(GcpAuthProvider()) +``` + +## Configure a toolset + +Use `GcpAuthProviderScheme` as the `auth_scheme` for a toolset that should use +Agent Identity credentials. The `name` value identifies the Agent Identity +provider configuration to use. + +```python +from google.adk.integrations.agent_identity import GcpAuthProviderScheme +from google.adk.tools.mcp_tool import McpToolset + +auth_scheme = GcpAuthProviderScheme(name="my-jira-auth-provider") + +mcp_toolset_jira = McpToolset( + # ... + auth_scheme=auth_scheme, +) +``` + +You can also pass scopes when the connected service requires them: + +```python +auth_scheme = GcpAuthProviderScheme( + name="my-jira-auth-provider", + scopes=["https://www.googleapis.com/auth/cloud-platform"], +) +``` + +## How it works + +When a tool uses `GcpAuthProviderScheme`, ADK delegates credential retrieval to +`GcpAuthProvider`. The provider calls the Agent Identity Credentials service +for the configured connector and current user, then returns an ADK +`AuthCredential` that the tool can use. + +Depending on the connector and credential type, the service can return +credentials immediately, require polling for a non-interactive OAuth flow, or +return a consent URL for a three-legged OAuth flow. + +For broader guidance on choosing between managed and self-managed credentials, +see [Authenticating with Tools](/tools-custom/authentication/). diff --git a/docs/tools-custom/authentication.md b/docs/tools-custom/authentication.md index 5514898b80..1025f3a3a3 100644 --- a/docs/tools-custom/authentication.md +++ b/docs/tools-custom/authentication.md @@ -137,6 +137,17 @@ specific interactive process with your ***Agent Client*** application. JSON key or Application Default Credentials. This type typically exchanges a Bearer token. +### Managed authentication with Agent Identity + +If you use Google Cloud Agent Identity Credentials, configure toolsets with +`GcpAuthProviderScheme` and register `GcpAuthProvider` with the +`CredentialManager`. This lets ADK delegate access-token retrieval to a managed +provider instead of handling every polling, consent, and refresh step in your +agent code. + +For setup details, see the +[Agent Identity integration](/integrations/agent-identity/). + ## Tools and integrations quick guide Here is a quick guide to authentication for key ADK toolsets: