Registrar e gerenciar agentes A2A

O Agent-to-Agent (A2A) é um protocolo de comunicação aberto e uma linguagem universal para agentes. Ela 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 Gemini Enterprise.

Antes de começar

Verifique se você tem o seguinte:

Configurar detalhes de autorização

Crie credenciais do OAuth 2.0 para que o agente acesse recursos do Google Cloud , como tabelas do BigQuery, em nome de um usuário.

Receber detalhes da autorização

Siga estas etapas para acessar os detalhes da autorização.

  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:

Adicionar um recurso de autorização ao Gemini Enterprise

Execute o comando a seguir para registrar um recurso de autorização com o Gemini Enterprise:

REST

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_ID/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_ID/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.
  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Atribua 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 que você recebeu ao criar as credenciais do OAuth. Ele tem o seguinte formato: https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
  • OAUTH_TOKEN_URI: o URI do token que você recebeu ao criar as credenciais do OAuth.

Registrar um agente A2A com o 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 usuários em um app do 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 do 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": "v1.0",
  "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 que você gerou 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 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. Atribua 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 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 extrair 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 por valores:

  • ENDPOINT_LOCATION-: a multirregião da sua solicitação de API. Atribua 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 por valores:

  • ENDPOINT_LOCATION-: a multirregião da sua solicitação de API. Atribua 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 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 do 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": "v3.0",
  "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 de 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. Atribua 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 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 por valores:

  • ENDPOINT_LOCATION-: a multirregião da sua solicitação de API. Atribua 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 Gemini Enterprise no app da Web.