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

Questa guida mostra come creare e fare il deployment di un agente in Agent Runtime su Gemini Enterprise Agent Platform con l'identità dell'agente abilitata.

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

Prima di iniziare

  1. Abilita le API Agent Identity, Agent Platform, Agent Registry e App Hub, se non sono già abilitate.

    Ruoli richiesti per abilitare le API

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

    Abilita le API

  2. Assicurati di disporre del 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 l'identità dell'agente:

  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 di 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 regione global

    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. Attiva l'identità dell'agente 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 del 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 della 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 ID progetto Google Cloud .

    • 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 (identità dell'agente):

    1. Nella console Google Cloud 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 fai clic su Copia negli appunti nella colonna Identità di quella riga. 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