Crea e distribuisci un agente con l'interfaccia a riga di comando dell'agente e l'identità dell'agente

Questa guida mostra come creare ed eseguire il deployment di un agente in Agent Runtime su Gemini Enterprise Agent Platform con Agent Identity abilitato.

Agent Identity assegna un'identità SPIFFE sicura all'agente di cui hai eseguito il deployment. L' agente utilizza questa identità per autenticarsi ai Google Cloud servizi e recuperare le credenziali dal gestore dell'autenticazione di Agent Identity.

Prima di iniziare

  1. Abilita le API Agent Identity, Agent Platform, Agent Registry e App Hub.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

  2. Assicurati di avere il ruolo Agent Platform User (roles/aiplatform.user) nel tuo progetto.

Crea ed esegui il deployment dell'agente

Crea un agente di esempio utilizzando google-agents-cli ed esegui il deployment con Agent Identity:

  1. Installa uv, quindi esegui la configurazione di google-agents-cli:

    pip install uv
uvx google-agents-cli setup

  2. Crea un progetto di agente utilizzando il modello di prototipo:

    uvx google-agents-cli create AGENT_PROJECT --prototype --yes

    Sostituisci AGENT_PROJECT con il nome della nuova directory del progetto dell'agente (ad esempio, maps-agent).

    Questo comando genera la seguente struttura della directory del progetto:

    AGENT_PROJECT/
├── app/                       # Core agent code
│   ├── agent.py               # Main agent logic
│   ├── fast_api_app.py        # Client application logic
│   └── app_utils/             # App utilities and helpers
├── tests/                     # Unit and integration tests
├── GEMINI.md                  # Development guide
└── pyproject.toml             # Project dependencies

  3. Rinomina la cartella dell'applicazione predefinita (app) in modo che corrisponda al nome dell'agente (AGENT_NAME, ad esempio maps_agent). I nomi degli agenti devono essere un identificatore Python valido: devono iniziare con una lettera e contenere solo lettere, numeri e trattini bassi.

    cd AGENT_PROJECT
mv app AGENT_NAME

  4. Aggiorna il file di configurazione agent.py in modo che rifletta il nuovo nome:

    # In AGENT_PROJECT/AGENT_NAME/agent.py
app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

  5. Scegli un modello da utilizzare in base alla sua disponibilità regionale. Aggiorna il valore di MODEL in agent.py in modo che corrisponda al modello scelto.

    Soluzione alternativa per i modelli disponibili solo nella global regione

    Per utilizzare un modello disponibile solo nella regione global devi modificare agent.py in modo che l'agente possa accedervi.

    1. Aggiungi le seguenti importazioni:

      from functools import cached_property
from google.genai import Client

    2. Aggiungi la seguente sottoclasse dopo le importazioni:

      class GlobalGemini(Gemini):
    @cached_property
    def api_client(self) -> Client:
        return Client(enterprise=True, location="global")

    3. Trova il seguente codice:

      root_agent = Agent(
    name="root_agent",
    model=Gemini(

      Modificalo in modo che faccia riferimento alla nuova sottoclasse:

      root_agent = Agent(
    name="root_agent",
    model=GlobalGemini(

  6. Abilita Agent Identity creando un file di configurazione:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  7. Crea un file requirements.txt per le dipendenze di deployment:

    uv export \
    --no-emit-workspace \
    --no-hashes \
    --format requirements.txt \
    --output-file AGENT_NAME/requirements.txt

  8. Verifica la struttura della directory del progetto:

    AGENT_PROJECT/
├── AGENT_NAME/                 # Agent application folder
│   ├── .agent_engine_config.json # Agent Identity configuration
│   ├── agent.py                  # Main agent logic
│   ├── fast_api_app.py           # Client application logic
│   ├── requirements.txt          # Deployment dependencies
│   └── app_utils/                # App helpers
├── tests/                        # Tests
├── GEMINI.md                     # Development guide
└── pyproject.toml                # Project dependencies

  9. Testa l'agente localmente:

    uv run adk web . --port 8501 --reload_agents

    Per convalidare l'agente:

    1. Vai a http://localhost:8501. In alternativa, se utilizzi Cloud Shell, fai clic sul link fornito dall'output del server web.

    2. Nell'interfaccia di chat, invia un prompt di test per verificare la risposta.

  10. Termina il server con CTRL+C.

  11. Esegui il deployment dell'agente in Google Cloud:

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo Google Cloud progetto ID.

    • LOCATION: la regione supportata in cui vuoi eseguire il deployment dell'agente (ad esempio, us-west1).

    Il completamento del deployment può richiedere alcuni minuti. Al termine, la CLI restituisce un messaggio di conferma e un link al playground dell'agente nella console. Google Cloud

  12. Recupera l'ID SPIFFE dell'agente (Agent Identity):

    1. Nella Google Cloud console vai alla pagina Deployment.

      Vai a Deployment

    2. Per copiare l'ID SPIFFE dell'agente negli appunti, individua la riga in cui si trova l'agente di cui hai eseguito il deployment e nella colonna Identità di quella riga fai clic su Copia negli appunti. L'identità è simile alla seguente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

Passaggi successivi