Usar o registro automático

O Agent Registry pode registrar agentes hospedados em ambientes de execução compatíveis Google Cloud sem que você precise chamar manualmente a API do 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 compatíveis. Se você hospedar um agente externamente ou em um ambiente de execução não compatível, consulte Usar o registro manual.

Os metadados e os recursos indexados para um agente durante o registro dependem de o agente implementar o protocolo Agent2Agent (A2A). 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 seus recursos 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 essas mudanças automaticamente.

Registrar agentes integrados do Google

Os agentes integrados do Google, como Google Workspace e Gemini Enterprise agentes, 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 uma carga de trabalho de agente de IA, que instrui o controlador de ambiente de execução do cluster do GKE a realizar uma verificação de introspecção no cluster e registrar o agente no Agent Registry.

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 do GKE usa essa anotação para consultar o cartão do agente A2A.

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:
      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 controlador de ambiente de execução do cluster do GKE inspeciona automaticamente o contêiner da carga de trabalho, consulta o endpoint do cartão do agente declarado na anotação e sincroniza os metadados e as habilidades A2A do agente diretamente no modelo de dados do Agent Registry.

Registrar agentes do Cloud Run

É possível registrar agentes implantados no Cloud Run especificando as flags --functional-type=agent e --identity-type=agent-identity durante a implantação. A flag --functional-type=agent identifica a carga de trabalho do Cloud Run como um agente de IA em vez de um aplicativo em contêineres padrão, instruindo o Cloud Run a registrar o agente no Agent Registry.

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.

É possível implantar agentes como serviços ou jobs do Cloud Run. Para saber como implantar um agente como um serviço ou job no Cloud Run, consulte Configurar recursos da Agent Platform para o Cloud Run.

Durante o registro, o Cloud Run adiciona automaticamente o nome, o endpoint de URL e o tipo (AGENT) do agente ao registro. Para mais informações sobre como implantar agentes A2A no Cloud Run, consulte Implantar agentes A2A no Cloud Run.

O registro automático só descobre recursos implantados no mesmo Google Cloud projeto. Para registrar agentes implantados em projetos diferentes, consulte o registro manual.

Verificar o registro

É possível verificar se o Agent Registry registrou seus agentes listando-os:

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

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
}