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

Agent Identity ti consente di eseguire il provisioning di un'identità gestita per gli agenti che crei e di cui esegui il deployment in Agent Runtime su Gemini Enterprise Agent Platform utilizzando Agents CLI e Agent Development Kit (ADK). L'agente di cui è stato eseguito il deployment può quindi autenticarsi ai serviziGoogle Cloud e recuperare le credenziali dalgestore di autenticazione di Agent Identitysenza gestione manuale delle credenziali.

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 hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (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 eseguine 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 template del 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à per regione. 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 del tuo agente su Google Cloud:

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto Google Cloud .

    • LOCATION: La regione supportata in cui si desidera distribuire l'agente (ad esempio, us-west1).

    Il deployment può richiedere alcuni minuti. Al termine, l'interfaccia a riga di comando 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 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 è stato eseguito il deployment e, nella colonna Identità della 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