Utilizzare la registrazione automatica

Agent Registry può registrare gli agenti ospitati sui runtime supportati Google Cloud senza richiedere di chiamare manualmente l' API Agent Registry. A seconda del runtime, questa procedura di registrazione avviene automaticamente o richiede un passaggio di configurazione di attivazione durante il deployment.

Questo documento spiega come abilitare il rilevamento degli agenti sui runtime supportati. Se ospiti un agente esternamente o su un runtime non supportato, consulta Utilizzare la registrazione manuale.

I metadati e le funzionalità indicizzati per un agente durante la registrazione dipendono dal fatto che l'agente implementi il protocollo Agent2Agent (A2A). Per saperne di più, consulta Registrare gli agenti.

Prima di iniziare

Prima di registrare gli agenti, configura Agent Registry. Per verificare la registrazione, devi avere l'ID progetto.

Per utilizzare i comandi Google Cloud CLI in questo documento, assicurati di aver configurato l'ambiente gcloud CLI.

Registrare gli agenti da Agent Runtime

Se sviluppi ed esegui il deployment di agenti con Agent Runtime su Gemini Enterprise Agent Platform, la registrazione in Agent Registry è automatica.

Il protocollo Agent2Agent (A2A) è uno standard aperto che consente agli agenti di dichiarare le proprie funzionalità e la propria identità. L'esempio seguente mostra come eseguire il deployment di un agente che implementa il protocollo A2A in Agent Runtime. Per saperne di più, consulta Eseguire il deployment di un 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]"],
    },
)

Quando aggiorni o elimini l'agente in Agent Runtime, Agent Registry sincronizza automaticamente queste modifiche.

Registrare gli agenti Google integrati

Gli agenti Google integrati, come Google Workspace e Gemini Enterprise agenti, vengono registrati automaticamente in Agent Registry. Non è necessario eseguire passaggi di configurazione o deployment. Questi agenti vengono inseriti e sono disponibili per il rilevamento all'interno del registro.

Registrare gli agenti da GKE

Puoi registrare gli agenti di cui è stato eseguito il deployment su Google Kubernetes Engine (GKE) aggiungendo l'etichetta registry.gke.io/functional-type: "AGENT" ai deployment. Questa etichetta identifica il deployment come un carico di lavoro dell'agente AI, che indica al controller del runtime del cluster GKE di eseguire una scansione di introspezione nel cluster e di registrare l'agente con Agent Registry.

Per abilitare il rilevamento automatico delle competenze dell'agente, devi fornire anche l'annotazione a2a-protocol.org/agent-card. Il controller di inserimento GKE utilizza questa annotazione per eseguire query sulla scheda dell'agente A2A.

L'esempio seguente mostra un manifest di deployment dell'agente GKE che utilizza queste configurazioni. Per saperne di più, consulta Eseguire il deployment e l'orchestrazione degli agenti AI.

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 viene applicato il deployment, il controller del runtime del cluster GKE esegue automaticamente l'introspezione del container del carico di lavoro, esegue query sull'endpoint della scheda dell'agente dichiarato nell'annotazione e sincronizza i metadati dell'agente e le competenze A2A direttamente nel modello dei dati di Agent Registry.

Registrare gli agenti da Cloud Run

Puoi registrare gli agenti di cui è stato eseguito il deployment in Cloud Run specificando i flag --functional-type=agent e --identity-type=agent-identity durante il deployment. Il flag --functional-type=agent identifica il carico di lavoro Cloud Run come un agente AI anziché come un'applicazione containerizzata standard, indicando a Cloud Run di registrare l'agente con Agent Registry.

I carichi di lavoro configurati con --functional-type=agent devono specificare il flag --identity-type=agent-identity. Il deployment con qualsiasi altro tipo di identità genera un errore.

Puoi eseguire il deployment degli agenti come servizi o job Cloud Run. Per scoprire come eseguire il deployment di un agente come servizio o job in Cloud Run, consulta Configurare le funzionalità di Agent Platform per Cloud Run.

Durante la registrazione, Cloud Run aggiunge automaticamente il nome, l'endpoint URL e il tipo (AGENT) dell'agente al registro. Per saperne di più sul deployment degli agenti A2A in Cloud Run, consulta Eseguire il deployment degli agenti A2A in Cloud Run.

La registrazione automatica rileva solo le risorse di cui è stato eseguito il deployment nello stesso Google Cloud progetto. Per registrare gli agenti di cui è stato eseguito il deployment in progetti diversi, consulta la registrazione manuale.

Verificare la registrazione

Puoi verificare che Agent Registry abbia registrato correttamente gli agenti elencandoli:

Console

  1. Nella Google Cloud console, vai ad Agent Registry:

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

  3. Seleziona la scheda Agenti.

    La pagina mostra un elenco di tutti gli agenti registrati e i relativi dettagli, come nome, identificatore, descrizione, runtime e località.

  4. Filtra l'elenco in base alla località dell'agente o alla risorsa di runtime:

    • Per filtrare in base alla località, fai clic sul menu Località , seleziona le località che vuoi filtrare e fai clic su Applica.
    • Per filtrare in base al runtime, fai clic sul menu Runtime , seleziona i runtime che vuoi filtrare e fai clic su Applica.

    La pagina mostra un elenco filtrato degli agenti registrati per le condizioni selezionate.

gcloud

Puoi filtrare l'elenco in base ai metadati dell'agente. Assicurati di aver configurato l'ambiente Google Cloud CLI per Agent Registry, quindi esegui:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.
  • REGION: la regione del registro.
  • FILTER_EXPRESSION: l'espressione di filtro per gli agenti che vuoi filtrare. Ad esempio, per filtrare in base al nome visualizzato, puoi utilizzare displayName='DISPLAY_NAME'. Per filtrare in base all' identificatoreunivoco globale (URN), puoi utilizzare agentId='urn:agent:AGENT_URN'.

Gli agenti Google integrati utilizzano un formato URN che dipende dalla posizione in cui è stato eseguito il deployment dell'agente. Ad esempio, puoi scoprire gli agenti Google Workspace integrati filtrando l'elenco per il publisher googleapis.com utilizzando --filter="agentId:'urn:agent:googleapis.com:*'".

Terraform

Fai riferimento all'agente registrato in altre configurazioni Terraform utilizzando l'origine dati 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
}

Sostituisci quanto segue:

  • REGION: la regione del registro.
  • DISPLAY_NAME: il nome visualizzato dell'agente leggibile da una persona.