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

Utilizzare la registrazione manuale

È necessaria la registrazione manuale in Agent Registry per gli agenti ospitati al di fuori diGoogle Cloud, in esecuzione su runtime non supportati o di cui è stato eseguito il deployment in diversi progetti Google Cloud . Questo documento mostra come registrare manualmente gli agenti in Agent Registry.

Avviso:questa funzionalità non è supportata nelle località multi-regionali us e eu. Devi utilizzare una regione supportata o la località global. Per saperne di più, consulta Località del registro degli agenti.

Prima di iniziare

Prima di iniziare, configura il registro degli agenti. Per eseguire queste attività, devi disporre dell'ID progetto.

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per registrare manualmente gli agenti in Agent Registry, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

Per registrare gli agenti in Agent Registry: Agent Registry API Editor (roles/agentregistry.editor)
Per la registrazione tra progetti, per accedere ai metadati dell'agente in un progetto remoto: Agent Registry API Viewer (roles/agentregistry.viewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Non sono necessarie autorizzazioni aggiuntive se l'endpoint dell'agente o la scheda dell'agente è accessibile tramite URL pubblici standard o autenticato tramite credenziali preconfigurate.

Registra un agente conforme ad A2A

Se il tuo agente remoto implementa la specifica Agent2Agent (A2A), indirizza direttamente il registro degli agenti al payload agent-card.json dell'agente. Il registro sincronizza automaticamente la scheda dell'agente e indicizza le competenze A2A disponibili dell'agente per il rilevamento.

Per registrare l'agente:

Console

Nella console Google Cloud , vai a Registro agenti:

Vai a Agent Registry
Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.
Seleziona la scheda Agenti.
Fai clic su Aggiungi agente.
Nel riquadro Dettagli agente, inserisci i seguenti dettagli:
- Tipo: seleziona A2A.
- Regione: seleziona la posizione geografica in cui vuoi registrare l'agente.
Scegli una delle seguenti opzioni:
- Per registrare l'agente utilizzando il relativo URL della scheda dell'agente, seleziona la scheda Da URI e inserisci un URL valido nel campo URI. Poi, fai clic su Importa per ottenere la scheda dell'agente dall'URL.
- Per copiare e incollare i contenuti della scheda dell'agente, seleziona la scheda Incolla JSON e incolla tutti i contenuti del file agent-card.json.
Fai clic su Salva.

gcloud

I flag di specifica che utilizzi determinano a quale raccolta di risorse appartiene il tuo servizio. Per una mappatura completa dei flag alle raccolte di risorse, consulta Risorse API.

Per registrare un agente A2A, salva la scheda agente come file JSON locale, ad esempio agent-card.json, e procedi nel seguente modo:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

La dimensione massima del file delle specifiche è 10 KB.

Sostituisci quanto segue:

AGENT_NAME: il nome che vuoi dare al tuo agente, ad esempio my-support-agent.
PROJECT_ID: l'ID progetto.
REGION: la regione in cui vuoi registrare l'agente. Se non vuoi utilizzare una regione specifica, utilizza il valore global.
DISPLAY_NAME: il nome leggibile che vuoi dare al tuo agente, ad esempio Support Agent.

Terraform

Il blocco della specifica che configuri, ad esempio agent_spec, determina a quale raccolta di risorse appartiene il tuo servizio. Per una mappatura completa delle specifiche alle raccolte di risorse, consulta Risorse API.

Per registrare un agente conforme ad A2A, configura la risorsa google_agent_registry_service. Specifica il blocco agent_spec con il tipo A2A_AGENT_CARD e content che rappresenta il payload JSON della scheda dell'agente:

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type    = "A2A_AGENT_CARD"
    content = jsonencode({
      schemaVersion = "v1"
      displayName   = "DISPLAY_NAME"
      description   = "A custom support agent registered using Terraform."
      skills = [
        {
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

Sostituisci quanto segue:

REGION: la regione in cui registri l'agente.
AGENT_NAME: Il nome univoco che vuoi assegnare al tuo agente, ad esempio my-support-agent.
DISPLAY_NAME: il nome leggibile che vuoi dare al tuo agente, ad esempio Support Agent.

Registra un agente REST standard

Gli agenti REST standard sono individuabili per nome e descrizione, ma non hanno skill A2A ricercabili, a meno che non adottino il protocollo A2A.

Per registrare un agente remoto che non implementa la specifica A2A, crea una risorsa Service configurata con --agent-spec-type=no-spec. Agent Registry genera quindi una risorsa Agent corrispondente nella raccolta agents.

L'utilizzo di --agent-spec-type=no-spec registra un agente, non una destinazione API di destinazione. Se vuoi registrare una destinazione API esterna a cui si connettono gli agenti, devi registrare un endpoint. Per istruzioni, vedi Registrare gli endpoint.

Per registrare l'agente:

Console

Nella console Google Cloud , vai a Registro agenti:

Vai a Agent Registry
Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.
Seleziona la scheda Agenti.
Fai clic su Aggiungi agente.
Nel riquadro Dettagli agente, inserisci i seguenti dettagli:
- Tipo: seleziona Non A2A.
- Nome: inserisci un nome visualizzato leggibile per l'agente, ad esempio Travel Agent.
- Descrizione: inserisci una descrizione delle funzionalità dell'agente, ad esempio A test agent that plans travel itineraries.
- Regione: seleziona la posizione geografica in cui vuoi registrare l'agente.
- Endpoint: inserisci l'endpoint in cui è ospitato l'agente.
Fai clic su Salva.

gcloud

I flag di specifica che utilizzi determinano a quale raccolta di risorse appartiene il tuo servizio. Per una mappatura completa dei flag alle raccolte di risorse, consulta Risorse API.

Se vuoi, puoi fornire l'interfaccia dell'endpoint HTTP/JSON definito con il flag --interfaces in modo che il registro stabilisca una connessione con l'agente.

Per registrare un agente REST standard:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

Sostituisci quanto segue:

AGENT_NAME: il nome che vuoi dare al tuo agente, ad esempio my-remote-rest-agent.
PROJECT_ID: l'ID progetto.
REGION: la regione del registro.
DISPLAY_NAME: il nome leggibile che vuoi dare al tuo agente, ad esempio Remote REST Agent.
ENDPOINT_URL: l'URL dell'endpoint API dell'agente, ad esempio https://api.remote-service.com/v1/agents/1234.
PROTOCOL: l'associazione del protocollo per l'endpoint. I valori validi sono http-json, grpc o jsonrpc.

Terraform

Per registrare un agente REST standard, configura la risorsa google_agent_registry_service con agent_spec impostato sul tipo NO_SPEC e definisci le connessioni dell'interfaccia dell'endpoint:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

Sostituisci quanto segue:

REGION: la regione in cui registri l'agente.
AGENT_NAME: Il nome univoco che vuoi assegnare al tuo agente, ad esempio my-remote-rest-agent.
DISPLAY_NAME: il nome leggibile che vuoi dare al tuo agente, ad esempio Remote REST Agent.
ENDPOINT_URL: l'URL dell'endpoint API dell'agente, ad esempio https://api.remote-service.com/v1/agents/1234.
PROTOCOL: l'associazione del protocollo per l'endpoint. I valori validi sono HTTP_JSON, GRPC o JSONRPC.

Registra un agente da un altro progetto

Se la tua organizzazione esegue il deployment di agenti in più progetti Google Cloude utilizza un Agent Gateway centrale per controllare il traffico in uscita, puoi registrare gli agenti dai progetti spoke o workload nel catalogo centrale di Agent Registry.

Poiché la registrazione automatica rileva solo le risorse create nello stesso progetto, devi registrare manualmente ogni agente remoto nel registry del progetto di governance centrale.

Considerazioni per la registrazione tra progetti

Prima di registrare agenti in più progetti, esamina quanto segue:

Località compatibili: l'istanza di Agent Registry, l'Agent Gateway e gli Agent Endpoint devono trovarsi nella stessa regione geografica o nella località global.
Limitazione del rilevamento automatico: il rilevamento automatico tra progetti non è supportato. Devi registrare manualmente ogni agente remoto.
Gestione del ciclo di vita: le voci manuali nel registro degli agenti non vengono aggiornate o eliminate automaticamente quando si verificano modifiche nel progetto remoto. Devi gestire il ciclo di vita di queste voci nel registro centrale quando gli agenti remoti vengono modificati o rimossi.
Solo modalità di uscita: la governance tra progetti con Agent Gateway è supportata solo per i gateway da agente a ovunque (in uscita). I gateway di ingresso da client ad agente richiedono che l'agente e il gateway si trovino nello stesso progetto.

Registra l'agente remoto

Per registrare manualmente un agente di un altro progetto:

Console

Nella console Google Cloud , vai a Registro agenti:

Vai a Agent Registry
Nel selettore di progetti, seleziona il progetto di governance centrale Google Cloud in cui vuoi registrare l'agente.
Seleziona la scheda Agenti.
Fai clic su Aggiungi agente.
Nel riquadro Dettagli agente, inserisci i seguenti dettagli:
- Tipo: seleziona A2A se l'agente remoto implementa il protocollo A2A o Non-A2A per un endpoint REST standard.
- Regione: seleziona la regione corrispondente al deployment del gateway centrale e dell'agente remoto.
Fornisci l'endpoint dell'agente:
- Per gli agenti A2A, seleziona Da URI e inserisci l'URL della scheda dell'agente remoto oppure seleziona Incolla JSON e incolla i contenuti di agent-card.json.
- Per gli agenti non A2A, inserisci l'URL Endpoint dell'agente remoto.
Fai clic su Salva.

gcloud

I flag di specifica che utilizzi determinano a quale raccolta di risorse appartiene il tuo servizio. Per una mappatura completa dei flag alle raccolte di risorse, consulta Risorse API.

Agente A2A: per registrare un agente A2A da un altro progetto utilizzando gcloud CLI, esegui il seguente comando nel progetto di governance centrale:

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

Agente REST: per registrare un agente REST standard da un altro progetto, esegui il seguente comando nel progetto di governance centrale:

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL

Sostituisci quanto segue:

AGENT_NAME: il nome dell'agente nel registro centrale, ad esempio remote-support-agent.
CENTRAL_PROJECT_ID: l'ID progetto del progetto di governance centrale.
REGION: la regione in cui registri l'agente.
DISPLAY_NAME: Il nome leggibile dell'agente, ad esempio Remote Support Agent.
REMOTE_ENDPOINT_URL: l'URL dell'endpoint dell'agente in esecuzione nel progetto remoto, ad esempio https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app.
PROTOCOL: l'associazione del protocollo per l'endpoint. I valori validi sono http-json, grpc o jsonrpc.

Terraform

Per registrare un agente remoto in un progetto di governance centrale utilizzando Terraform, configura la risorsa google_agent_registry_service e specifica il progetto centrale:

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project REMOTE_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "REMOTE_ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.remote_agent.registry_resource
}

Sostituisci quanto segue:

CENTRAL_PROJECT_ID: l'ID progetto del progetto di governance centrale.
REGION: la regione in cui registri l'agente.
AGENT_NAME: il nome univoco dell'agente nel registro, ad esempio remote-support-agent.
DISPLAY_NAME: Il nome leggibile dell'agente, ad esempio Remote Support Agent.
REMOTE_PROJECT_ID: l'ID progetto in cui è ospitato l'agente.
REMOTE_ENDPOINT_URL: l'URL dell'endpoint dell'agente in esecuzione nel progetto remoto.
PROTOCOL: l'associazione del protocollo per l'endpoint. I valori validi sono HTTP_JSON, GRPC o JSONRPC.

Verifica la registrazione

Dopo aver registrato l'agente, verifica che Agent Registry abbia elaborato correttamente Service e creato la risorsa Agent corrispondente:

Console

Nella console Google Cloud , vai a Registro agenti:

Vai a Agent Registry
Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.
Seleziona la scheda Agenti.

La pagina mostra un elenco di tutti gli agenti registrati e i relativi dettagli.

gcloud

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

Se hai più agenti o se vuoi confermare la registrazione di un singolo agente, puoi filtrare l'elenco in base ai metadati dell'agente:

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

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto.
REGION: la regione in cui vuoi registrare l'agente. Se non vuoi utilizzare una regione specifica, utilizza il valore global.
FILTER_EXPRESSION: l'espressione di filtro per gli agenti che vuoi filtrare. Ad esempio, per filtrare per nome visualizzato, puoi utilizzare displayName='DISPLAY_NAME'. Per filtrare in base all'identificatore (URN) univoco a livello globale, puoi utilizzare agentId='urn:agent:AGENT_URN'.

Terraform

Fai riferimento al tuo 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 leggibile dell'agente.

Passaggi successivi

Scopri come gestire gli agenti registrati.
Scopri di più sulla registrazione automatica, il metodo consigliato per registrare gli agenti di cui è stato eseguito il deployment nei runtime gestiti.

Utilizzare la registrazione manuale Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Ruoli obbligatori

Registra un agente conforme ad A2A

Console

gcloud

Terraform

Registra un agente REST standard

Console

gcloud

Terraform

Registra un agente da un altro progetto

Considerazioni per la registrazione tra progetti

Registra l'agente remoto

Console

gcloud

Terraform

Verifica la registrazione

Console

gcloud

Terraform

Passaggi successivi

Utilizzare la registrazione manuale