Esta página foi traduzida pela API Cloud Translation.

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 Agent Development Kit (ADK) hospedados no 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 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.

No console Google Cloud , na página APIs e serviços, acesse a página Credenciais.

Ir para Credenciais
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.
Clique em Criar credenciais e selecione ID do cliente do Oauth.
Em Tipo de aplicativo, selecione Aplicativo da Web.
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
Clique em Criar.
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:

No console Google Cloud , acesse a página do Gemini Enterprise.

Gemini Enterprise
Clique no nome do app em que você quer registrar o agente.
Clique em Agentes > Adicionar agentes.
Na seção Escolher um tipo de agente, clique em Adicionar para Agente personalizado via mecanismo de agente.
Se você quiser que o agente acesse recursos do Google Cloud em seu nome, 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 o ID do cliente, a chave secreta do cliente, o URI de autorização e o URI de token gerados na seção Receber detalhes de autorização.
4. Clique em Adicionar autorização.
Clique em Próxima.
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. Configure as Configurações da ferramenta:
  1. Insira uma descrição no campo Descrição da ferramenta. Essa descrição é usada pelo LLM para entender o objetivo da ferramenta e decidir quando usá-la.
  2. Insira o nome no campo Nome do parâmetro de entrada. Esse é o nome do parâmetro para a chamada de função. O nome do parâmetro indica ao LLM o tipo de entrada esperado, como question, command ou search_query.
  3. Insira a descrição no campo Descrição do parâmetro de entrada. Essa descrição fornece ao LLM mais informações sobre o parâmetro, como o conteúdo esperado e as ações a serem realizadas.
5. 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.
```

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:

No console Google Cloud , acesse a página do Gemini Enterprise.

Gemini Enterprise
Clique no nome do app que inclui o agente que você quer atualizar.
Clique em Agentes.
Clique no nome do agente do mecanismo de agente que você quer atualizar e em Editar.
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.
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 do 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.

Exemplo de comando e resultado

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890/operations/delete-agent-12345678901234567890",
  "done": true
}

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`

Registrar e gerenciar agentes do ADK hospedados no Vertex AI Agent Engine Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Configurar detalhes de autorização

Receber detalhes da autorização

Adicionar um recurso de autorização ao Gemini Enterprise

REST

Registrar um agente do ADK com o Gemini Enterprise

Console

REST

Listar agentes conectados a um app

REST

Conferir os detalhes de um agente do ADK

REST

Atualizar um agente do ADK

Console

REST

Excluir um agente do ADK

REST

Exemplo de comando e resultado

Localização do mecanismo de raciocínio

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