Registe e faça a gestão de agentes ADK alojados no Vertex AI Agent Engine

Esta página descreve como os administradores do Gemini Enterprise podem registar agentes do Agent Development Kit (ADK) alojados no Vertex AI Agent Engine para que possam ser disponibilizados 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 ADK com o Gemini Enterprise

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

Consola

Para registar um agente do ADK 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 do Agent Engine.

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

    1. Clique em Adicionar autorização.

    2. Introduza um valor exclusivo para o Nome da autorização. É gerado um ID com base no nome, e não é possível alterá-lo posteriormente.

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

    4. Clique em Adicionar autorização.

  6. Clicar em Seguinte.

  7. Para configurar o seu agente, siga estes passos:

    1. Introduza um nome no campo Nome do agente. Este valor aparece na app Web Gemini Enterprise como o nome a apresentar do seu agente.

    2. Introduza uma descrição no campo Descreva o seu agente. Este valor é usado por um GML para determinar se deve invocar o seu agente em resposta a uma consulta do utilizador.

    3. Introduza o caminho do recurso do motor 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 alojados no Vertex AI Agent Engine e obter o caminho do recurso, consulte o artigo Liste agentes implementados.

    4. Configure as definições da ferramenta:

      1. Introduza uma descrição para o campo Descrição da ferramenta. Esta descrição é usada pelo MDG para compreender a finalidade da ferramenta e decidir quando a usar.

      2. Introduza o nome no campo Nome do parâmetro de entrada. Este é o nome do parâmetro para a chamada de função. Este nome de parâmetro dá pistas ao MDL sobre o tipo de entrada esperado, como um question, command ou search_query.

      3. Introduza a descrição do campo Descrição do parâmetro de entrada. Esta descrição do parâmetro fornece ao MDG mais informações acerca do parâmetro, como o conteúdo esperado e as ações a realizar.

    5. Clique em Criar.

REST

Este exemplo de código demonstra como pode registar os 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 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 .

  • APP_ID: o identificador exclusivo da app Gemini Enterprise.

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

  • ICON_URI: o URI público do ícone a apresentar junto ao nome do agente. Em alternativa, pode transmitir o conteúdo do ficheiro de imagem codificado em Base64 e, nesse caso, usar icon.content.

  • ADK_RESOURCE_ID: o ID do ponto final do motor de raciocínio onde o agente ADK está implementado. Para mais informações sobre como listar os agentes alojados no Vertex AI Agent Engine e obter o ID do recurso, consulte o artigo Liste os agentes implementados.

  • REASONING_ENGINE_LOCATION: a localização na nuvem do motor de raciocínio. Para mais informações, consulte a secção Localização do motor de raciocínio.

  • 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 

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

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

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

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

Consola

Para atualizar o agente 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 do motor do agente que quer atualizar e, de seguida, clique em Editar.

  5. Atualize o Nome a apresentar, a Descrição ou o motor 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 alojados no Vertex AI Agent Engine e obter o caminho do recurso, consulte o artigo Liste os agentes implementados.

  6. Clique em Guardar.

REST

Pode atualizar todos os campos durante o registo do agente. No entanto, tem de atualizar os seguintes campos:

  • displayName
  • description

  • reasoningEngine

    Este exemplo de código demonstra como pode atualizar o registo 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 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 .

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

  • DISPLAY_NAME: obrigatório. O nome intuitivo do seu agente que é apresentado no Gemini Enterprise.

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

  • REASONING_ENGINE_LOCATION: obrigatório. A localização na nuvem do motor de raciocínio no qual está a criar um agente. Para mais informações, consulte o artigo Localização do motor de raciocínio.

  • ADK_RESOURCE_ID: o ID do ponto final do motor de raciocínio onde o agente ADK está implementado. Para mais informações sobre como listar os agentes alojados no Vertex AI Agent Engine e obter o ID do recurso, consulte o artigo Liste os agentes implementados.

Elimine um agente do ADK

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.

Localização do motor de raciocínio

Para fazer a chamada da API para a localização correta do motor de raciocínio, use o gráfico seguinte:

Localização na nuvem a partir da qual está a ligar Localização do motor de raciocínio
us us-central1
eu europe-west1
outros (incluindo global) us-central1