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 fonctionnalités de l'agent, d'une invite système bien structurée 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 une invite système robuste à l'aide d'un compilateur structuré
  • Ajouter des outils MCP Google Maps pour le 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 localement
  • Déployer l'agent sur Agent Engine (Cloud Run)

Ce dont vous avez besoin

  • Un navigateur Web (par exemple, Chrome)
  • Un projet Google Cloud avec facturation activée
  • Connaissances de base 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 du sélecteur de 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 pour un projet.

Démarrer Cloud Shell

Cloud Shell est un environnement de ligne de commande exécuté dans Google Cloud, qui est préchargé 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 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 Maps. L'application la lit à partir d'une variable d'environnement :
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

Configurer les variables d'environnement

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

  1. Copiez l'exemple de fichier d'environnement :
cp planner_agent/sample.env planner_agent/.env
  1. Ouvrez planner_agent/.env et mettez à jour le champ GOOGLE_CLOUD_PROJECT avec votre ID de projet Google Cloud réel, puis mettez à jour 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=us-west1
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 approprié avec des règles et une planification d'itinéraire.

5. Créer une invite système

Les invites système (instructions) 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 des instructions de manière dynamique.

Ouvrez planner_agent/prompts.py pour voir comment l'invite 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, elle est déjà importée.

Recherchez la section avec TODO: Replace Instruction and Description et annulez la mise en commentaire de la réaffectation 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 l'invite pour l'agent qui ne fait référence à aucun outil. Vous ajouterez des outils lors d'une étape ultérieure.

Vous pouvez tester cette version de l'agent :

uv run adk run planner_agent

Dans la fenêtre de chat, envoyez l'invite suivante :

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

Après 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 invite bien définie, le résultat est déjà beaucoup plus proche du résultat 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 liés aux compétences et aux 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 encapsule les instructions, les ressources et les outils nécessaires pour 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 d'exploitation 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 l'itinéraire du marathon.
  2. mapping : utilise les outils Google Maps pour rechercher des lieux et des informations météorologiques.
  3. race-director : valide que l'itinéraire du marathon respecte les consignes de planification.

Les compétences 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 effectué 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, qui est en ligne. Bien qu'elle ne soit pas utilisée dans cet atelier de programmation, elle 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 mappage

Le planificateur de marathon a besoin d'un contexte spatial pour générer des itinéraires. Pour cela, 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 localement

Maintenant que l'agent, l'invite et les outils sont connectés, exécutez l'agent localement. Cette fois, vous utiliserez adk web pour pouvoir afficher les événements de chargement des compétences et d'appel d'outils.

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 l'invite suivante :
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 de marathon.

L'interface utilisateur doit se présenter comme suit :

Interface utilisateur Web de l&#39;ADK

8. Déployer l'agent

Une fois que vous êtes satisfait des performances de l'agent localement, 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 \
  planner_agent

Une fois le déploiement terminé, la CLI 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 le bac à sable d'Agent Runtime 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 votre ID de projet Google Cloud réel.

Le fichier doit se présenter comme suit :

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
  1. Vous pouvez répertorier 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 disposez de l'ID d'agent déployé, vous pouvez envoyer une invite :

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 votre compte Google Cloud ne soit facturé en permanence, supprimez les ressources créées lors de cet atelier de programmation.

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 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 supprimer l'intégralité du projet 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 de planification de marathon sophistiqué à l'aide d'ADK.

Connaissances acquises

  • Initialisation d'un projet Agent Development Kit (ADK)
  • Utilisation de PromptBuilder pour les invites système modulaires
  • Intégration des fonctionnalités de mappage à l'aide des outils MCP et d'ApiRegistry
  • Chargement conditionnel des compétences à l'aide de SkillToolset
  • Tests locaux et déploiement sur Agent Engine

Documents de référence