Créer et déployer un agent avec l'interface de ligne de commande Agent et l'identité de l'agent

Ce guide vous explique comment créer et déployer un agent dans Agent Runtime sur Gemini Enterprise Agent Platform avec l'identité de l'agent activée.

Agent Identity attribue une identité SPIFFE sécurisée à votre agent déployé. L'agent utilise cette identité pour s'authentifier auprès des services Google Cloud et récupérer les identifiants du gestionnaire d'authentification de l'identité de l'agent.

Avant de commencer

  1. Activez l'API Agent Identity.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

    Activer l'API

  2. Assurez-vous de disposer du rôle Utilisateur Vertex AI (roles/aiplatform.user) sur votre projet.

Créer et déployer l'agent

Créez un exemple d'agent à l'aide de agents-cli et déployez-le avec l'identité de l'agent :

  1. Installez google-agents-cli et uv, puis exécutez la configuration :

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

  2. Créez un projet d'agent à l'aide du modèle de prototype :

    agents-cli create AGENT_PROJECT --prototype --yes

    Remplacez AGENT_PROJECT par le nom du répertoire de votre nouveau projet d'agent (par exemple, maps-agent).

    Cette commande génère la structure de répertoire de projet suivante :

    (Remarque : L'arborescence suivante met en évidence les fichiers de configuration concernés et peut ne pas représenter tous les fichiers de votre répertoire.)

    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. Renommez le dossier d'application par défaut (app) pour qu'il corresponde au nom de votre agent (AGENT_NAME, par exemple maps_agent) :

    mv app AGENT_NAME

    Ensuite, mettez à jour votre fichier de configuration agent.py pour refléter le nouveau nom :

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

  4. Activez l'identité de l'agent en créant un fichier de configuration :

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

  5. Créez un fichier requirements.txt pour les dépendances de déploiement :

    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. Vérifiez la structure du répertoire du projet :

    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

    Validez votre agent localement :

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

    Pour valider votre agent, procédez comme suit :

    1. Accédez à http://localhost:8501.
    2. Dans l'interface de chat, envoyez une requête de test pour vérifier la réponse.

  7. Déployez votre agent sur Google Cloud :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • LOCATION : région dans laquelle vous souhaitez déployer l'agent (par exemple, us-west1).

    Une fois le déploiement terminé, la CLI affiche un message de confirmation et un lien vers l'espace de jeu de votre agent dans la console Google Cloud .

  8. Récupérez l'ID SPIFFE (identité de l'agent) de votre agent depuis la consoleGoogle Cloud  :

    1. Dans la console Google Cloud , accédez à la page Plate-forme d'agent.
    2. Cliquez sur l'onglet Déploiements, puis sélectionnez l'agent déployé.
    3. Copiez la valeur Agent Identity (Identité de l'agent), par exemple principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

Étapes suivantes