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 Agent Identity activé.

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

Avant de commencer

  1. Activez les API Agent Identity, Agent Platform, Agent Registry et App Hub.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

    Activer les API

  2. Assurez-vous de disposer du rôle Utilisateur d'Agent Platform (roles/aiplatform.user) dans 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 nouveau répertoire de projet d'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 pour les modèles disponibles uniquement dans la global région

    Pour utiliser un modèle disponible uniquement 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 référencer la nouvelle sous-classe :

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

  6. Activez Agent Identity 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 localement :

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

    Pour valider votre agent, procédez comme suit :

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

    2. Dans l'interface de chat, envoyez un prompt 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 : votre Google Cloud projet ID.

    • LOCATION : la région compatible dans laquelle vous souhaitez déployer l'agent (par exemple, us-west1).

    Le déploiement peut prendre quelques minutes. Une fois terminé, l' interface CLI affiche un message de confirmation et un lien vers le bac à sable de votre agent dans la Google Cloud console.

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

    1. Dans la Google Cloud console, 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 cliquez sur Copier dans le presse-papiers dans la colonne Identité de cette ligne. L'identité ressemble à ce qui suit : principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

Étape suivante