Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Utilizzare la registrazione manuale

È necessaria la registrazione manuale nel registro degli agenti per gli agenti ospitati al di fuori diGoogle Cloud o in esecuzione su runtime non supportati. Questo documento mostra come registrare manualmente gli agenti in Agent Registry.

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 il ruolo IAM Editor API Agent Registry (roles/agentregistry.editor) sul 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.

Registra un agente conforme ad A2A

Se il tuo agente remoto implementa la specifica Agent2Agent (A2A), registra direttamente l'agente nel payload agent-card.json dell'agente. Il registro sincronizza automaticamente la scheda dell'agente e indicizza le competenze disponibili dell'agente per la scoperta.

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 località geografica in cui vuoi registrare l'agente.
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 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

Per registrare un agente A2A, salva la scheda dell'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 di specifica è 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

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 rilevabili per nome e descrizione, ma non hanno skill 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 specifica del protocollo dell'agente.

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 il tuo 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 località geografica in cui vuoi registrare l'agente.
- Endpoint: inserisci l'endpoint in cui è ospitato l'agente.
Fai clic su Salva.

gcloud

Se vuoi, 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 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.

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 deve mostrare 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 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

Verifica la registrazione

Console

gcloud

Terraform

Passaggi successivi

Utilizzare la registrazione manuale