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 l'API Agent Identity Connector.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (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 Agent Identity :

  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 pertinents 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 Agent Identity 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

    Vérifiez 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 invite 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 : votre Google Cloud projet ID.
    • LOCATION: la région dans laquelle vous souhaitez déployer l'agent (par exemple, us-west1).

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

  8. Récupérez l'ID SPIFFE de votre agent (Agent Identity) depuis la Google Cloud console :

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

Étape suivante