O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Usar o registro automático para agentes

O Registro de Agentes permite configurar o registro automático de agentes em ambientes de execução do Google Cloud compatíveis para que os desenvolvedores e os agentes de orquestração possam descobri-los sem criar manualmente recursos de registro. Dependendo do ambiente de execução, o registro acontece por padrão ou por uma etapa de implantação opcional, e os metadados indexados dependem do protocolo de implementação.

O registro automático só descobre recursos compatíveis implantados no projeto de governança em que o Agent Registry está ativado. Para registrar agentes remotos implantados em outros projetos doGoogle Cloud , consulte Registrar um agente de outro projeto. Para agentes remotos hospedados externamente ou em ambientes de execução não compatíveis, consulte Usar o registro manual para agentes.

Metadados indexados automaticamente

Os metadados e os recursos indexados para um agente durante o registro automático dependem de o agente implementar o protocolo Agent2Agent (A2A):

Agentes que implementam o protocolo A2A: o registro de agentes consulta o card de agente do /.well-known/agent-card.json para extrair automaticamente as habilidades e os recursos A2A anunciados no registro de agentes.
Agentes que não implementam o protocolo A2A: o Agent Registry registra o agente, mas não pode capturar automaticamente metadados como o URL do endpoint em que o agente está hospedado, a identidade do agente e as habilidades de A2A. São agentes que expõem, por exemplo, endpoints REST ou gRPC padrão. Para associar recursos a agentes que não são A2A, use o registro manual ou registre habilidades.

Antes de começar

Configure o Agent Registry.
Consiga o ID do projeto para o projeto de governança em que o Agent Registry está ativado.
Para usar os comandos da Google Cloud CLI neste documento, configure o ambiente da CLI gcloud.

Registrar agentes do Agent Runtime

Se você desenvolve e implanta agentes com o Agent Runtime na Gemini Enterprise Agent Platform, o registro no Agent Registry é automático.

O exemplo a seguir mostra como implantar um agente que implementa o protocolo A2A no Agent Runtime. Para mais informações, consulte Implantar um agente.

# Create and deploy the agent
# This action automatically registers the agent in Agent Registry
remote_agent = client.agent_engines.create(
    agent=my_a2a_agent, # Your defined A2A object
    config={
        "display_name": "my-support-agent",
        "description": "An agent that handles support tickets.",
        "requirements": ["google-cloud-aiplatform[agent_engines,langchain]"],
    },
)

À medida que você atualiza ou exclui seu agente no Agent Runtime, o Agent Registry sincroniza essas mudanças automaticamente.

Registrar agentes integrados do Google

Os agentes integrados do Google, como os do Google Workspace e do Gemini Enterprise, são registrados automaticamente no Agent Registry. Não é necessário realizar nenhuma etapa de configuração ou implantação. Esses agentes são ingeridos e disponibilizados para descoberta no seu registro.

Registrar agentes do GKE

Para registrar agentes implantados no Google Kubernetes Engine (GKE), adicione os rótulos e as anotações necessários do Kubernetes ao manifesto de implantação. O exemplo a seguir mostra um manifesto do GKE que define um Deployment e um Service do Kubernetes configurados para registro automático:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
  labels:
    # GKE takes this label and registers the agent to Agent Registry
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  selector:
    matchLabels:
      app: my-agent
  template:
    metadata:
      labels:
        app: my-agent
      annotations:
        # Agent Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
    spec:
      containers:
      - name: server
        image: gcr.io/PROJECT_ID/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
# Kubernetes Service for in-cluster network routing to the agent pod
apiVersion: v1
kind: Service
metadata:
  name: my-agent-service
  labels:
    app: my-agent
spec:
  type: ClusterIP
  ports:
  - port: 8080
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: my-agent

Substitua PROJECT_ID pelo Google Cloud ID do projeto.

Para configurar e aplicar o manifesto de implantação, faça o seguinte:

No metadata.labels do manifesto Deployment, adicione o rótulo registry.gke.io/functional-type: "AGENT". Esse rótulo identifica a implantação como uma carga de trabalho de agente de IA, o que instrui o controlador de ambiente de execução do cluster do GKE a inspecionar a carga de trabalho e registrar o agente no Agent Registry.

Observação: o GKE também é compatível com a anotação apphub.cloud.google.com/functional-type: "AGENT" para compatibilidade com versões anteriores. No entanto, use o rótulo registry.gke.io/functional-type: "AGENT" para as implantações do GKE.
No metadata.annotations do manifesto Deployment, ative a descoberta automática das habilidades de A2A do agente fornecendo a anotação a2a-protocol.org/agent-card. O controlador de ingestão do GKE usa essa anotação para consultar o card do agente A2A.
Em spec.template.metadata.annotations do modelo de pod, ative a comunicação autenticada configurando a Identidade do agente com a anotação iam.gke.io/spiffe-identity-type: agent-identity.
Aplique o manifesto de implantação ao cluster. Para mais informações, consulte Implantar e orquestrar agentes de IA.

Quando você aplica a implantação, o controlador de ambiente de execução do cluster do GKE inspeciona automaticamente o contêiner de carga de trabalho e consulta o endpoint do card do agente declarado na anotação. Em seguida, ele sincroniza os metadados do agente e as habilidades de A2A diretamente em um recurso de descoberta Agent somente leitura no Agent Registry.

Registrar agentes do Cloud Run

É possível registrar agentes automaticamente ao implantá-los como serviços ou jobs do Cloud Run especificando as flags --functional-type=agent e --identity-type=agent-identity. A flag --functional-type=agent identifica o serviço ou job do Cloud Run como um agente de IA, em vez de uma carga de trabalho conteinerizada padrão, instruindo o Cloud Run a registrar o agente no Agent Registry. Durante o registro, o Cloud Run adiciona automaticamente o nome do agente e o tipo AGENT ao registro.

As cargas de trabalho configuradas com --functional-type=agent precisam especificar a flag --identity-type=agent-identity. A implantação com qualquer outro tipo de identidade resulta em um erro.

Para configurar o registro automático em um serviço ou job novo ou atual do Cloud Run, consulte Configurar recursos da Gemini Enterprise Agent Platform para o Cloud Run. Para preparar, conteinerizar e implantar um agente compatível com A2A no Cloud Run, consulte Implantar agentes A2A no Cloud Run.

Verificar registro

Para verificar se o Agent Registry registrou seus agentes, liste-os:

Console

No console do Google Cloud , acesse Agent Registry:

Acessar o Agent Registry
No seletor de projetos, selecione o projeto do Google Cloud em que você configurou o Agent Registry.
Selecione a guia Agentes.

A página mostra uma lista de todos os agentes registrados e os detalhes deles, como nome, identificador, descrição, ambiente de execução e local.
Filtre a lista pelo local do agente ou pelo recurso de ambiente de execução:
- Para filtrar por local, clique no menu Local, selecione os locais que você quer filtrar e clique em Aplicar.
- Para filtrar por ambiente de execução, clique no menu Ambiente de execução, selecione os ambientes que você quer filtrar e clique em Aplicar.
A página exibe uma lista filtrada dos agentes registrados para as condições selecionadas.

gcloud

É possível filtrar a lista pelos metadados do agente. Verifique se você configurou o ambiente da CLI gcloud para o Agent Registry e execute o comando gcloud agent-registry agents list:

gcloud 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, use displayName='DISPLAY_NAME'. Para filtrar pelo identificador de agente globalmente exclusivo (URN), use agentId='urn:agent:AGENT_URN'.

Os agentes integrados do Google usam um formato de identificador de agente (URN) que depende de onde o agente é implantado. Por exemplo, é possível descobrir agentes integrados do Google Workspace filtrando sua lista pelo editor googleapis.com usando --filter="agentId:'urn:agent:googleapis.com:*'".

Terraform

Faça referência ao agente registrado em outras configurações do Terraform usando a fonte de dados google_agent_registry_agent:

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}