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 des identités d'agent.

Avant de commencer

  1. Activez les API Agent Identity, Agent Platform, Agent Registry et App Hub, si certaines ne sont pas déjà activées.

    Rôles requis pour activer les API

    Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer les API

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

Créer et déployer l'agent

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

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

    pip install uv
uvx google-agents-cli setup

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

    uvx google-agents-cli create AGENT_PROJECT --prototype --yes

    Remplacez AGENT_PROJECT par le nom du répertoire de votre nouvel agent (par exemple, maps-agent).

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

    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). Les noms d'agent doivent être des identifiants Python valides : ils doivent commencer par une lettre et ne contenir que des lettres, des chiffres et des traits de soulignement.

    cd AGENT_PROJECT
mv app AGENT_NAME

  4. 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",
)

  5. Choisissez un modèle à utiliser en fonction de sa disponibilité régionale. Mettez à jour la valeur de MODEL dans agent.py pour qu'elle corresponde au modèle choisi.

    Solution de contournement pour les modèles disponibles uniquement dans la région global

    Pour utiliser un modèle qui n'est disponible que dans la région global, vous devez modifier agent.py afin que votre agent puisse y accéder.

    1. Ajoutez les importations suivantes :

      from functools import cached_property
from google.genai import Client

    2. Ajoutez la sous-classe suivante après les importations :

      class GlobalGemini(Gemini):
    @cached_property
    def api_client(self) -> Client:
        return Client(enterprise=True, location="global")

    3. Recherchez le code suivant :

      root_agent = Agent(
    name="root_agent",
    model=Gemini(

      Modifiez-le pour qu'il fasse référence à la nouvelle sous-classe :

      root_agent = Agent(
    name="root_agent",
    model=GlobalGemini(

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

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

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

    uv export \
    --no-emit-workspace \
    --no-hashes \
    --format requirements.txt \
    --output-file AGENT_NAME/requirements.txt

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

  9. Testez votre agent en local :

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

    Pour valider votre agent, procédez comme suit :

    1. Accédez à http://localhost:8501. Si vous utilisez Cloud Shell, vous pouvez également cliquer sur le lien fourni par la sortie du serveur Web.

    2. Dans l'interface de chat, envoyez une requête de test pour vérifier la réponse.

  10. Arrêtez le serveur avec CTRL+C.

  11. 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 prise en charge dans laquelle vous souhaitez déployer l'agent (par exemple, us-west1).

    Le déploiement peut prendre quelques minutes. Une fois l'opération terminée, l'CLI affiche un message de confirmation et un lien vers le terrain de jeu de votre agent dans la console Google Cloud .

  12. Récupérez l'ID SPIFFE de votre agent (identité de l'agent) :

    1. Dans la console Google Cloud , accédez à la page Déploiements.

      Accéder à la page "Déploiements"

    2. Pour copier l'ID SPIFFE de votre agent dans le presse-papiers, recherchez la ligne dans laquelle se trouve votre agent déployé, puis dans la colonne Identité de cette ligne, cliquez sur Copier dans le presse-papiers. L'identité ressemble à ceci : principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

Étapes suivantes