Registrare un agente ADK personalizzato

Agent Registry ti consente di registrare gli agenti personalizzati che crei con l'Agent Development Kit (ADK) e di ospitarli sulla tua infrastruttura in modo che altri sviluppatori e agenti orchestratori possano scoprirli. Esponendo una scheda dell'agente conforme al protocollo Agent2Agent (A2A) e registrando manualmente l'endpoint dell'agente, rendi le sue skill A2A rilevabili in Agent Registry.

Prima di iniziare

  1. Configura Agent Registry.

  2. Recupera l'ID progetto per il progetto di governance in cui è abilitato Agent Registry.

  3. 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 agenti ADK personalizzati in Agent Registry, chiedi all'amministratore di concederti il ruolo IAM Agent Registry API Editor (roles/agentregistry.editor) nel progetto di governance in cui è abilitato Agent Registry. 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.

Endpoint della scheda Agente

Affinché Agent Registry possa indicizzare le funzionalità dell'agente personalizzato, l'agente deve esporre i propri metadati e le competenze A2A disponibili utilizzando il protocollo Agent2Agent (A2A).

La specifica A2A richiede agli agenti di fornire una scheda agente, ovvero un documento JSON che descrive l'identità e gli strumenti dell'agente, in un endpoint specifico, in genere /.well-known/agent-card.json.

Quando utilizzi i plug-in o i moduli del server A2A specifici dell'ADK per registrare l'agente, il framework può generare e pubblicare automaticamente questa scheda dell'agente in base alla definizione Agent e a tools che fornisci nel codice.

Registra l'agente esposto

Dopo aver eseguito il deployment dell'agente ADK nel tuo ambiente di hosting e aver pubblicato correttamente i relativi endpoint REST, chiedi ad Agent Registry di rilevarlo.

Poiché i deployment personalizzati richiedono la registrazione manuale, crei una risorsa Service nel registry. Salva la scheda dell'agente generata come file JSON locale, ad esempio agent-card.json.

Utilizza gcloud CLI per registrare l'agente con il comando gcloud agent-registry services create, assicurandoti di specificare il tipo di specifica a2a-agent-card e di caricare il file locale utilizzando il flag --agent-spec-content:

gcloud agent-registry services create AGENT_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --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 al tuo agente, ad esempio my-custom-agent.
  • PROJECT_ID: l'ID progetto
  • LOCATION: la località o la regione del registry.
  • DISPLAY_NAME: il nome leggibile del tuo agente.

Dopo la creazione della risorsa Service, Agent Registry analizza la scheda dell'agente, crea una risorsa Agent di sola lettura e indicizza le skill A2A definite nel codice Python dell'ADK in modo che altri sviluppatori possano cercarle.