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.

Por padrão, o registro automático descobre recursos compatíveis implantados no projeto de governança em que o Agent Registry está ativado. Para descobrir agentes registrados automaticamente em vários projetos do Google Cloud , configure um limite de gerenciamento. Se você não usar um limite de gerenciamento, também poderá registrar manualmente um agente de outro projeto no projeto de governança.

Para agentes remotos hospedados externamente ou em ambientes de execução não compatíveis, é necessário usar o registro manual de 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.
Para uma configuração de projeto único, use o ID do projeto do projeto de governança em que o Agent Registry está ativado. Se você configurou um limite de gerenciamento para vários projetos, use o ID do projeto de gerenciamento para descoberta e registro em todo o limite ou especifique um ID de projeto de membro para operações de projeto único.
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
}