Keynote pour les développeurs Next 2026 : Créer des agents ADK avec des compétences et des outils

1. Introduction

Dans cet atelier de programmation, vous allez créer un agent de planification de marathon sophistiqué à l'aide de l'Agent Development Kit (ADK). Vous examinerez progressivement les capacités de l'agent, d'un prompt système bien structuré au chargement dynamique des compétences et au mappage des outils MCP. Enfin, vous testerez l'agent localement et le déploierez sur Agent Runtime (Agent Engine).

Objectifs de l'atelier

  • Initialiser un nouveau projet d'agent ADK
  • Composer un prompt système robuste à l'aide d'un compilateur structuré
  • Ajoutez les outils MCP Google Maps pour obtenir un contexte de localisation réel.
  • Charger dynamiquement des compétences dans l'ensemble d'outils de l'agent
  • Tester l'exécution de l'agent en local
  • Déployez l'agent sur Agent Engine (Cloud Run).

Prérequis

  • Un navigateur Web (par exemple, Chrome)
  • Un projet Google Cloud avec facturation activée
  • Connaître les bases de Python

Cet atelier de programmation s'adresse aux développeurs intermédiaires qui souhaitent créer des agents d'IA générative spécialisés.

Durée estimée : 45 minutes

Les ressources créées dans cet atelier de programmation devraient coûter moins de 2 $.

2. Avant de commencer

Créer un projet Google Cloud

  1. Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
  2. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

Démarrer Cloud Shell

Cloud Shell est un environnement de ligne de commande exécuté dans Google Cloud et fourni avec les outils nécessaires.

  1. Cliquez sur Activer Cloud Shell en haut de la console Google Cloud.
  2. Une fois connecté à Cloud Shell, vérifiez votre authentification :
    gcloud auth list
  3. Vérifiez que votre projet est configuré :
    gcloud config get project
  4. Si votre projet n'est pas défini comme prévu, définissez-le :
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Vérifiez l'authentification :

gcloud auth list

Confirmez votre projet :

gcloud config get project

Définissez-le si nécessaire :

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Activer les API

Exécutez cette commande pour activer toutes les API requises :

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  mapstools.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com

Créer une clé API Google Maps

Pour utiliser les outils MCP Google Maps, vous devez générer une clé API Google Maps.

  1. Dans la console Google Cloud, utilisez la barre de recherche pour accéder à Google Maps Platform > Identifiants.
  2. Si vous y êtes invité, confirmez votre projet Google Cloud.
  3. Cliquez sur Créer des identifiants et sélectionnez Clé API.
  4. Copiez la clé API générée. Vous en aurez besoin à l'étape suivante.

3. Configurer votre environnement

Pour cet atelier de programmation, le code est hébergé sur GitHub. Vous allez cloner le dépôt, qui contient la structure de répertoire et les sous-composants requis (tels que le répertoire skills/).

  1. Clonez le dépôt et accédez au dossier du projet :
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. Configurez un environnement virtuel Python et installez ADK :
uv venv
source .venv/bin/activate
uv sync
  1. Définissez votre clé API Google Maps. L'application le lit à partir d'une variable d'environnement :
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

Configurer les variables d'environnement

L'agent Simulator utilise un fichier .env pour la configuration. Copiez l'exemple de fichier et mettez-le à jour avec l'ID de votre projet.

  1. Copiez l'exemple de fichier d'environnement :
cp planner_agent/sample.env planner_agent/.env
  1. Ouvrez planner_agent/.env, puis mettez à jour le champ GOOGLE_CLOUD_PROJECT avec votre ID de projet Google Cloud et le champ GOOGLE_MAPS_API_KEY avec la clé API Google Maps que vous avez créée.

Le fichier doit se présenter comme suit :

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=global
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true

4. Créer un agent ADK

Explorez le fichier principal qui définit l'agent : planner_agent/agent.py.

Dans le dépôt build-agents-with-skills, l'agent est initialisé à l'aide de la classe Agent d'ADK. Il spécifie le modèle sous-jacent, un nom d'identité et extrait les instructions et les outils définis dans d'autres modules.

Ouvrez planner_agent/agent.py pour examiner le code d'initialisation :

instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]

# ...

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='planner_agent',
    description=description,
    instruction=instruction,
    tools=tools
)

La classe Agent abstrait l'historique des messages, l'orchestration des outils et la communication LLM, ce qui vous permet de vous concentrer sur le comportement de l'agent.

Pour le moment, l'agent est très générique. Vous pouvez interagir avec lui comme avec n'importe quel autre LLM.

uv run adk run planner_agent

Cette commande lance une discussion avec l'agent. Il utilise gemini-3-flash-preview comme modèle et peut répondre à des questions de base.

Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.

L'agent connaît déjà quelques faits sur les marathons. Toutefois, cela ne suffit pas pour planifier un marathon en bonne et due forme avec des règles et un itinéraire.

5. Créer un prompt système

Les instructions système (prompts) dictent le comportement de l'agent. Au lieu d'une seule chaîne géante, ce projet utilise un PromptBuilder (planner_agent/utils.py) pour composer les instructions de manière dynamique.

Ouvrez planner_agent/prompts.py pour voir comment la requête est structurée en sections logiques :

from collections import OrderedDict
from .utils import PromptBuilder

ROLE = """\
...
"""

RULES = """\
...
"""

WORKFLOW = """\
...
"""

###

# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        tools=TOOLS_PROMPT_ONLY,
        workflow=WORKFLOW_PROMPT_ONLY,
    )
).build()

# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        skills=SKILLS,
        tools=TOOLS,
        workflow=WORKFLOW,
    )
).build()

Dans planner_agent/agent.py, cet élément est déjà importé.

Recherchez la section avec TODO: Replace Instruction and Description et annulez la mise en commentaire de la réattribution des variables instruction et description.

Cette section de code doit se présenter comme suit :

instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."

Vous importez une version de la requête pour l'agent qui ne fait référence à aucun outil. Vous ajouterez des outils lors d'une prochaine étape.

Vous pouvez tester cette version de l'agent :

uv run adk run planner_agent

Dans la fenêtre de chat, envoyez le prompt suivant :

Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Au bout de quelques instants, vous devriez recevoir une réponse semblable à celle-ci :

Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.

As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.

### 1. Intent Alignment
*   **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
*   **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...

Avec une requête bien définie, le résultat est déjà beaucoup plus proche de celui attendu. À l'étape suivante, vous ajouterez des outils pour faire passer l'agent au niveau supérieur.

6. Ajouter des compétences et des outils

Pour activer les compétences et les outils dans planner_agent/agent.py, recherchez la section avec TODO: Replaces Tools et annulez la mise en commentaire des deux lignes suivantes. Le code doit ressembler à l'extrait suivant :

instruction=PLANNER_INSTRUCTION
tools=get_tools()

Il s'agit de la seule modification de code requise à cette étape. Le reste de cette section explique les concepts qui sous-tendent les compétences et les outils.

Compétences

Une compétence d'agent est une unité de fonctionnalité autonome qu'un agent ADK peut utiliser pour effectuer une tâche spécifique. Une compétence d'agent englobe les instructions, les ressources et les outils nécessaires à une tâche, en fonction de la spécification de la compétence d'agent. La structure d'une compétence lui permet d'être chargée de manière incrémentielle afin de minimiser l'impact sur la fenêtre de contexte opérationnel de l'agent.

Pour l'agent de planification de marathon, trois compétences sont définies :

  1. gis-spatial-engineering : responsable du traitement des données GeoJSON pour créer le parcours du marathon.
  2. Cartographie : utilisez les outils Google Maps pour rechercher des lieux et des informations météorologiques.
  3. race-director : valider que le parcours du marathon respecte les consignes de planification.

Les skills peuvent comporter des scripts, des éléments supplémentaires et des références.

L'application charge toutes les compétences et les fournit en tant qu'outils dans planner_agent/tools.py. Notez comment cela est fait dans la fonction get_tools() :

def get_tools() -> list:
    """Build the planner's tool list with lazy-loaded skills."""
    from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor

    skills_dir = pathlib.Path(__file__).parent / "skills"

    skills = []
    if skills_dir.exists():
        skills = [
            load_skill_from_dir(d)
            for d in sorted(skills_dir.iterdir())
            if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
        ]

    additional_tools = _load_additional_tools(skills_dir)

    skill_toolset = SkillToolset(
        skills=skills,
        code_executor=UnsafeLocalCodeExecutor(),
        additional_tools=additional_tools,
    )

    tools = [
        skill_toolset,
        PreloadMemoryTool(),
    ]

    tools.extend(get_maps_tools())

    return tools

La partie la plus intéressante est la méthode load_skill_from_dir d'ADK. Il existe une autre façon de créer des compétences dans ADK : en ligne. Bien qu'il ne soit pas utilisé dans cet atelier de programmation, il se présente comme suit :

from google.adk.skills import models

greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "A friendly greeting skill that can say hello to a specific person."
        ),
    ),
    instructions=(
        "Step 1: Read the 'references/hello_world.txt' file to understand how"
        " to greet the user. Step 2: Return a greeting based on the reference."
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "Hello! So glad to have you here!",
            "example.md": "This is an example reference.",
        },
    ),
)

Ajouter des outils de cartographie

Le planificateur de marathon a besoin d'un contexte spatial pour générer des itinéraires. Pour ce faire, vous devez intégrer le serveur MCP (Model Context Protocol) Google Maps.

Dans planner_agent/tools.py, notez comment le serveur MCP est enregistré avec l'outil ApiRegistry :

from google.adk.integrations.api_registry import ApiRegistry

class MapsApiRegistry(ApiRegistry):
    """ApiRegistry subclass that strips ADC headers to force API key auth."""

    def get_toolset(self, *args, **kwargs):  # noqa: ANN002, ANN003
        toolset = super().get_toolset(*args, **kwargs)
        conn = getattr(toolset, "_connection_params", None)
        headers = getattr(conn, "headers", None) if conn else None
        if headers:
            headers.pop("Authorization", None)  # type: ignore[union-attr]
            headers.pop("x-goog-user-project", None)  # type: ignore[union-attr]
        return toolset

def get_maps_tools() -> list:
    """Return Maps MCP toolset if configured."""
    project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
    maps_key = _resolve_maps_key()

    if not project_id or not maps_key:
        return []

    # Map the MCP server location on Google Cloud
    mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
    
    # Initialize the custom API registry that supports header injection
    api_registry = MapsApiRegistry(
        api_registry_project_id=project_id,
        header_provider=header_provider,
    )
    return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]

En ajoutant l'ensemble d'outils MCP, l'agent peut automatiquement interroger Google Maps pour obtenir des informations sur les itinéraires, l'altitude et la localisation.

7. Exécuter l'agent en local

Maintenant que l'agent, le prompt et les outils sont connectés, exécutez l'agent localement. Cette fois, vous utiliserez adk web pour pouvoir voir les événements Skill Load et Tool Call.

uv run adk web

Vous devriez voir quelque chose de semblable.

INFO:     Started server process [99665]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  1. Ouvrez votre navigateur et accédez à l'URL affichée dans le terminal (généralement http://localhost:8000).
  2. Dans le menu déroulant en haut à gauche, sélectionnez planner_agent.
  3. Dans la fenêtre de chat, envoyez le prompt suivant :
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Vous devriez voir les compétences se charger et les outils être appelés. Après quelques instants, l'agent génère un plan d'entraînement pour le marathon.

Votre UI doit ressembler à ceci :

Interface utilisateur Web de l&#39;ADK

8. Déployer l'agent

Une fois que vous êtes satisfait des performances de l'agent en local, vous pouvez le déployer sur Agent Engine, qui l'héberge de manière sécurisée sur Cloud Run.

Pour déployer l'agent, utilisez la commande de déploiement de la CLI ADK :

uv run adk deploy agent_engine \
  --env_file planner_agent/.env --region=us-central1 \
  planner_agent

Une fois le déploiement terminé, l'interface de ligne de commande génère un point de terminaison hébergé de manière sécurisée pour votre agent. Vous pouvez désormais intégrer ce point de terminaison dans des applications frontend, des chatbots ou d'autres systèmes backend. Vous pouvez également utiliser l'Agent Runtime Playground pour tester l'agent.

La sortie ressemble à ceci :

Files and dependencies resolved
Deploying to agent engine...
✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>

Vous pouvez utiliser le script Python fourni pour communiquer avec l'agent.

  1. Copiez l'exemple de fichier d'environnement :
cp sample.env .env
  1. Ouvrez .env et mettez à jour le champ GOOGLE_CLOUD_PROJECT avec l'ID de votre projet Google Cloud.

Le fichier doit se présenter comme illustré ci-dessous.

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-central1
  1. Vous pouvez lister les agents de votre projet.
python main.py list

Vous devriez voir quelque chose de semblable.

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

Une fois que vous avez l'ID de l'agent déployé, vous pouvez envoyer une requête :

export AGENT_ID=<AGENT_ID>

python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"

Vous obtiendrez un résultat semblable à celui-ci :

Streaming response from agent <AGENT_ID>:

{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...

9. Effectuer un nettoyage

Pour éviter que les ressources créées lors de cet atelier de programmation ne soient facturées en permanence sur votre compte Google Cloud, supprimez-les.

Supprimez le service Cloud Run créé par le déploiement :

python main.py delete --agent-id ${AGENT_ID}

Si vous avez stocké la clé API Google Maps dans Secret Manager, supprimez le secret :

gcloud secrets delete maps-api-key --project=$PROJECT_ID

Si vous avez créé un projet Google Cloud pour cet atelier de programmation, vous pouvez le supprimer entièrement pour supprimer toutes les ressources et API qui y sont associées :

gcloud projects delete $PROJECT_ID

10. Félicitations

Félicitations ! Vous avez créé un agent sophistiqué de planification de marathon à l'aide d'ADK.

Connaissances acquises

  • Initialiser un projet Agent Development Kit (ADK)
  • Utiliser PromptBuilder pour les invites système modulaires
  • Intégrer des fonctionnalités de cartographie à l'aide des outils MCP et de ApiRegistry
  • Chargement conditionnel des compétences à l'aide de SkillToolset
  • Tester en local et déployer sur Agent Engine

Documents de référence