Utilizzare la registrazione manuale

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

Prima di iniziare

Prima di iniziare, configura Agent Registry. Per eseguire queste attività, devi avere l'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 nel progetto:

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 utilizzando URL pubblici standard o autenticata tramite credenziali preconfigurate.

Registra un agente conforme ad A2A

Se l'agente remoto implementa la specifica Agent2Agent (A2A), indirizza Agent Registry al payload agent-card.json dell'agente. Il registro sincronizza automaticamente la scheda dell'agente e indicizza le competenze A2A disponibili dell'agente per la rilevabilità.

Per registrare l'agente:

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.

  4. Fai clic su Aggiungi agente.

  5. Nel riquadro Dettagli agente, inserisci i seguenti dettagli:

    • Tipo: seleziona A2A.
    • Regione: seleziona la posizione geografica in cui vuoi registrare l'agente.

  6. Scegli una delle seguenti opzioni:

    • Per registrare l'agente utilizzando il relativo URI risorsa, seleziona la scheda Da URI e inserisci un URL valido nel campo URI. Quindi, fai clic su Importa per recuperare 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.

  7. Fai clic su Salva.

gcloud

Per registrare un agente A2A, salva la scheda dell'agente come file JSON locale, ad esempio agent-card.json, e procedi come segue:

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: il nome che vuoi assegnare all'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, usa il valore global.
  • DISPLAY_NAME: il nome leggibile che vuoi assegnare all'agente, ad esempio Support Agent.

Terraform

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({
      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 all'agente, ad esempio my-support-agent.
  • DISPLAY_NAME: il nome leggibile che vuoi assegnare all'agente, ad esempio Support Agent.

Registra un agente REST standard

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

Se vuoi registrare un agente remoto che non implementa la specifica A2A, ad esempio un endpoint API REST o SaaS standard, l'API Agent Registry crea una risorsa Service senza alcuna specifica del protocollo dell'agente.

Per registrare l'agente:

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.

  4. Fai clic su Aggiungi agente.

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

  6. Fai clic su Salva.

gcloud

Facoltativamente, puoi fornire l'interfaccia dell'endpoint HTTP/JSON definita 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 assegnare all'agente, ad esempio my-remote-rest-agent.
  • PROJECT_ID: l'ID progetto.
  • REGION: la regione del registro.
  • 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.remote-service.com/v1/agents/1234.
  • PROTOCOL: il binding 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 all'agente, ad esempio my-remote-rest-agent.
  • 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.remote-service.com/v1/agents/1234.
  • PROTOCOL: il binding 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ù Google Cloud progetti e utilizza un Agent Gateway centrale per gestire 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 registro del progetto di governance centrale.

Considerazioni per la registrazione tra progetti

Prima di registrare gli agenti tra progetti, esamina quanto segue:

  • Località compatibili: l'istanza di Agent Registry, Agent Gateway e gli endpoint dell'agente devono risiedere 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 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à in uscita: la governance tra progetti con Agent Gateway è supportata solo per i gateway da agente a ovunque (in uscita). I gateway in entrata 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 da un altro progetto:

Console

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

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il progetto di governance centrale Google Cloud in cui vuoi registrare l'agente.

  3. Seleziona la scheda Agenti.

  4. Fai clic su Aggiungi agente.

  5. 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 gateway centrale e al deployment dell'agente remoto.

  6. 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 dell'endpoint dell'agente remoto.

  7. Fai clic su Salva.

gcloud

  • Agente A2A: per registrare un agente A2A da un altro progetto utilizzando la gcloud CLI, esegui il comando seguente 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 comando seguente 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: il binding 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: il binding 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 il Service e creato la risorsa Agent corrispondente:

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.

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, usa 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' identificatoreunivoco globale (URN), 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 registro.
  • DISPLAY_NAME: il nome visualizzato leggibile dell'agente.

Passaggi successivi