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 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 da Agent Identity Auth Manager.

Prima di iniziare

  1. Abilita l'API Agent Identity Connector.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilitare l'API

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

Creare e fare il deployment dell'agente

Crea un agente di esempio utilizzando agents-cli e fai il deployment con Agent Identity:

  1. Installa google-agents-cli e uv, quindi 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 della 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 Agent Identity creando un file di configurazione:

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

  5. Crea un file requirements.txt per le dipendenze di 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 in locale:

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

    Per convalidare l'agente:

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

  7. Fai 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 in cui vuoi fare 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 Google Cloud console.

  8. Recupera l'ID SPIFFE dell'agente (Agent Identity) dalla Google Cloud console:

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

Passaggi successivi