Vibe Coding AI Agents : gérer le cycle de vie des agents avec Agents CLI et ADK 2.0

1. Présentation

Dans cet atelier de programmation, vous allez apprendre à utiliser Agents CLI pour régir l'ensemble du cycle de vie du développement local d'un agent d'IA. Que vous encapsuliez des modèles Gemini existants ou que vous créiez des agents personnalisés de A à Z avec l'Agent Development Kit (ADK 2.0), Agents CLI fournit les outils nécessaires pour échafauder, créer, analyser et tester vos agents en local.

Points abordés

  • Comment installer et configurer agents-cli et ses skills associés.
  • Découvrez comment créer un projet d'agent.
  • Structure et fichiers clés d'un projet d'agent de workflow de graphique ADK 2.0.
  • Comment exécuter des vérifications linting et des nettoyages de code automatisés.
  • Découvrez comment lancer et utiliser l'atelier Web local pour effectuer des tests interactifs avec rechargement automatique.

Ce dont vous avez besoin

  • Python 3.11 ou version ultérieure
  • Gestionnaire de packages uv
  • Node.js 18 ou version ultérieure (si vous utilisez des compétences d'agent de codage)
  • IDE Antigravity (installer et configurer à partir de Google Antigravity)

Prérequis

Cet atelier de programmation suppose que vous êtes à l'aise avec les éléments suivants :

  • En utilisant un terminal et une ligne de commande.

Aucune expérience préalable avec les agents d'IA ou ADK 2.0 n'est requise.

2. Configurer l'authentification et l'environnement

Fournissez vos identifiants d'authentification pour que l'agent puisse appeler les modèles Gemini.

Option 1 : Clé API Gemini (Google AI Studio)

Si vous utilisez une clé API Gemini standard (que vous pouvez obtenir depuis Google AI Studio), exportez-la dans la session de terminal de votre IDE :

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

Option 2 : Identifiants par défaut de l'application Google Cloud

Si vous utilisez Vertex AI sur Google Cloud, authentifiez-vous avec les identifiants par défaut de l'application (ADC) Google Cloud et définissez votre projet Google Cloud actif :

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. Configurer Agents CLI et les compétences

La première étape consiste à installer l'outil agents-cli. Cet outil gère le gros du travail de gestion des projets d'agents.

Une fois Antigravity installé, exécutez la commande de configuration directement dans votre terminal.

👉 Ouvrez un terminal et exécutez :

uvx google-agents-cli setup

Cette commande installe automatiquement les éléments suivants :

  1. L'outil Agents CLI au niveau global sur votre système.
  2. Sept compétences d'assistant de codage spécifiques à un domaine qu'Antigravity peut utiliser pour vous aider à créer, échafauder, évaluer et déployer des agents. Ces compétences sont installées une seule fois au niveau mondial dans ~/.agents/skills/ et sont automatiquement détectées par Antigravity.

Remarque : Les compétences sont installées dans ~/.agents/skills/ et sont automatiquement détectées par Antigravity. Vous pouvez le vérifier à l'aide de la commande /skills ou de vos paramètres Antigravity.

Résultat attendu (tronqué) :

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. Créer votre projet d'agent

Dans cette section, vous allez créer un répertoire de projet entièrement structuré à l'aide du modèle de prototype.

👉 Requête Antigravity :

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

Antigravity exécute automatiquement la commande d'échafaudage (agents-cli scaffold create customer-support-agent --prototype --yes) et configure les fichiers du projet pour vous.

5. Explorer le code de l'agent

👉 Demandez à Antigravity d'expliquer le code généré :

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

Dans l'IDE Antigravity, les fichiers et artefacts de projet nouvellement créés s'affichent directement dans le volet auxiliaire (à gauche). Vous pouvez y afficher app/agent.py ou l'ouvrir à partir de l'explorateur de fichiers de l'IDE pour explorer le code généré.

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

Concepts clés

  • Workflow et edges : dans ADK 2.0, les applications d'agent sont orchestrées sous forme de graphique à l'aide de Workflow. La liste edges définit le flux d'exécution, en enchaînant les nœuds à partir de START et en permettant le branchement conditionnel en fonction des routes (par exemple, le routage vers faq_agent sur "shipping" ou handle_unrelated sur "unrelated").
  • LlmAgent : nœuds déclaratifs qui définissent des tâches basées sur des LLM avec des instructions, des modèles et des sorties structurées spécifiques (output_schema).
  • Nœuds et contexte : fonctions Python décorées avec @node (ou fonctions standards) qui effectuent une logique, accèdent à l'état d'exécution via Context et génèrent des objets Event pour transmettre des données et des signaux de routage le long du graphique.
  • Modèle : "gemini-3.1-flash-lite" est utilisé comme modèle de raisonnement rapide par défaut.
  • Wrapper d'application : l'objet App de premier niveau encapsule le workflow racine. Les outils externes tels que le bac à sable local, les harnais d'évaluation ADK et Agent Runtime découvrent et exécutent votre workflow via cette interface app standardisée.

6. Linting automatisé

Avant d'exécuter ou de tester votre agent, il est recommandé de vous assurer que votre code est propre et correctement formaté.

👉 Requête Antigravity :

Run linting on my agent project to verify its health.

Antigravity exécutera agents-cli lint en coulisses pour effectuer des vérifications préconfigurées, en vérifiant les importations, la syntaxe et la cohérence de la mise en forme dans vos fichiers.

7. Tests interactifs avec le bac à sable

L'atelier Web local est le moyen le plus rapide de vérifier le comportement de votre agent. Il fournit une interface de chat interactive qui vous permet de discuter avec votre agent et d'inspecter les exécutions d'outils en temps réel.

👉 Requête Antigravity :

Launch the local development playground for my agent.

Antigravity démarre le serveur de développement local (agents-cli playground). Ouvrez l'URL fournie (généralement http://127.0.0.1:8080/dev-ui/?app=app) dans votre navigateur Web, puis sélectionnez le dossier app dans le menu déroulant pour commencer à discuter avec votre agent.

Commencez à discuter avec votre agent dans l'interface Web. Essayez de poser une question sur la livraison :

How much is standard shipping?

Notez que le workflow catégorise et transfère correctement la question à faq_agent pour y répondre. Essayez également de poser une question sans rapport pour vérifier que le workflow la transfère à handle_unrelated et refuse correctement d'y répondre :

What is the weather like?

Tester la recharge automatique en temps réel

Vous pouvez voir comment les modifications en temps réel apportées à votre agent sont reflétées dans le terrain de jeu.

  1. Modifiez l'instruction faq_agent dans app/agent.py en demandant à Antigravity : 
    Modify the faq_agent instruction in app/agent.py to make the shipping rates
response more playful and enthusiastic. Add some emojis and highlight the
free shipping threshold.
  2. Envoyez un nouveau message à l'agent dans l'atelier pour tester le rechargement automatique : 
    How much is standard shipping?
    Le bac à sable se recharge automatiquement et exécute votre code mis à jour en temps réel, sans avoir besoin de redémarrer le serveur. Vous devriez maintenant voir des emojis dans la réponse.

8. Exécution de ligne de commande

Pour les tests rapides, l'automatisation ou les scripts, vous pouvez demander à Antigravity d'exécuter votre agent directement depuis le terminal.

👉 Requête Antigravity :

Run a CLI query asking my agent how long standard delivery takes.

Antigravity exécutera la commande de requête (agents-cli run "How long does standard delivery take?"). Cela exécutera une inférence rapide en un seul tour et affichera la réponse finale de l'agent ainsi que les détails d'exécution de l'outil.

9. Nettoyage

Pour éviter de laisser des ressources indésirables dans votre environnement local, suivez ces étapes de nettoyage :

  1. Arrêtez les serveurs locaux : si votre serveur agents-cli playground est toujours en cours d'exécution, arrêtez-le dans votre terminal en appuyant sur Ctrl + C.
  2. Supprimer les fichiers de projet locaux : supprimez le répertoire du projet d'agent échafaudé de votre machine locale.
rm -rf customer-support-agent

10. Récapitulatif et étapes suivantes

Félicitations ! Vous avez réussi à gérer le cycle de vie complet du développement local d'un agent d'IA à l'aide de la CLI Agents et d'ADK 2.0.

Ce que vous avez appris

  • Configurez vos outils : installez la CLI Agents et configurez les compétences de workflow spécifiques au domaine pour Antigravity.
  • Projet structuré : vous avez créé un projet customer-support-agent entièrement structuré à l'aide de modèles standardisés.
  • Structure ADK 2.0 analysée : exploration des workflows graphiques, des agents LLM, des nœuds, des arêtes et du routage conditionnel.
  • Managed Local Health : exécution de vérifications automatisées de la qualité du code à l'aide de agents-cli lint.
  • Comportement validé : l'agent a été testé de manière interactive avec le rechargement à chaud en temps réel via le terrain de jeu, et des tests rapides ont été exécutés sur la ligne de commande.

Et maintenant ?

Maintenant que vous maîtrisez la boucle de développement local, voici comment étendre et mettre en production votre agent :

  • Évaluation : évaluez votre agent par rapport à un ensemble d'évaluation à l'aide de agents-cli eval run pour mesurer la précision et trouver les régressions.
  • Enterprise Cloud Scale : déploiement et observabilité : packagez et déployez votre agent dans des environnements de production tels qu'Agent Runtime ou Cloud Run à l'aide de agents-cli deploy. Configurez la télémétrie de production pour diffuser des journaux et des traces d'exécution vers Cloud Trace et BigQuery.

Autres ressources