Agents Google ADK : d’un seul agent Gemini aux déploiements sur Cloud Run

Les grands modèles de langage ont changé la façon dont les gens utilisent les logiciels, mais l’étape suivante concerne moins des conversations plus intelligentes et plus des systèmes capables de raisonner, d’appeler des outils, de travailler ensemble et d’exécuter des flux de travail complets de leur propre chef. C’est le domaine de l’IA agente. Alors qu’une application classique envoie une requête et attend une seule réponse, un agent décide de ce qu’il faut faire ensuite : il peut appeler une API, récupérer des informations, confier une sous-tâche à un spécialiste ou retourner un résultat structuré.

Le Google Agent Development Kit (ADK) est un cadre pratique pour apprendre cela. Il vous permet de créer des agents à partir des modèles Gemini, d’exposer des fonctions Python en tant qu’outils, d’orchestrer plusieurs agents et de les déployer sur Google Cloud. Les sections suivantes abordent le sujet, en partant d’un agent unique jusqu’au déploiement dans le cloud.

Des requêtes aux agents

Les applications traditionnelles de modèles de langage sont basées sur un principe de demande-réponse : vous posez une question, le modèle répond, et c’est tout. Dans une configuration agente, le modèle fait partie d’un système d’exécution plus vaste. Il peut avoir des objectifs, choisir des outils, interagir avec des API et collaborer avec d’autres agents. L’idée clé est qu’un agent est bien plus qu’une simple demande : c’est un composant logiciel piloté par un modèle de langage.

Une application ADK est centrée autour d’un root_agent. La version la plus simple se présente comme suit :

from google.adk.agents import Agent

root_agent = Agent(
    name="assistant",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant"
)

Même celui-ci est un agent fonctionnel doté d’un nom, d’un comportement, d’un modèle et de la capacité d’exécuter des tâches. Il peut discuter, mais il ne peut toucher à rien en dehors de lui-même tant qu’il n’a pas de outils.

Outils

Ce qui définit l’IA agente, c’est l’utilisation d’outils. Sans outils, un modèle ne produit que du texte, tandis qu’avec eux, un agent peut appliquer une véritable logique. Dans ADK, une simple fonction Python devient un outil dès qu’elle est intégrée à la configuration de l’agent. Un agent calculateur montre comment cela fonctionne :

from google.adk.agents import Agent


def calculator(a: float, b: float, operation: str) -> float:
    if operation == "add":
        return a + b

    if operation == "subtract":
        return a - b

    if operation == "multiply":
        return a * b

    if operation == "divide":
        if b == 0:
            raise Exception("Cannot divide by zero")

        return a / b

    raise Exception("Unsupported operation")


root_agent = Agent(
    name="assistant",
    model="gemini-2.5-flash",
    instruction=(
        "You are a helpful assistant with calculator capabilities. "
        "Use the calculator tool for arithmetic. "
        "Supported operations are add, subtract, multiply, divide."
    ),
    tools=[calculator]
)

Ici, le modèle comprend la demande, mais au lieu d’effectuer lui-même les calculs, il confie la computation exacte à la fonction. Le LLM s’occupe du raisonnement tandis que l’outil s’occupe de l’exécution. Cette séparation est au fondement de conceptions d’entreprise solides.

Les systèmes réels reposent rarement sur un seul outil. Un assistant peut appeler des API, convertir des données, interroger une base de données, récupérer des documents, vérifier des politiques et résumer les résultats. Un agent multi-outils combine des fonctions de calcul, de conversion de unités et de recherche météorologique :

from google.adk.agents import Agent


def calculator(a: float, b: float, operation: str) -> float:
    if operation == "add":
        return a + b

    if operation == "subtract":
        return a - b

    if operation == "multiply":
        return a * b

    if operation == "divide":
        if b == 0:
            raise ValueError("Cannot divide by zero.")

        return a / b

    raise ValueError("Unsupported operation.")


def convert_units(value: float, from_unit: str, to_unit: str) -> float:
    from_unit = from_unit.lower()
    to_unit = to_unit.lower()

    if from_unit == "km" and to_unit == "miles":
        return value * 0.621371

    if from_unit == "miles" and to_unit == "km":
        return value / 0.621371

    if from_unit == "celsius" and to_unit == "fahrenheit":
        return value * 9 / 5 + 32

    if from_unit == "fahrenheit" and to_unit == "celsius":
        return (value - 32) * 5 / 9

    raise ValueError("Unsupported unit conversion.")


def get_weather_mock(city: str) -> dict:
    weather_data = {
        "bucharest": {
            "temperature_celsius": 23,
            "condition": "sunny",
            "wind_speed_kmh": 10,
        },
        "london": {
            "temperature_celsius": 16,
            "condition": "rain",
            "wind_speed_kmh": 18,
        },
    }

    key = city.lower()

    if key not in weather_data:
        return {
            "city": city,
            "error": "Weather data not available."
        }

    return {
        "city": city,
        **weather_data[key],
    }


root_agent = Agent(
    name="multi_tool_agent",
    model="gemini-2.5-flash",
    instruction=(
        "You are a practical assistant. "
        "Use the available tools when the user asks for calculations, "
        "unit conversions, or weather information."
    ),
    tools=[
        calculator,
        convert_units,
        get_weather_mock,
    ],
)

L’agent agit désormais en tant qu’orchestrateur. Il sélectionne des outils en temps réel en fonction de la demande, et l’utilisateur n’a jamais besoin de préciser lequel utiliser.

Agents en tant qu’outils pour d’autres agents

ADK permet à un agent de servir d’outil pour un autre, ce qui favorise la spécialisation. Au lieu d’un seul prompt géant tentant de couvrir tout, on crée des agents plus petits ayant des tâches spécifiques. Un planificateur de voyages composé de plusieurs agents illustre bien ce principe :

from google.adk.agents import LlmAgent
from google.adk.tools import google_search
from google.adk.tools import google_maps_grounding
from google.adk.tools.agent_tool import AgentTool


routing_agent = LlmAgent(
    name="routing_agent",
    model="gemini-2.5-pro",
    instruction="""
    You are a routing agent.
    Use google_maps_grounding to estimate routes and travel times.
    """,
    tools=[google_maps_grounding],
)


discovery_agent = LlmAgent(
    name="discovery_agent",
    model="gemini-2.5-pro",
    instruction="""
    You are a travel discovery agent.
    Use Google Search to find interesting places.
    """,
    tools=[google_search]
)


composer_agent = LlmAgent(
    name="composer_agent",
    model="gemini-2.5-pro",
    instruction="""
    Write a friendly travel itinerary based on the collected information.
    """,
    tools=[]
)


root_agent = LlmAgent(
    name="travel_agent",
    model="gemini-2.5-pro",
    instruction="""
    You are a travel assistant.
    Coordinate discovery, routing, and itinerary composition.
    """,
    tools=[
        AgentTool(discovery_agent),
        AgentTool(routing_agent),
        AgentTool(composer_agent)
    ]
)

L’agent principal fonctionne comme un orchestrateur sans processus de travail fixe, et chaque sous-agent est un spécialiste qui peut être sollicité dans n’importe quel ordre. Un tel système est plus simple à entretenir, à échaler et à comprendre, ce qui correspond à l’orientation prise par de nombreux projets d’IA d’entreprise.

Flux structurés

Tous les processus ne doivent pas être entièrement autonomes, car les systèmes d’entreprise ont souvent besoin de structure. Une forme courante est la planification, suivie de l’exécution, puis de la génération de rapports. ADK le gère grâce à des agents séquentiels, comme dans cette chaîne de planificateur, d’exécutant et de rapporteur :

from google.adk.agents import Agent, SequentialAgent
from google.adk.tools import AgentTool


planner_agent = Agent(
    name="planner_agent",
    model="gemini-2.5-flash",
    instruction="""
    Read the user request and create a short execution plan.
    """
)


executor_agent = Agent(
    name="executor_agent",
    model="gemini-2.5-flash",
    instruction="""
    Execute the plan and delegate specialist work.
    """,
    tools=[]
)


report_agent = Agent(
    name="report_agent",
    model="gemini-2.5-flash",
    instruction="""
    Produce the final report based on execution results.
    """
)


root_agent = SequentialAgent(
    name="planner_executor_report_workflow",
    sub_agents=[
        planner_agent,
        executor_agent,
        report_agent,
    ],
)

Développement local

Le cycle local d’ADK est rapide. Tout d’abord, un fichier .env définit le projet Google Cloud, la localisation ainsi que l’utilisation de Vertex AI :

GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=True

Ensuite, une commande lance une interface web locale permettant d’essayer les agents de manière interactive :

adk web

Ce cycle rapide convient bien à l’expérimentation.

Déploiement sur Cloud Run

Les tests locaux ont leurs limites, et Cloud Run constitue l’une des voies les plus simples pour le déploiement en production. Pour le premier agent mentionné, un Dockerfile court suffit :

FROM python:3.11-slim

WORKDIR /app

COPY . .

RUN pip install --no-cache-dir -r requirements.txt

CMD ["adk", "web", "--host", "0.0.0.0", "--port", "8080"]

Déployer depuis la source avec gcloud :

gcloud run deploy simple-agent \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE \
  --set-env-vars GOOGLE_CLOUD_PROJECT=PROJECT_ID \
  --set-env-vars GOOGLE_CLOUD_LOCATION=us-central1

Ensuite, recherchez l’URL du service :

gcloud run services describe simple-agent \
  --region us-central1 \
  --format='value(status.url)'

En ouvrant cette URL, l’interface ADK est affichée directement depuis Cloud Run. Le résultat est un service d’IA pouvant être déployé, et non un simple outil de démonstration.

Exposer une API avec FastAPI

Parfois, une API HTTP convient mieux qu’une interface en navigateur, et ADK fonctionne bien avec FastAPI. Un main.py minimal contenant l’agent météo ressemble à ceci :

import uuid

from fastapi import FastAPI
from pydantic import BaseModel

from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

from agent import root_agent


app = FastAPI()

session_service = InMemorySessionService()

runner = Runner(
    agent=root_agent,
    app_name="weather_agent_service",
    session_service=session_service,
)


class QueryRequest(BaseModel):
    message: str


@app.post("/weather")
async def weather(request: QueryRequest):

    user_id = "api_user"
    session_id = str(uuid.uuid4())

    await session_service.create_session(
        app_name="weather_agent_service",
        user_id=user_id,
        session_id=session_id,
    )

    content = types.Content(
        role="user",
        parts=[
            types.Part(text=request.message)
        ],
    )

    final_answer = ""

    async for event in runner.run_async(
        user_id=user_id,
        session_id=session_id,
        new_message=content,
    ):
        if event.is_final_response():
            final_answer = event.content.parts[0].text

    return {
        "response": final_answer
    }

Le déploiement nécessite un Dockerfile légèrement différent :

FROM python:3.11-slim

WORKDIR /app

COPY . .

RUN pip install --no-cache-dir -r requirements.txt

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

Agent Engine

ADK peut également être déployé sur l’Agent Engine de Google, un environnement d’exécution géré conçu pour l’exécution d’agents d’entreprise. Commencez par activer les API nécessaires :

gcloud services enable \
  aiplatform.googleapis.com \
  storage.googleapis.com

Ensuite, créez un bucket de staging :

export STAGING_BUCKET="gs://${PROJECT_ID}-agent-staging"

gsutil mb -l us-central1 $STAGING_BUCKET

Ensuite, déployez l’agent :

adk deploy agent_engine \
--project=$PROJECT_ID \
--region=us-central1 \
--staging_bucket=$STAGING_BUCKET \
basic_agent

Cela crée une ressource d’engine de raisonnement géré dans Google Cloud, et le processus est simple compte tenu de tout ce qui se passe en arrière-plan.

Pourquoi c’est important

L’IA agente représente une manière différente de développer des logiciels autour de modèles de langage, et non simplement des prompts améliorés. Les agents raisonnent, utilisent des outils, coordonnent des workflows et interagissent avec des systèmes externes au lieu de produire des réponses isolées.

ADK constitue un excellent outil d’apprentissage, car il introduit progressivement ces concepts. On commence avec un seul agent Gemini, on ajoute des outils, on connecte plusieurs agents, puis on en vient à des workflows d’entreprise intégrant RAG, des intégrations MCP, des pipelines d’évaluation et un déploiement sur GCP. Les mêmes principes s’appliquent, que ce soit à l’exemple de la calculatrice ou à une configuration d’entreprise multi-agents : raisonnement, délégation, orchestration et exécution. Le logiciel évolue de la simple réponse à des questions vers son utilisation au sein d’applications réelles.