Utilizzare la registrazione manuale

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

È necessaria la registrazione manuale in Agent Registry per gli agent ospitati all'esterno di Google Cloud. Questo documento mostra come registrare manualmente gli agent in Agent Registry.

Prima di iniziare

Prima di iniziare, configura Agent Registry. Per eseguire queste attività, devi disporre dell' ID progetto.

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per registrare manualmente gli agent 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 Agent.

4. Fai clic su Aggiungi agente.

5. Nel riquadro Dettagli agente , inserisci un nome visualizzato, una descrizione e seleziona la regione geografica.

6. Per il tipo di agente, seleziona A2A.

7. Nella sezione delle specifiche dell'agente, seleziona la scheda Incolla JSON e incolla l'intero contenuto del file agent-card.json.

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

Nota: le dimensioni del file delle specifiche dell'agente che carichi non devono superare i 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 del registro.
• DISPLAY_NAME: il nome leggibile che vuoi assegnare all'agente, ad esempio Support Agent.

Registra un agente REST standard

Gli agent 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 specifiche 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 Agent.

4. Fai clic su Aggiungi agente.

5. Nel riquadro Dettagli agente , inserisci un nome visualizzato, una descrizione e seleziona la regione geografica.

6. Per il tipo di agente, seleziona l'opzione che indica nessuna specifica, ad esempio Non A2A.

7. Inserisci l'endpoint in cui è ospitato l'agente e seleziona l'associazione del protocollo, se necessario, ad esempio HTTP_JSON.

8. 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 del servizio 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 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 Agent.

   La pagina deve mostrare un elenco di tutti gli agent registrati e i relativi dettagli.

gcloud

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

Se hai più agent o 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 del registro.
• FILTER_EXPRESSION: l'espressione di filtro per gli agent 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'.