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

Utilizza la registrazione manuale per gli agenti

Il registry degli agenti ti consente di registrare manualmente gli agenti REST standard e conformi ad A2A ospitati al di fuori di Google Cloud, in esecuzione su runtime non supportati o di cui è stato eseguito il deployment in progetti Google Cloud diversi. Creando una risorsa Service per questi agenti, rendi i loro endpoint e le loro funzionalità rilevabili nel tuo ecosistema AI.

Agent Registry utilizza un progetto di governance Google Cloudcentrale. In questo documento, il termine remoto si riferisce agli agenti ospitati al di fuori del progetto di governance, ad esempio in progetti Google Cloud separati, ambienti on-premise o cloud esterni, o in esecuzione su runtime non supportati. Poiché la registrazione automatica rileva solo le risorse supportate di cui è stato eseguito il deployment nel progetto di governance in cui è abilitato Agent Registry, devi registrare manualmente gli agenti remoti nel registry del progetto di governance.

Tipi di agenti e limitazioni

Puoi registrare manualmente due tipi di agenti:

Agenti conformi ad A2A: agenti che implementano la specifica Agent2Agent (A2A) con il tipo A2A_AGENT_CARD. Il registry scansiona l'endpoint della agent-card.json scheda dell'agente per indicizzare le sue skill A2A.
Agenti REST standard: agenti remoti che non implementano la specifica A2A e utilizzano il tipo NO_SPEC, ad esempio agenti che espongono un endpoint API REST.

La registrazione manuale non è supportata nelle località multiregionali us e eu; devi utilizzare una regione supportata o la località global. Per saperne di più, consulta Località di Agent Registry.

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.

Ruoli obbligatori

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

Per registrare gli agenti in Agent Registry: Agent Registry API Editor (roles/agentregistry.editor)
Per la registrazione tra progetti, per accedere ai metadati degli agenti in un altro progetto Google Cloud : 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 o la scheda dell'agente sono accessibili tramite URL pubblici standard o autenticati tramite credenziali preconfigurate.

Registra un agente conforme ad A2A

Se l'agente remoto implementa la specifica A2A, indirizza il Registro degli agenti al payload agent-card.json dell'agente. Il registry sincronizza automaticamente la scheda dell'agente e indicizza le competenze A2A disponibili dell'agente per il rilevamento.

Per registrare l'agente, segui questi passaggi:

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.
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 l'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 i contenuti completi del file agent-card.json.
Fai clic su Salva.

gcloud

I flag di specifica che utilizzi determinano la raccolta di risorse a cui appartiene il componente. Per una mappatura completa dei flag alle raccolte di risorse, consulta [Risorse di servizio e risorse di rilevamento](/agent-registry/data-model#service-resources).

Per registrare un agente A2A, salva la scheda dell'agente come file JSON locale, ad esempio agent-card.json, quindi esegui il comando gcloud agent-registry services create:

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 di specifica è 10 kB.

Sostituisci quanto segue:

AGENT_NAME: l'ID che vuoi assegnare al tuo agente, ad esempio my-support-agent. L'ID deve contenere da 4 a 63 caratteri e può includere solo lettere minuscole, numeri e trattini.
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 assegnare all'agente, ad esempio Support Agent.

Terraform

Il blocco di specifica che configuri determina la raccolta di risorse a cui appartiene il componente. Per una mappatura completa delle specifiche alle raccolte di risorse, consulta [Risorse di servizio e risorse di rilevamento](/agent-registry/data-model#service-resources).

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 il 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({
      name               = "AGENT_NAME"
      description        = "A custom support agent registered using Terraform."
      version            = "1.0.0"
      capabilities       = {}
      defaultInputModes  = ["text/plain"]
      defaultOutputModes = ["text/plain"]
      supportedInterfaces = [
        {
          url             = "https://api.example.com/v1/agents/support"
          protocolBinding = "JSONRPC"
          protocolVersion = "1.0"
        }
      ]
      skills = [
        {
          id          = "customer_lookup"
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
          tags        = ["support", "customer"]
        }
      ]
    })
  }
}

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: l'ID univoco che vuoi assegnare al tuo agente, ad esempio my-support-agent. L'ID deve contenere da 4 a 63 caratteri e può includere solo lettere minuscole, numeri e trattini.
DISPLAY_NAME: il nome leggibile che vuoi assegnare all'agente, ad esempio Support Agent.

Registra un agente REST standard

Gli agenti REST standard sono scopribili per nome e descrizione, ma non hanno competenze 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 non A2A. Agent Registry genera una risorsa Agent di sola lettura per l'agente non A2A nella raccolta agents, incluso l'URL dell'endpoint, in modo che gli orchestratori, gli altri agenti e Agent Gateway possano rilevare l'agente e connettersi.

Se imposti il tipo di agente su Non-A2A nella console Google Cloud o utilizzi il flag --agent-spec-type=no-spec nei comandi gcloud CLI, viene registrato un agente AI. Non registrare l'agente separatamente come risorsa Endpoint. Registra una risorsa Endpoint solo se vuoi gestire le connessioni in uscita dell'agente a un'API REST o a un servizio web non dell'agente, ad esempio un'API di database, un'API SaaS di terze parti o le API di Google. Per istruzioni sulla registrazione di destinazioni API non agente, consulta Registra gli endpoint.

Per registrare l'agente, segui questi passaggi:

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.
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

Per registrare un agente REST standard e specificare l'URL dell'endpoint in cui è ospitato l'agente, esegui il comando gcloud agent-registry services create con --agent-spec-type=no-spec e il flag --interfaces:

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: l'ID che vuoi assegnare al tuo agente, ad esempio my-remote-rest-agent. L'ID deve contenere da 4 a 63 caratteri e può includere solo lettere minuscole, numeri e trattini.
PROJECT_ID: l'ID progetto
REGION: la regione del registry.
DISPLAY_NAME: il nome leggibile che vuoi assegnare all'agente, ad esempio Remote REST Agent.
ENDPOINT_URL: l'URL dell'endpoint API dell'agente, ad esempio https://api.example.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: l'ID univoco che vuoi assegnare al tuo agente, ad esempio my-remote-rest-agent. L'ID deve contenere da 4 a 63 caratteri e può includere solo lettere minuscole, numeri e trattini.
DISPLAY_NAME: il nome leggibile che vuoi assegnare all'agente, ad esempio Remote REST Agent.
ENDPOINT_URL: l'URL dell'endpoint API dell'agente, ad esempio https://api.example.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 degli agenti in più progetti Google Cloud e utilizza un Agent Gateway centrale in modalità di traffico in uscita Agent-to-Anywhere per gestire il traffico, devi registrare manualmente ogni agente remoto di questi altri progetti Google Cloud nel registry del progetto di governancecentrale. Per saperne di più su questa architettura, consulta Pattern di deployment di esempio.

Considerazioni per la registrazione tra progetti

Prima di registrare gli agenti in più progetti, tieni presente quanto segue:

Località compatibili: l'istanza di Agent Registry, 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 in Agent Registry non vengono aggiornate o eliminate automaticamente quando si verificano modifiche nell'altro progettoGoogle Cloud in cui viene eseguito l'agente. Devi gestire il ciclo di vita di queste voci nel registry centrale quando gli agenti remoti vengono modificati o rimossi.
Solo modalità in uscita: la governance tra progetti con Agent Gateway è supportata solo per i gateway in uscita da agente a ovunque. I gateway in entrata da client ad agente richiedono che l'agente e il gateway si trovino nello stesso progetto.

Registra un agente remoto

Per registrare manualmente un agente da un altro progetto, segui questi passaggi:

Console

Nella console Google Cloud , vai a Agent Registry:

Vai ad Agent Registry
Nel selettore di progetti, seleziona il progetto di governance centrale 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 agent-card.json.
- Per gli agenti non A2A, inserisci l'URL dell'endpoint dell'agente remoto.
Fai clic su Salva.

gcloud

Agente A2A: per registrare un agente A2A da un altro progetto, esegui il comando gcloud agent-registry services create:

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 comando gcloud agent-registry services create:

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: l'ID dell'agente nel registro centrale, ad esempio remote-support-agent. L'ID deve contenere da 4 a 63 caratteri e può includere solo lettere minuscole, numeri e trattini.
CENTRAL_PROJECT_ID: l'ID progetto del progetto di governance centrale.
REGION: la regione in cui registri l'agente e in cui si trovano il gateway centrale e l'agente remoto, ad esempio us-central1.
DISPLAY_NAME: il nome leggibile dell'agente, ad esempio Remote Support Agent.
REMOTE_ENDPOINT_URL: l'URL dell'endpoint dell'agente remoto in esecuzione nell'altro progetto Google Cloud , ad esempio https://remote-support-agent-abc123.us-central1.run.app o https://api.example.com/v1/agents/support.
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 AGENT_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 e in cui si trovano il gateway centrale e l'agente remoto, ad esempio us-central1.
AGENT_NAME: l'ID univoco dell'agente nel registry, ad esempio remote-support-agent. L'ID deve contenere da 4 a 63 caratteri e può includere solo lettere minuscole, numeri e trattini.
DISPLAY_NAME: il nome leggibile dell'agente, ad esempio Remote Support Agent.
AGENT_PROJECT_ID: l'ID progetto del progetto Google Cloud separato in cui è ospitato l'agente remoto.
REMOTE_ENDPOINT_URL: l'URL dell'endpoint dell'agente remoto in esecuzione nell'altro progetto Google Cloud , ad esempio https://remote-support-agent-abc123.us-central1.run.app o https://api.example.com/v1/agents/support.
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 la risorsa Service e creato la risorsa Agent di sola lettura corrispondente:

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.

gcloud

Elenca gli agenti registrati nel tuo registry con il comando gcloud agent-registry agents list:

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 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'.

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 registry.
DISPLAY_NAME: il nome visualizzato dell'agente leggibile da una persona.

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.

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

Tipi di agenti e limitazioni

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 un agente remoto

Console

gcloud

Terraform

Verifica la registrazione

Console

gcloud

Terraform

Passaggi successivi

Utilizza la registrazione manuale per gli agenti