Registrar e gerenciar agentes A2A

O protocolo Agent2Agent (A2A) é um protocolo de comunicação aberto e uma linguagem universal para agentes. O protocolo permite que agentes de diferentes criadores e plataformas se descubram, colaborem e deleguem tarefas com segurança. Este documento explica como os administradores do Gemini Enterprise podem conectar agentes criados com A2A e hospedados em qualquer plataforma ao Gemini Enterprise, disponibilizando-os para os usuários no app da Web do Gemini Enterprise.

Antes de começar

Verifique se você tem o seguinte:

  • A função de administrador do Gemini Enterprise.

  • Ative a API Discovery Engine. Para ativar a API Discovery Engine no projeto Google Cloud, acesse a página API Discovery Engine no console Google Cloud .

    Acessar a API Discovery Engine

  • Um app Gemini Enterprise existente. Para criar um app, consulte Criar um app.

  • Um agente que usa o protocolo A2A.

    O Gemini Enterprise é compatível com o mecanismo de streaming A2A v0.3.

    Se você usa o A2A v1.0.0 ou mais recente, use os pacotes de compatibilidade fornecidos pelo SDK para garantir que seu agente funcione com o mecanismo anterior (por exemplo, o pacote a2acompat/a2av0 para Go ou o pacote a2a.compat.v0_3 para Python).

Configurar detalhes de autorização (opcional)

Para agentes A2A, use as credenciais do OAuth 2.0 para controlar o acesso do usuário final aos agentes A2A. No entanto, se o agente for executado no Cloud Run e usar o Identity and Access Management para controle de acesso, as credenciais do OAuth 2.0 não serão necessárias.

  1. No console Google Cloud , na página APIs e serviços, acesse a página Credenciais.

    Ir para Credenciais

  2. Selecione o projeto do Google Cloud que tem a fonte de dados a que você quer que o agente acesse. Por exemplo, selecione o projeto que contém o conjunto de dados do BigQuery que você quer que o agente consulte.

  3. Clique em Criar credenciais e selecione ID do cliente do Oauth.

  4. Em Tipo de aplicativo, selecione Aplicativo da Web.

  5. Na seção URIs de redirecionamento autorizados, adicione os seguintes URIs:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. Clique em Criar.

  7. No painel Cliente OAuth criado, clique em Fazer o download do JSON. O JSON baixado inclui Client ID, Authorization URI, Token URI e Client secret para oGoogle Cloud projeto selecionado. Você precisa desses detalhes para criar um recurso de autorização.

Registrar um agente A2A no Gemini Enterprise

É possível registrar seu agente A2A com o Gemini Enterprise usando o consoleGoogle Cloud ou a API REST. Isso disponibiliza o agente para os usuários em um app Gemini Enterprise.

Console

Para registrar um agente A2A usando o console Google Cloud , siga estas etapas:

  1. No console Google Cloud , acesse a página Gemini Enterprise.

    Gemini Enterprise

  2. Clique no nome do app em que você quer registrar o agente.

  3. Clique em Agentes > Adicionar agentes.

  4. Na seção Escolher um tipo de agente, clique em Adicionar para Agente personalizado via A2A.

  5. No campo JSON do card do agente, insira os detalhes do card no formato JSON. Para uma lista completa de campos disponíveis, consulte a especificação oficial do protocolo Agent2Agent (A2A). O exemplo a seguir usa apenas os campos obrigatórios.

    Exemplo:

    {
  "protocolVersion": "0.3",
  "name": "Hello World Agent",
  "description": "Just a hello world agent",
  "url": "https://example.com/myagent",
  "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
  "version": "1.0.0",
  "capabilities": {
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Data analysis",
      "tags": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

  6. Clique em Visualizar detalhes do agente > Próxima.

  7. Conclua a configuração usando um dos seguintes métodos:

    • Se você quiser que o agente acesse recursos do Google Cloud em seu nome, siga estas etapas:

      1. Insira o ID do cliente, a chave secreta do cliente, o URI de autorização e o URI de token gerados na seção Receber detalhes de autorização.

      2. Insira os escopos.

      3. Clique em Concluir.

    • Se você não quiser que o agente acesse recursos do Google Cloud em seu nome, clique em Ignorar e concluir.

REST

Para registrar um agente A2A usando a API REST, siga estas etapas:

Adicionar o recurso de autorização ao Gemini Enterprise (opcional)

Se o agente precisar acessar recursos do Google Cloud em nome de um usuário, execute o comando a seguir para registrar o recurso de autorização criado na seção Configurar detalhes da autorização (opcional) com o Gemini Enterprise:

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

Substitua:

  • PROJECT_ID: ID do projeto.
  • PROJECT_NUMBER: o número do seu projeto Google Cloud .
  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
  • AUTH_ID: o ID do recurso de autorização. Esse é um ID alfanumérico arbitrário definido por você. Você precisará fazer referência a esse ID mais tarde ao registrar um agente que exige suporte do OAuth.
  • OAUTH_CLIENT_ID: o identificador do cliente OAuth 2.0 que você recebeu ao criar as credenciais do OAuth.
  • OAUTH_CLIENT_SECRET: a chave secreta do cliente OAuth 2.0 que você recebeu ao criar as credenciais do OAuth.

  • OAUTH_AUTH_URI: o URI de autorização. Para autorizar seu app, crie um URI de autorização específico usando os detalhes do arquivo JSON de credenciais OAuth. Copie o modelo a seguir e substitua os marcadores de posição pelos seus valores específicos.

    https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

    • YOUR_CUSTOM_SCOPES: você pode adicionar os escopos necessários. Por exemplo, a string de escopo OAuth a seguir solicita acesso somente leitura ao Google Drive e aos Documentos Google.

      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly

  • OAUTH_TOKEN_URI: o URI do token que você recebeu ao criar as credenciais do OAuth.

Mais informações sobre os parâmetros de URI de autorização.

Para garantir que o URI funcione corretamente, verifique os seguintes campos:

Parâmetro Valor ou ação
client_id Substitua pelo client_id encontrado no JSON baixado.
redirect_uri Não mude. Precisa ser https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
scope

Liste os escopos da API do Google que seu app precisa acessar em nome do usuário. Por exemplo, para conceder acesso ao BigQuery, use o escopo https://www.googleapis.com/auth/bigquery. Para acesso somente leitura ao Google Docs, use https://www.googleapis.com/auth/documents.readonly.

Se você estiver usando vários escopos, separe com um espaço, que se torna %20 no URL.
include_granted_scopes Precisa ser true.
response_type Precisa ser code para receber um código de autorização.
access_type Defina como offline para garantir que você receba um token de atualização.
prompt Defina como consent para garantir que o usuário sempre veja uma tela de permissão.

Registrar seu agente A2A

Para criar e registrar um agente com o Gemini Enterprise, use o método agents.create. O comando a seguir usa apenas os campos obrigatórios. Para uma lista completa de campos disponíveis, consulte a Especificação oficial do protocolo Agent2Agent (A2A).

Execute este comando para registrar seu agente A2A no Gemini Enterprise:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

Substitua:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
  • PROJECT_ID: ID do projeto.
  • APP_ID: o ID do app com que você quer registrar o agente.
  • AGENT_NAME: o identificador exclusivo do agente.
  • AGENT_DISPLAY_NAME: o nome do agente que é mostrado no app da Web.
  • AGENT_DESCRIPTION: a descrição do que o agente pode fazer.
  • PROTOCOLVERSION: a versão do protocolo A2A compatível com o agente. Para mais informações sobre as versões compatíveis, consulte as notas da versão do A2A.
  • AGENT_URL: o URL do endpoint do agente.
  • AGENT_VERSION: a versão do agente.
  • INPUT_MODE: o tipo de mídia de entrada padrão. Por exemplo, application/json ou text/plain.
  • OUTPUT_MODE: o tipo de mídia de saída padrão. Por exemplo, text/plain" ou image/png.
  • CAPABILITIES: um objeto JSON que contém recursos compatíveis com A2A. Por exemplo, \"streaming\": true ou \"pushNotifications\": false.
  • SKILLS: uma lista do objeto AgentSkill que o agente oferece.
  • authorizationConfig: se você tiver os detalhes de autorização e quiser que o agente acesse recursos do Google Cloud em nome do usuário, adicione o campo authorization_config ao recurso JSON.

Listar agentes conectados a um app

O exemplo de código a seguir demonstra como receber os detalhes de todos os agentes conectados ao seu app:

REST 

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

Substitua as variáveis pelos valores:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • LOCATION: a multirregião do seu app: global, us ou eu.
  • APP_ID: o ID do seu app Gemini Enterprise.

Se o agente não for pré-criado pelo Google, a resposta vai incluir um campo name nas primeiras linhas. O valor desse campo contém o ID do agente no final do caminho. Por exemplo, na resposta a seguir, o ID do agente é 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

Conferir os detalhes de um agente A2A

O exemplo de código a seguir demonstra como recuperar os detalhes de um agente registrado no Gemini Enterprise:

REST 

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Substitua as variáveis pelos valores:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • LOCATION: a multirregião do seu app: global, us ou eu.
  • APP_ID: o ID do seu app Gemini Enterprise.
  • AGENT_ID: o ID do agente. Para encontrar o ID do agente, liste os agentes conectados ao seu app.

Atualizar um agente A2A

É possível modificar os detalhes de um agente A2A registrado no Gemini Enterprise usando o console do Google Cloud ou a API REST.

Console

Para atualizar um agente A2A usando o console Google Cloud , siga estas etapas:

  1. No console Google Cloud , acesse a página Gemini Enterprise.

    Gemini Enterprise

  2. Clique no nome do app que inclui o agente que você quer atualizar.

  3. Clique em Agentes.

  4. Clique no nome do agente A2A (personalizado) que você quer atualizar e em Editar.

  5. No campo JSON do card do agente, atualize os detalhes do card no formato JSON. Para uma lista completa de campos disponíveis, consulte a especificação oficial do protocolo Agent2Agent (A2A). O exemplo a seguir usa apenas os campos obrigatórios.

    Exemplo:

    {
  "protocolVersion": "0.3",
  "name": "Hello World Agent",
  "description": "Just a hello world agent",
  "url": "https://example.com/myagent",
  "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
  "version": "1.1.0",
  "capabilities": {
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Data analysis",
      "tags": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

  6. Clique em Salvar.

REST

Para atualizar os detalhes de um agente A2A registrado no Gemini Enterprise, use o método agents.patch. O comando a seguir usa apenas os campos obrigatórios. Para uma lista completa de campos disponíveis, consulte a Especificação oficial do protocolo Agent2Agent (A2A).

Execute este comando para atualizar seu agente A2A com o Gemini Enterprise:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

Substitua:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu.
  • PROJECT_ID: ID do projeto.
  • APP_ID: o ID do app em que você quer registrar o agente.
  • AGENT_ID: o ID do agente. Para encontrar o ID do agente, liste os agentes conectados ao seu app.
  • AGENT_NAME: o identificador exclusivo do agente.
  • AGENT_DISPLAY_NAME: o nome do agente que é mostrado no app da Web.
  • AGENT_DESCRIPTION: a descrição do que o agente pode fazer.
  • PROTOCOLVERSION: a versão do protocolo A2A compatível com o agente. Para mais informações sobre as versões compatíveis, consulte as notas da versão do A2A.
  • AGENT_URL: o URL do endpoint do agente.
  • AGENT_VERSION: a versão do agente.
  • INPUT_MODE: o tipo de mídia de entrada padrão. Por exemplo, application/json ou text/plain.
  • OUTPUT_MODE: o tipo de mídia de saída padrão. Por exemplo, text/plain ou image/png.
  • CAPABILITIES: um objeto JSON que contém recursos compatíveis com A2A. Por exemplo, \"streaming\": true ou \"pushNotifications\": false.
  • SKILLS: uma lista do objeto AgentSkill que o agente oferece.
  • authorizationConfig: se você tiver os detalhes de autorização e quiser que o agente acesse recursos do Google Cloud em nome do usuário, adicione o campo authorization_config ao recurso JSON.

Excluir um agente A2A

O exemplo de código a seguir demonstra como excluir um agente conectado ao seu app:

REST 

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Substitua as variáveis pelos valores:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • LOCATION: a multirregião do seu app: global, us ou eu
  • APP_ID: o ID do seu app Gemini Enterprise.
  • AGENT_ID: o ID do agente. Para encontrar o ID do agente, liste os agentes conectados ao seu app.

A seguir

  • Use o agente que você registrou no app da Web do Gemini Enterprise.