Para permitir que os agentes façam a autenticação em ferramentas externas, como ServiceNow ou Salesforce, usando a própria autoridade, configure a autenticação de saída usando provedores de autenticação OAuth de duas etapas (credenciais do cliente) no gerenciador de autenticação da identidade do agente.
Os provedores de autenticação OAuth de duas etapas gerenciam credenciais e tokens para você. Isso elimina a necessidade de escrever código personalizado para processar fluxos de autenticação.
Fluxo de trabalho do OAuth de duas etapas
Os provedores de autenticação OAuth de duas etapas usam a identidade do agente e não exigem o consentimento do usuário. O Google gerencia o armazenamento das credenciais do cliente. Quando você usa o Kit de desenvolvimento de agentes (ADK, na sigla em inglês), ele recupera e injeta automaticamente os tokens de acesso resultantes nos cabeçalhos de invocação da ferramenta.
Antes de começar
- Verifique se você escolheu o método de autenticação correto.
Ative a API do conector de identidade do agente.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (
roles/serviceusage.serviceUsageAdmin), que contém a permissãoserviceusage.services.enable. Saiba como conceder papéis.Receba o ID do cliente e a chave secreta do cliente do aplicativo de terceiros que você quer conectar.
Verifique se você tem as funções necessárias para concluir essa tarefa.
Funções exigidas
Para receber as permissões necessárias para criar e usar um provedor de autenticação de identidade do agente de duas etapas, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:
-
Para criar provedores de autenticação:
- Administrador do conector do IAM (
roles/iamconnectors.admin) - Editor do conector do IAM (
roles/iamconnectors.editor)
- Administrador do conector do IAM (
-
Para usar provedores de autenticação:
- Usuário do conector do IAM (
roles/iamconnectors.user) - Acesso padrão do agente (
roles/aiplatform.agentDefaultAccess) - Editor de contexto do agente (
roles/aiplatform.agentContextEditor) - Usuário da Vertex AI (
roles/aiplatform.user) - Consumidor do Service Usage (
roles/serviceusage.serviceUsageConsumer)
- Usuário do conector do IAM (
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esses papéis predefinidos contêm as permissões necessárias para criar e usar um provedor de autenticação de identidade do agente de duas etapas. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As permissões a seguir são necessárias para criar e usar um provedor de autenticação de identidade do agente de duas etapas:
-
Para criar provedores de autenticação:
iamconnectors.connectors.create -
Para usar provedores de autenticação:
-
iamconnectors.connectors.retrieveCredentials -
aiplatform.endpoints.predict -
aiplatform.sessions.create
-
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Criar um provedor de autenticação de duas etapas
Crie um provedor de autenticação para definir a configuração e as credenciais de aplicativos de terceiros.
Para criar um provedor de autenticação de duas etapas, use o Google Cloud console ou a Google Cloud CLI.
Console
- No Google Cloud console, acesse a página Registro de agentes.
- Clique no nome do agente para o qual você quer criar um provedor de autenticação.
- Clique em Identidade.
- Na seção Provedores de autenticação, clique em Adicionar provedor de autenticação.
-
No painel Adicionar provedor de autenticação, insira um nome e uma descrição.
O nome só pode conter letras minúsculas, números ou hífens, não pode terminar com um hífen e precisa começar com uma letra minúscula.
- Na lista Tipo de OAuth, selecione OAuth (duas etapas) .
- Clique em Criar e continuar.
- Para conceder permissão de identidade do agente para usar o provedor de autenticação, clique em Conceder acesso.
Isso atribui automaticamente o papel de usuário do conector (
roles/iamconnectors.user) à identidade do agente no recurso do provedor de autenticação. - Na seção Credenciais do provedor de autenticação, insira as seguintes informações:
- ID do cliente
- Client Secret
- URL do token
- Clique em Adicionar configuração do provedor.
O provedor de autenticação recém-criado aparece na lista Provedores de autenticação.
CLI gcloud
-
Crie o provedor de autenticação:
gcloud alpha agent-identity connectors create
AUTH_PROVIDER_NAME\ --location="LOCATION" \ --two-legged-oauth-client-id="CLIENT_ID" \ --two-legged-oauth-client-secret="CLIENT_SECRET" \ --two-legged-oauth-token-endpoint="TOKEN_ENDPOINT" - Verifique se o provedor de autenticação aparece na lista e se o estado dele é
ENABLED:gcloud alpha agent-identity connectors list \ --project="
PROJECT_ID" \ --location="LOCATION" -
Conceda permissões de acesso para permitir que o agente e o ambiente de desenvolvimento local ambiente recuperem credenciais do provedor de autenticação. Para permitir que o agente implantado e sua conta de usuário pessoal acessem o provedor de autenticação, conceda o papel de usuário do conector (
roles/iamconnectors.user) no recurso do provedor de autenticação:-
Conceda acesso ao ID do SPIFFE do agente implantado (identidade do agente):
gcloud alpha agent-identity connectors add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/iamconnectors.user" \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID" -
Conceda acesso à sua conta de usuário pessoal para desenvolvimento e testes locais (
adk web):gcloud alpha agent-identity connectors add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/iamconnectors.user" \ --member="user:USER_EMAIL"
-
Substitua:
PROJECT_ID: o ID do Google Cloud projeto do.LOCATION: o local em que o provedor de autenticação e o agente estão implantados (por exemplo,us-west1).AUTH_PROVIDER_NAME: o nome do provedor de autenticação (por exemplo,bigquery-mcp-3lo-authprovider).AUTHORIZATION_URL: o URL do servidor de autorização (por exemplo,https://accounts.google.com/o/oauth2/v2/auth).TOKEN_URL: o URL do servidor de tokens (por exemplo,https://oauth2.googleapis.com/token).CLIENT_ID: o ID do cliente OAuth gerado pelo serviço de terceiros.CLIENT_SECRET: a chave secreta do cliente OAuth gerada pelo serviço de terceiros.ORGANIZATION_ID: o ID da sua Google Cloud organização.PROJECT_NUMBER: o Google Cloud número do projeto.ENGINE_ID: o ID do agente do mecanismo de raciocínio implantado.USER_EMAIL: o endereço de e-mail da sua conta de usuário pessoal.
Autenticar no código do agente
Para autenticar o agente, você pode usar o ADK.
ADK
Faça referência ao provedor de autenticação no código do agente usando o conjunto de ferramentas do MCP no ADK.
from google.adk.agents.llm_agent import LlmAgent from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset from google.adk.auth.auth_tool import AuthConfig # Register the Google Cloud Auth Provider so the CredentialManager can use it. CredentialManager.register_auth_provider(GcpAuthProvider()) # Create the Google Cloud Auth Provider scheme using the auth provider's full resource name. auth_scheme = GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME" ) # Configure an MCP tool with the authentication scheme. toolset = McpToolset( connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"), auth_scheme=auth_scheme, ) # Initialize the agent with the authenticated tools. agent = LlmAgent( name="AGENT_NAME", model="gemini-2.5-flash", instruction="AGENT_INSTRUCTIONS", tools=[toolset], )
ADK
Faça referência ao provedor de autenticação no código do agente usando uma ferramenta de função autenticada no ADK.
import httpx from google.adk.agents.llm_agent import LlmAgent from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider from google.adk.integrations.agent_identity import GcpAuthProviderScheme from google.adk.apps import App from google.adk.auth.auth_credential import AuthCredential from google.adk.auth.auth_tool import AuthConfig from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool from vertexai import agent_engines # First, register Google Cloud auth provider CredentialManager.register_auth_provider(GcpAuthProvider()) # Create Auth Config spotify_auth_config = AuthConfig( auth_scheme=GcpAuthProviderScheme( name=( "projects/PROJECT_ID/locations/" "LOCATION/connectors/" "AUTH_PROVIDER_NAME" ) ) ) # Use the Auth Config in Authenticated Function Tool spotify_search_track_tool = AuthenticatedFunctionTool( func=spotify_search_track, auth_config=spotify_auth_config ) # Sample function tool async def spotify_search_track(credential: AuthCredential, query: str) -> str | list: token = None if credential.http and credential.http.credentials: token = credential.http.credentials.token if not token: return "Error: No authentication token available." async with httpx.AsyncClient() as client: response = await client.get( "https://api.spotify.com/v1/search", headers={"Authorization": f"Bearer {token}"}, params={"q": query, "type": "track", "limit": 1}, ) # Add your own logic here agent = LlmAgent( name="AGENT_NAME", model="MODEL_NAME", instruction="AGENT_INSTRUCTIONS", tools=[spotify_search_track_tool], ) app = App( name="APP_NAME", root_agent=agent, ) vertex_app = agent_engines.AdkApp(app_name=app)
ADK
Faça referência ao provedor de autenticação no código do agente usando o conjunto de ferramentas do MCP do registro de agentes no ADK.
from google.adk.agents.llm_agent import LlmAgent from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider from google.adk.integrations.agent_identity import GcpAuthProviderScheme from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset from google.adk.auth.auth_tool import AuthConfig from google.adk.integrations.agent_registry import AgentRegistry # First, register Google Cloud auth provider CredentialManager.register_auth_provider(GcpAuthProvider()) # Create Google Cloud auth provider scheme by providing Auth Provider full resource name auth_scheme = GcpAuthProviderScheme( name=( "projects/PROJECT_ID/locations/" "LOCATION/connectors/" "AUTH_PROVIDER_NAME" ) ) # Set Agent Registry registry = AgentRegistry(project_id="PROJECT_ID", location="global") toolset = registry.get_mcp_toolset( mcp_server_name=( "projects/PROJECT_ID/locations/" "global/mcpServers/" "agentregistry-00000000-0000-0000-0000-000000000000" ), auth_scheme=auth_scheme, ) # Example MCP tool toolset = McpToolset( connection_params=StreamableHTTPConnectionParams(url="MCP_URL"), auth_scheme=auth_scheme, ) agent = LlmAgent( name="AGENT_NAME", model="MODEL_NAME", instruction="AGENT_INSTRUCTIONS", tools=[toolset], )
Instalar dependências para testes locais
Para testar o agente localmente em um ambiente virtual, instale as seguintes dependências necessárias:
- Crie e ative um ambiente virtual:
python3 -m venv env source env/bin/activate
- Instale os pacotes necessários.
pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]
Implantar o agente
Ao implantar o agente no Google Cloud, verifique se a identidade do agente está ativada.
Se você estiver implantando no
Agent Runtime na Gemini Enterprise Agent Platform
, use a identity_type=AGENT_IDENTITY
flag:
import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
project="PROJECT_ID",
location="LOCATION",
http_options=dict(api_version="v1beta1")
)
# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)
# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
agent=app,
config={
"identity_type": types.IdentityType.AGENT_IDENTITY,
"requirements": ["google-cloud-aiplatform[agent_engines,adk]", "google-adk[agent-identity]"],
},
)
A seguir
- Visão geral da identidade do agente
- Autenticar usando o OAuth de três etapas com o gerenciador de autenticação
- Autenticar usando a chave de API com o gerenciador de autenticação
- Gerenciar provedores de autenticação de identidade do agente
- Resolver problemas do gerenciador de autenticação de identidade do agente