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 eles fiquem disponíveis 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. 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 do OAuth. Copie o modelo a seguir e substitua os marcadores pelos valores específicos.

    https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_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

    Detalhamento de parâmetros

    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 Ação necessária: liste os escopos da API do Google de que seu app precisa (como https://www.googleapis.com/auth/bigquery). Se você estiver usando vários escopos, separe-os 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 consentimento.

  • 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. Insira uma descrição no campo Descreva seu agente. Esse valor é usado por um LLM para determinar se o agente deve 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_NUMBER/locations/global/authorizations/AUTH_ID"
   ]
   }
   }'

Substitua as variáveis por 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 .

  • PROJECT_NUMBER: o número do seu projeto 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 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 por 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 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. 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 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. 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 .

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

Local do Reasoning Engine

Ao registrar ou atualizar um agente do ADK, o local do recurso do mecanismo de inferência precisa ser compatível com o local do agente. Os locais do mecanismo de raciocínio dependem da localização do agente da seguinte forma:

  • Agentes globais:se o agente estiver no local global, você poderá usar um mecanismo de inferência implantado em qualquer região compatível.

  • Agentes multirregionais:

    • Se o seu agente estiver na multirregião us, o mecanismo de inferência precisará ser implantado em uma região dos EUA, como us-central1, us-east1 ou us-west1.
    • Se o agente estiver na multirregião eu, o mecanismo de inferência precisará ser implantado em uma região europeia, como europe-west1, europe-west2 ou europe-central2. Confira uma tabela de resumo:
Local do agente Locais permitidos do Reasoning Engine
global Qualquer região Google Cloud em que o recurso está disponível
us Qualquer região que comece com us-, como us-central1 ou us-east4
eu Qualquer região que comece com europe-, como europe-west1 ou europe-west3

Locais incompatíveis resultam em um erro durante o registro ou a atualização do agente.