Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Utilizza la registrazione automatica per gli agenti

Agent Registry ti consente di configurare la registrazione automatica degli agenti sui runtime Google Cloud supportati, in modo che gli sviluppatori e gli agenti orchestratore possano individuarli senza creare manualmente le risorse del registry. A seconda del runtime, la registrazione avviene per impostazione predefinita o tramite un passaggio di deployment di attivazione e i metadati indicizzati dipendono dal protocollo di implementazione.

La registrazione automatica rileva solo le risorse supportate di cui è stato eseguito il deployment all'interno del progetto di governance in cui è abilitato Agent Registry. Per registrare gli agenti remoti di cui è stato eseguito il deployment in altri progettiGoogle Cloud , consulta Registra un agente da un altro progetto. Per gli agenti remoti ospitati esternamente o su runtime non supportati, consulta Utilizza la registrazione manuale per gli agenti.

Metadati indicizzati automaticamente

I metadati e le funzionalità indicizzati per un agente durante la registrazione automatica dipendono dall'implementazione o meno del protocollo Agent2Agent (A2A) da parte dell'agente:

Agenti che implementano il protocollo A2A: Agent Registry esegue query sulla scheda dell'agente /.well-known/agent-card.json per estrarre automaticamente le skill A2A e le funzionalità pubblicizzate in Agent Registry.
Agenti che non implementano il protocollo A2A: Agent Registry registra l'agente, ma non può acquisire automaticamente i metadati, come l'URL dell'endpoint in cui è ospitato l'agente, l'identità dell'agente e le competenze A2A. Si tratta di agenti che espongono, ad esempio, endpoint REST o gRPC standard. Per associare le funzionalità ad agenti non A2A, utilizza la registrazione manuale o registra le skill.

Prima di iniziare

Configura Agent Registry.
Recupera l'ID progetto per il progetto di governance in cui è abilitato Agent Registry.
Per utilizzare i comandi di Google Cloud CLI in questo documento, configura l'ambiente gcloud CLI.

Registra gli agenti da Agent Runtime

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

L'esempio seguente mostra come eseguire il deployment di un agente che implementa il protocollo A2A in Agent Runtime. Per saperne di più, consulta Esegui 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 le modifiche.

Registra gli agenti Google integrati

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

Registra gli agenti da GKE

Per registrare gli agenti di cui è stato eseguito il deployment su Google Kubernetes Engine (GKE), aggiungi le etichette e le annotazioni Kubernetes richieste al manifest di deployment. L'esempio seguente mostra un manifest GKE che definisce un Deployment Kubernetes e un Service Kubernetes configurati per la registrazione automatica:

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

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Per configurare e applicare il manifest di deployment, segui questi passaggi:

In metadata.labels del manifest Deployment, aggiungi l'etichetta registry.gke.io/functional-type: "AGENT". Questa etichetta identifica il deployment come workload di un agente AI, che indica al controller di runtime del cluster GKE di ispezionare il workload e registrare l'agente in Agent Registry.

Nota: GKE supporta anche l'annotazione apphub.cloud.google.com/functional-type: "AGENT" per la compatibilità con le versioni precedenti. Tuttavia, utilizza l'etichetta registry.gke.io/functional-type: "AGENT" per i tuoi deployment GKE.
In metadata.annotations del manifest Deployment, attiva il rilevamento automatico delle skill A2A dell'agente fornendo l'annotazione a2a-protocol.org/agent-card. Il controller di importazione GKE utilizza questa annotazione per eseguire query sulla scheda dell'agente A2A.
In spec.template.metadata.annotations del template del pod, abilita la comunicazione autenticata configurando l'identità dell'agente con l'annotazione iam.gke.io/spiffe-identity-type: agent-identity.
Applica il manifest di deployment al tuo cluster. Per saperne di più, consulta Esegui il deployment e l'orchestrazione degli agenti AI.

Quando applichi il deployment, il controller di runtime del cluster GKE ispeziona automaticamente il container del workload ed esegue query sull'endpoint della scheda dell'agente dichiarato nell'annotazione. Quindi sincronizza i metadati dell'agente e le competenze A2A direttamente in una risorsa di rilevamento Agent di sola lettura in Agent Registry.

Registra gli agenti da Cloud Run

Puoi registrare automaticamente gli agenti quando li esegui il deployment come servizi o job Cloud Run specificando i flag --functional-type=agent e --identity-type=agent-identity. Il flag --functional-type=agent identifica il servizio o il job Cloud Run come agente AI anziché come workload containerizzato standard, indicando a Cloud Run di registrare l'agente in Agent Registry. Durante la registrazione, Cloud Run aggiunge automaticamente il nome dell'agente e il tipo AGENT al registry.

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

Per configurare la registrazione automatica su un servizio o un job Cloud Run nuovo o esistente, consulta Configura le funzionalità di Gemini Enterprise Agent Platform per Cloud Run. Per preparare, containerizzare ed eseguire il deployment di un agente conforme ad A2A su Cloud Run, consulta Esegui il deployment degli agenti A2A su Cloud Run.

Verifica la registrazione

Puoi verificare che Agent Registry abbia registrato correttamente i tuoi agenti elencandoli:

Console

Nella console Google Cloud , vai a Agent Registry:

Vai ad Agent Registry
Nel selettore di progetti, seleziona il progetto Google Cloud in cui hai configurato Agent Registry.
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à.
Filtra l'elenco in base alla località dell'agente o alla sua risorsa di runtime:
- Per filtrare in base alla località, fai clic sul menu Località, seleziona le località da 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 gcloud CLI per Agent Registry, quindi esegui il comando gcloud agent-registry agents list:

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 registry.
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'identificatore dell'agente (URN) univoco a livello globale, puoi utilizzare agentId='urn:agent:AGENT_URN'.

Gli agenti Google integrati utilizzano un formato di identificatore dell'agente (URN) che dipende dalla posizione in cui viene 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
}