Registrar e gerenciar agentes do ADK hospedados no Vertex AI Agent Engine

Nesta página, descrevemos como os administradores do Gemini Enterprise podem registrar agentes do Kit de Desenvolvimento de Agente (ADK) hospedados na Vertex AI Agent Engine para que fiquem disponíveis aos usuários no app da Web Gemini Enterprise.

Antes de começar

Verifique se você tem o seguinte:

  • O papel de administrador do Discovery Engine.

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

    Acessar a API Discovery Engine

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

  • Um agente do ADK hospedado no Vertex AI Agent Engine. Para mais informações, consulte Visão geral do Agent Development Kit.

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 do ADK com o Gemini Enterprise

É possível registrar seu agente do ADK 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 do ADK 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. A página Agentes é exibida.

  4. Clique em Adicionar agente. O painel Adicionar um agente é exibido.

  5. Clique em Adicionar para Agente personalizado via Agent Engine. A página Autorizações é exibida.

  6. Se você quiser que o agente acesse recursos do Google Cloud em seu nome, cada recurso precisará de uma autorização. Para configurar uma autorização para um único recurso, siga estas etapas:

    1. Clique em Adicionar autorização.

    2. Insira um valor exclusivo para Nome da autorização. Um ID é gerado com base no nome e não pode ser alterado depois.

    3. Insira os valores gerados na seção Receber detalhes de autorização nos seguintes campos:

      1. Insira o valor no campo ID do cliente.

      2. Insira o valor no campo Chave secreta do cliente.

      3. Insira o valor no campo URI do token.

      4. Clique em Concluído.

  7. Clique em Próxima.

  8. Para configurar o agente, siga estas etapas:

    1. Digite um nome no campo Nome do agente. Esse valor aparece no app da Web Gemini Enterprise como o nome de exibição do seu agente.

    2. Digite uma descrição no campo Descreva seu agente. Esse valor é usado por um LLM para determinar se o agente precisa ser invocado em resposta a uma consulta do usuário.

    3. Insira o caminho do recurso do mecanismo de raciocínio do Agent Engine. O caminho do recurso tem o seguinte formato:

          https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID

      Para mais informações sobre como listar os agentes hospedados no Vertex AI Agent Engine e receber o caminho do recurso, consulte Listar agentes implantados.

    4. Clique em Criar.

REST

Este exemplo de código demonstra como registrar seus agentes do ADK.

   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/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
      -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "icon": {
            "uri": "ICON_URI"
      },
      "adk_agent_definition": {
         "provisioned_reasoning_engine": {
            "reasoning_engine":
            "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/reasoningEngines/ADK_RESOURCE_ID"
         }
      },
   "authorization_config": {


   "tool_authorizations": [
   "projects/PROJECT_ID/locations/global/authorizations/AUTH_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 .

  • APP_ID: o identificador exclusivo do app Gemini Enterprise.

  • DESCRIPTION : a descrição do agente que é mostrada no Gemini Enterprise.

  • ICON_URI: o URI público do ícone a ser exibido perto do nome do agente. Outra opção é transmitir o conteúdo do arquivo de imagem codificado em Base64. Nesse caso, use icon.content.

  • ADK_RESOURCE_ID: o ID do endpoint do mecanismo de raciocínio em que o agente do ADK é implantado. Para mais informações sobre como listar os agentes hospedados no Vertex AI Agent Engine e receber o ID do recurso, consulte Listar agentes implantados.

  • REASONING_ENGINE_LOCATION: o local na nuvem do mecanismo de raciocínio. Para mais informações, consulte Local do Reasoning Engine.

  • 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.

     * <code><var>AUTH_ID</var></code>: the value that you used for
    <var>AUTH_ID</var> in the [Configure authorization details](#authorize-your-adk-agent)
    section.

Adicionar usuários com permissão

Para adicionar usuários com permissão a um agente do ADK usando o console Google Cloud , consulte Adicionar ou modificar usuários e as permissões deles.

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 do ADK

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 do ADK

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

Console

Para atualizar o agente 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 do mecanismo de agente que você quer atualizar e em Editar.

  5. Atualize o Nome de exibição, a Descrição ou o Mecanismo de inferência do Agent Engine.

    O caminho do recurso tem o seguinte formato:

      https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID

    Para mais informações sobre como listar os agentes hospedados no Vertex AI Agent Engine e receber o caminho do recurso, consulte Listar agentes implantados.

  6. Clique em Salvar.

REST

É possível atualizar todos os campos durante o registro do agente. No entanto, os campos a seguir precisam ser atualizados:

  • displayName
  • description

  • reasoningEngine

    Este exemplo de código demonstra como atualizar o registro de um agente do ADK existente:

    curl -X PATCH \
   -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/AGENT_RESOURCE_NAME" \
   -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "adkAgentDefinition": {
         "provisionedReasoningEngine": {
            "reasoningEngine":
            "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/reasoningEngine
            s/ADK_RESOURCE_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 .

  • AGENT_RESOURCE_NAME: o nome do recurso do registro do agente a ser atualizado.

  • DISPLAY_NAME: obrigatório. O nome fácil de usar do seu agente que aparece no Gemini Enterprise.

  • DESCRIPTION: obrigatório. Uma breve explicação do que seu agente faz, visível para os usuários no Gemini Enterprise.

  • REASONING_ENGINE_LOCATION: obrigatório. O local na nuvem do Reasoning Engine em que você está criando um agente. Para mais informações, consulte Local do Reasoning Engine.

  • ADK_RESOURCE_ID: o ID do endpoint do mecanismo de raciocínio em que o agente do ADK é implantado. Para mais informações sobre como listar os agentes hospedados no Vertex AI Agent Engine e receber o ID do recurso, consulte Listar agentes implantados.

Excluir um agente do ADK

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.

Localização do mecanismo de raciocínio

Para fazer a chamada de API no local correto do mecanismo de inferência, use o gráfico a seguir:

Local do Cloud que você está chamando Local do Reasoning Engine
us us-central1
eu europe-west1
outros (incluindo global) us-central1