Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Usar o registro automático

O Agent Registry pode registrar agentes hospedados em ambientes de execução com suporte Google Cloud sem que você precise chamar manualmente a API Agent Registry. Dependendo do ambiente de execução, esse processo de registro acontece automaticamente ou exige uma etapa de configuração de ativação durante a implantação.

Este documento explica como ativar a descoberta de agentes em ambientes de execução com suporte. Se você hospedar um agente externamente ou em um ambiente de execução sem suporte, consulte Usar o registro manual.

Os metadados e as habilidades extraídos de um agente durante o registro dependem do protocolo dele. Para mais informações, consulte Registrar agentes.

Antes de começar

Antes de registrar agentes, configure o Agent Registry. Você precisa do ID do projeto para verificar o registro.

Para usar os comandos da Google Cloud CLI neste documento, verifique se você configurou o ambiente da CLI gcloud.

Registrar agentes do Agent Runtime

Se você desenvolver e implantar agentes com o Agent Runtime na Gemini Enterprise Agent Platform, o registro no Agent Registry será automático.

O protocolo Agent2Agent (A2A) é um padrão aberto que permite que os agentes declarem suas capacidades e identidade. O seguinte exemplo 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 o agente no Agent Runtime, o Agent Registry sincroniza automaticamente essas mudanças.

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 ficam disponíveis para descoberta no registro.

Registrar agentes do GKE

É possível registrar agentes implantados no Google Kubernetes Engine (GKE) adicionando o rótulo registry.gke.io/functional-type: "AGENT" às implantações. Esse rótulo identifica a implantação como um agente de IA, permitindo que o Agent Registry execute uma verificação de introspecção.

Para ativar a descoberta automatizada das habilidades do agente, também é necessário fornecer a anotação a2a-protocol.org/agent-card. O controlador de ingestão usa essa anotação para consultar o card do agente A2A. Além disso, configure a Identidade da carga de trabalho usando a anotação iam.gke.io/spiffe-identity-type: agent-identity para ajudar a ativar a comunicação autenticada segura.

O exemplo a seguir mostra um manifesto de implantação de agente do GKE usando essas configurações. Para mais informações, consulte Implantar e orquestrar agentes de IA.

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:
      annotations:
        # Workload Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
      labels:
        app: my-agent
    spec:
      containers:
      - name: server
        image: gcr.io/my-project/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
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

Quando a implantação é aplicada, o cluster do GKE tenta buscar automaticamente os metadados do agente e os sincroniza diretamente no modelo de dados do Agent Registry.

Verificar o registro

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

Console

No Google Cloud console, acesse o Agent Registry:

Acessar o Agent Registry
No seletor de projetos, selecione o Google Cloud projeto 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 de execução que você quer filtrar e clique em Aplicar.
A página mostra 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 Google Cloud CLI para o Agent Registry e execute:

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

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

Terraform

Consulte o 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
}