Registe e faça a gestão de agentes A2A

O protocolo agente a agente (A2A) é um protocolo de comunicação aberto e uma linguagem universal para agentes. Permite que os agentes de diferentes criadores e plataformas se descubram, colaborem e deleguem tarefas em segurança. Este documento explica como os administradores do Gemini Enterprise podem associar agentes criados com a A2A e alojados em qualquer plataforma ao Gemini Enterprise, disponibilizando-os aos utilizadores na app Web Gemini Enterprise.

Antes de começar

Certifique-se de que tem o seguinte:

Configure os detalhes da autorização

Crie credenciais OAuth 2.0 para o agente aceder a recursos Google Cloud , como tabelas do BigQuery, em nome de um utilizador.

Obtenha detalhes de autorização

Siga estes passos para obter os detalhes da autorização.

  1. Na Google Cloud consola, na página APIs e serviços, aceda à página Credenciais.

    Aceder a Credenciais

  2. Selecione o Google Cloud projeto que tem a origem de dados à qual quer que o agente aceda. Por exemplo, selecione o projeto que contém o conjunto de dados do BigQuery que quer que o agente consulte.

  3. Clique em Criar credenciais e selecione ID de cliente OAuth.

  4. Em Tipo de aplicação, selecione Aplicação Web.

  5. Na secçã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 Transferir JSON. O JSON transferido inclui Client ID, Authorization URI, Token URI e Client secret para o Google Cloud projeto selecionado. Precisa destes detalhes para criar um recurso de autorização:

Adicione um recurso de autorização ao Gemini Enterprise

Execute o seguinte comando para registar 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 o seguinte:

  • PROJECT_ID: o ID do seu projeto.
  • ENDPOINT_LOCATION: a multirregião para o seu pedido de API. Atribua um dos seguintes valores:
    • us- para a multirregião dos EUA
    • eu- para a multirregião da UE
    • global- para a localização global
    Para mais informações, consulte o artigo Especifique várias regiões para o 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. Este é um ID alfanumérico arbitrário que define. Tem de referenciar este ID mais tarde quando registar um agente que requer suporte de OAuth.
  • OAUTH_CLIENT_ID: o identificador do cliente OAuth 2.0 que obteve quando criou as credenciais OAuth.
  • OAUTH_CLIENT_SECRET: o segredo do cliente OAuth 2.0 que obteve quando criou as credenciais OAuth.
  • OAUTH_AUTH_URI: o URI de autorização que obteve quando criou as credenciais OAuth. 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 obteve quando criou as credenciais OAuth.

Registe um agente A2A com o Gemini Enterprise

Pode registar o seu agente A2A com o Gemini Enterprise através da Google Cloud consola ou da API REST. Isto torna o agente disponível para os utilizadores numa app Gemini Enterprise.

Consola

Para registar um agente A2A através da consola Google Cloud , siga estes passos:

  1. Na Google Cloud consola, aceda à página do Gemini Enterprise.

    Gemini Enterprise

  2. Clique no nome da app na qual quer registar o agente.

  3. Clique em Agentes > Adicionar agentes.

  4. Na secção Escolha um tipo de agente, clique em Adicionar para Agente personalizado através de A2A.

  5. No campo JSON do cartão de agente, introduza os detalhes do cartão de agente no formato JSON. Para ver uma lista completa dos campos disponíveis, consulte a Especificação oficial do protocolo Agent2Agent (A2A). O exemplo seguinte usa apenas os campos obrigatórios.

    Por 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 Pré-visualizar detalhes do agente > Seguinte.

  7. Conclua a configuração através de um dos seguintes métodos:

    • Se quiser que o agente aceda a Google Cloud recursos em seu nome, siga estes passos:

      1. Introduza o ID de cliente, o segredo do cliente, o URI de autorização e o URI do token que gerou na secção Obtenha detalhes de autorização.

      2. Introduza os Âmbitos.

      3. Clique em Concluir.

    • Se não quiser que o agente aceda aos Google Cloud recursos em seu nome, clique em Ignorar e concluir.

REST

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

Execute este comando para registar o 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 o seguinte:

  • ENDPOINT_LOCATION: a multirregião para o seu pedido de API. Atribua um dos seguintes valores:
    • us- para a multirregião dos EUA
    • eu- para a multirregião da UE
    • global- para a localização global
    Para mais informações, consulte o artigo Especifique várias regiões para o seu repositório de dados.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
  • PROJECT_ID: o ID do seu projeto.
  • APP_ID: o ID da app com a qual quer registar o agente.
  • AGENT_NAME: o identificador exclusivo do agente.
  • AGENT_DISPLAY_NAME: o nome do agente que é apresentado na app Web.
  • AGENT_DESCRIPTION: a descrição do que o agente pode fazer.
  • PROTOCOLVERSION: a versão do protocolo A2A que o agente suporta. Para mais informações sobre as versões suportadas, consulte as notas de lançamento da A2A.
  • AGENT_URL: o URL do ponto final do agente.
  • AGENT_VERSION: a versão do agente.
  • INPUT_MODE: o tipo de suporte de entrada predefinido. Por exemplo, application/json ou text/plain.
  • OUTPUT_MODE: o tipo de suporte de saída predefinido. Por exemplo, text/plain" ou image/png.
  • CAPABILITIES: um objeto JSON que contém funcionalidades A2A suportadas. Por exemplo, \"streaming\": true ou \"pushNotifications\": false.
  • SKILLS: uma lista do objeto AgentSkill que o agente oferece.
  • authorizationConfig: Se obteve os detalhes de autorização e quer que o agente aceda aos recursos em nome do utilizador, adicione o campo authorization_config ao seu recurso JSON. Google Cloud

Liste agentes associados a uma app

O seguinte exemplo de código demonstra como pode obter os detalhes de todos os agentes ligados à sua 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 para o seu pedido de API. Atribua um dos seguintes valores:
    • us- para a multirregião dos EUA
    • eu- para a multirregião da UE
    • global- para a localização global
    Para mais informações, consulte o artigo Especifique várias regiões para o seu repositório de dados.
  • PROJECT_ID: o ID do seu projeto Google Cloud .
  • LOCATION: a multirregião da sua app: global, us ou eu.
  • APP_ID: o ID da sua app Gemini Enterprise.

Se o seu agente não for pré-criado pela Google, a resposta inclui um campo name nas primeiras linhas. O valor deste campo contém o ID do agente no final do caminho. Por exemplo, na resposta seguinte, o ID do agente é 12345678901234567890:

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

Veja os detalhes de um agente A2A

O seguinte exemplo de código demonstra como pode obter os detalhes de um agente registado 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 para o seu pedido de API. Atribua um dos seguintes valores:
    • us- para a multirregião dos EUA
    • eu- para a multirregião da UE
    • global- para a localização global
    Para mais informações, consulte o artigo Especifique várias regiões para o seu repositório de dados.
  • PROJECT_ID: o ID do seu projeto Google Cloud .
  • LOCATION: a multirregião da sua app: global, us ou eu.
  • APP_ID: o ID da sua app Gemini Enterprise.
  • AGENT_ID: o ID do agente. Pode encontrar o ID do agente listando os agentes associados à sua app.

Atualize um agente A2A

Pode modificar os detalhes de um agente A2A existente registado no Gemini Enterprise através da Google Cloud consola ou da API REST.

Consola

Para atualizar um agente A2A através da Google Cloud consola, siga estes passos:

  1. Na Google Cloud consola, aceda à página do Gemini Enterprise.

    Gemini Enterprise

  2. Clique no nome da app que inclui o agente que quer atualizar.

  3. Clique em Agentes.

  4. Clique no nome do agente A2A (personalizado) que quer atualizar e, de seguida, clique em Editar.

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

    Por 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 Guardar.

REST

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

Execute este comando para atualizar o 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 o seguinte:

  • ENDPOINT_LOCATION: a multirregião para o seu pedido de API. Atribua um dos seguintes valores:
    • us- para a multirregião dos EUA
    • eu- para a multirregião da UE
    • global- para a localização global
    Para mais informações, consulte o artigo Especifique várias regiões para o seu repositório de dados.
  • LOCATION: a multirregião da sua loja de dados: global, us ou eu.
  • PROJECT_ID: o ID do seu projeto.
  • APP_ID: o ID da app na qual quer registar o agente.
  • AGENT_ID: o ID do agente. Pode encontrar o ID do agente listando os agentes associados à sua app.
  • AGENT_NAME: o identificador exclusivo do agente.
  • AGENT_DISPLAY_NAME: o nome do agente que é apresentado na app Web.
  • AGENT_DESCRIPTION: a descrição do que o agente pode fazer.
  • PROTOCOLVERSION: a versão do protocolo A2A que o agente suporta. Para mais informações sobre as versões suportadas, consulte as notas de lançamento da A2A.
  • AGENT_URL: o URL do ponto final do agente.
  • AGENT_VERSION: a versão do agente.
  • INPUT_MODE: o tipo de suporte de entrada predefinido. Por exemplo, application/json ou text/plain.
  • OUTPUT_MODE: o tipo de suporte de saída predefinido. Por exemplo, text/plain ou image/png.
  • CAPABILITIES: um objeto JSON que contém funcionalidades A2A suportadas. Por exemplo, \"streaming\": true ou \"pushNotifications\": false.
  • SKILLS: uma lista do objeto AgentSkill que o agente oferece.
  • authorizationConfig: Se obteve os detalhes de autorização e quer que o agente aceda aos recursos em nome do utilizador, adicione o campo authorization_config ao seu recurso JSON. Google Cloud

Elimine um agente A2A

O seguinte exemplo de código demonstra como pode eliminar um agente que está ligado à sua 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 para o seu pedido de API. Atribua um dos seguintes valores:
    • us- para a multirregião dos EUA
    • eu- para a multirregião da UE
    • global- para a localização global
    Para mais informações, consulte o artigo Especifique várias regiões para o seu repositório de dados.
  • PROJECT_ID: o ID do seu projeto Google Cloud .
  • LOCATION: a multirregião da sua app: global, us ou eu
  • APP_ID: o ID da sua app Gemini Enterprise.
  • AGENT_ID: o ID do agente. Pode encontrar o ID do agente listando os agentes associados à sua app.

O que se segue?

  • Use o agente que registou com o Gemini Enterprise na app Web.