Utilizzare la registrazione manuale

È necessaria la registrazione manuale in Agent Registry per gli agenti ospitati all'esterno Google 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 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 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 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 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 nel seguente modo:

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

Registra un agente REST standard

Gli agenti REST standard sono rilevabili per nome e descrizione, ma non hanno competenze 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 alpha 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.

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 deve mostrare un elenco di tutti gli agenti registrati e i relativi dettagli.

gcloud 

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

Passaggi successivi