Créer et déployer un agent avec la CLI d'agent et Agent Identity

Agent Identity vous permet de provisionner une identité gérée pour les agents que vous créez et déployez dans Agent Runtime sur Gemini Enterprise Agent Platform à l'aide d'Agent CLI et d'Agent Development Kit (ADK). Votre agent déployé peut ensuite s'authentifier auprès des servicesGoogle Cloud et récupérer les identifiants à partir du gestionnaire d'authentification Agent Identity sans gestion manuelle des identifiants.

Avant de commencer

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

    Rôles requis pour activer les API

    Pour activer des API, vous devez disposer 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 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 l'identité de l'agent :

  1. Installez uv, puis exécutez la configuration de 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 nouveau 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 que vous avez choisi.

    Solution de contournement pour les modèles qui ne sont disponibles que 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 de 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. 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 un prompt de test pour vérifier la réponse.

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

  11. Déployez votre agent dans 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, la CLI affiche un message de confirmation et un lien vers le playground 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