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 servizi Google Cloud e recuperare le credenziali dal gestore di autenticazione dell'identità dell'agente.

Prima di iniziare

  1. Abilita l'API Agent Identity.

    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.

    Abilitare l'API

  2. Assicurati di disporre del ruolo Vertex AI User (roles/aiplatform.user) nel tuo progetto.

Crea ed esegui il deployment dell'agente

Crea un agente di esempio utilizzando agents-cli ed esegui il deployment con l'identità dell'agente:

  1. Installa google-agents-cli e uv, poi esegui la configurazione:

    pip install google-agents-cli uv
agents-cli setup

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

    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:

    (Nota: la seguente struttura evidenzia i file di configurazione pertinenti e potrebbe non rappresentare tutti i file nella directory.)

    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):

    mv app AGENT_NAME

    Quindi, 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",
)

  4. Abilita l'identità dell'agente creando un file di configurazione:

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

  5. Crea un file requirements.txt per le dipendenze del deployment:

    echo "httpx" > requirements.txt
echo "google-auth" >> requirements.txt
echo "google-adk[agent_engines,agent-identity]" >> requirements.txt
echo "google-cloud-aiplatform[agent_engines,adk]>=1.153.1" >> requirements.txt

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

    Verifica l'agente a livello locale:

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

    Per convalidare l'agente:

    1. Vai a http://localhost:8501.
    2. Nell'interfaccia della chat, invia un prompt di test per verificare la risposta.

  7. 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 in cui vuoi eseguire il deployment dell'agente (ad esempio, us-west1).

    Al termine del deployment, la CLI restituisce un messaggio di conferma e un link al playground dell'agente nella console Google Cloud .

  8. Recupera l'ID SPIFFE (identità dell'agente) dell'agente dalla consoleGoogle Cloud :

    1. Nella console Google Cloud , vai alla pagina Agent Platform.
    2. Fai clic sulla scheda Deployment e seleziona l'agente di cui è stato eseguito il deployment.
    3. Copia il valore di Identità agente (ad esempio, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Passaggi successivi