Usar o registro manual

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

É necessário fazer o registro manual no Agent Registry para agentes hospedados fora do Google Cloud Google Cloud. Este documento mostra como registrar agentes manualmente no Agent Registry.

Observação: o registro manual não é compatível com os locais multirregionais us e eu. É necessário registrar recursos em uma região compatível ou no global local. Para mais informações, consulte Locais do Agent Registry.

Antes de começar

Antes de começar, configure o Agent Registry. Você precisa do ID do projeto para realizar essas tarefas.

Para usar os comandos da CLI gcloud neste documento, configure o ambiente da Google Cloud CLI.

Funções exigidas

Para receber as permissões necessárias para registrar agentes manualmente no Agent Registry, peça ao administrador para conceder a você o papel do IAM de Editor da API Agent Registry (roles/agentregistry.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando personalizados papéis ou outros predefinidos papéis.

Registrar um agente compatível com A2A

Se o agente remoto implementar a especificação do Agent2Agent (A2A), direcione o Agent Registry para o payload agent-card.json do agente. O registro sincroniza automaticamente o card do agente e indexa as habilidades disponíveis do agente para descoberta.

Siga estas etapas para registrar o agente:

Console

1. No Google Cloud console, acesse o Agent Registry:

   Acessar o Agent Registry

2. No seletor de projetos, selecione o Google Cloud projeto em que você configurou o Agent Registry.

3. Selecione a guia Agentes.

4. Clique em Adicionar agente.

5. No painel Detalhes do agente , insira um nome de exibição, uma descrição e selecione a região geográfica.

6. Para o tipo de agente, selecione A2A.

7. Na seção de especificação do agente, selecione a guia Colar JSON e cole todo o conteúdo do arquivo agent-card.json.

8. Clique em Salvar.

gcloud

Para registrar um agente A2A, salve o card do agente como um arquivo JSON local, por exemplo, agent-card.json, e faça o seguinte:

gcloud alpha agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

Observação: o arquivo de especificação do agente que você fizer o upload não pode exceder 10 KB.

Substitua:

• AGENT_NAME: o nome que você quer dar ao agente, por exemplo, my-support-agent.
• PROJECT_ID: o ID do projeto.
• REGION: a região do registro.
• DISPLAY_NAME: o nome legível que você quer dar ao agente, por exemplo, Support Agent.

Registrar um agente REST padrão

Os agentes REST padrão podem ser descobertos por nome e descrição, mas não têm habilidades pesquisáveis, a menos que adotem o A2A protocolo.

Se você quiser registrar um agente remoto que não implementa a especificação A2A, como um endpoint de API REST ou SaaS padrão, a API Agent Registry cria um recurso Service sem especificação de protocolo do agente.

Siga estas etapas para registrar o agente:

Console

1. No Google Cloud console, acesse o Agent Registry:

   Acessar o Agent Registry

2. No seletor de projetos, selecione o Google Cloud projeto em que você configurou o Agent Registry.

3. Selecione a guia Agentes.

4. Clique em Adicionar agente.

5. No painel Detalhes do agente , insira um nome de exibição, uma descrição e selecione a região geográfica.

6. Para o tipo de agente, selecione a opção que indica nenhuma especificação, como Não A2A.

7. Insira o endpoint em que o agente está hospedado e selecione a vinculação de protocolo, se necessário, como HTTP_JSON.

8. Clique em Salvar.

gcloud

Também é possível fornecer a interface de endpoint HTTP/JSON definida com a flag --interfaces para que o registro estabeleça uma conexão com o agente.

Para registrar um agente REST padrão, faça o seguinte:

gcloud alpha agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

Substitua:

• AGENT_NAME: o nome que você quer dar ao agente, por exemplo, my-remote-rest-agent.
• PROJECT_ID: o ID do projeto.
• REGION: a região do registro.
• DISPLAY_NAME: o nome legível que você quer dar ao agente, por exemplo, Remote REST Agent.
• ENDPOINT_URL: o URL do endpoint do serviço do agente, por exemplo, https://api.remote-service.com/v1/agents/1234.
• PROTOCOL: a vinculação de protocolo para o endpoint. Os valores válidos são HTTP_JSON, GRPC ou JSONRPC.

Verificar o registro

Depois de registrar o agente, verifique se o Agent Registry processou o Service e criou o recurso Agent correspondente:

Console

1. No Google Cloud console, acesse o Agent Registry:

   Acessar o Agent Registry

2. No seletor de projetos, selecione o Google Cloud projeto em que você configurou o Agent Registry.

3. Selecione a guia Agentes.

   A página precisa mostrar uma lista de todos os agentes registrados e os detalhes deles.

gcloud

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

Se você tiver vários agentes ou quiser confirmar o registro de um único agente, filtre a lista pelos metadados do agente:

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Substitua:

• PROJECT_ID: o ID do projeto.
• REGION: a região do registro.
• FILTER_EXPRESSION: a expressão de filtro para os agentes que você quer filtrar. Por exemplo, para filtrar por nome de exibição, você pode usar displayName='DISPLAY_NAME'. Para filtrar pelo identificador globalmente exclusivo (URN), use agentId='urn:agent:AGENT_URN'.