Évaluer des agents de l'Agents SDK dans un workflow

Si le système que vous évaluez est un agent construit avec l'Agents SDK, passez-le en tant qu'AgentSystem, comme dans le guide du SDK d'évaluation. La tâche exécute l'agent en tant que ctx.agent, et l'exécution enregistre quel agent a été évalué, afin que Studio puisse l'afficher.

La seule différence avec le SDK : un Agent est un objet Python, et il ne peut pas franchir Temporal. Le workflow envoie uniquement son nom et ses overrides, et l'activité de la tâche reconstruit ctx.agent à partir de votre code. Vous déclarez donc un agent issu du code sur la tâche qui l'exécute.

Vous avez besoin du plugin d'évaluation de workflow et de l'Agents SDK, mistralai-agents 1.1.0 ou version ultérieure, dans l'environnement du worker :

pip install -U mistralai-agents

pip install -U mistralai-agents

Un worker sans clé API (un déploiement géré) accède à l'API d'agents avec son token de compte de service. Cela nécessite également mistralai-agents 1.1.0 ou version ultérieure.

Déclarez l'agent sur la tâche avec @evaluation.task(agents=[...]), puis passez-le dans l'AgentSystem de evaluation.run() :

from mistralai import agents
from mistralai.workflows import workflow
from mistralai.workflows.plugins.evaluations import AgentSystem, evaluation
from mistralai.workflows.plugins.evaluations.types import Evaluation, Project, TaskContext


@agents.tool
async def lookup_order(order_id: str) -> dict[str, str]:
    """Get the status of an order."""
    return {"order_id": order_id, "status": "shipped on Monday"}  # read from your database


support_bot = agents.Agent(
    name="support-bot",
    model="mistral-small-latest",
    instructions="You are the support agent of Shopi.",
    tools=[lookup_order],
)


@evaluation.task(agents=[support_bot])
async def answer(ctx: TaskContext) -> str:
    result = await ctx.agent.run(ctx.input_record["question"])
    return result.text or ""


@workflow.define(name="support-bot-eval")
class SupportBotEval:
    @workflow.entrypoint
    async def run(self) -> None:
        await evaluation.run(
            system=AgentSystem(agent=support_bot, overrides={"model": "mistral-medium-latest"}),
            task=answer,
            dataset=dataset,
            evaluators=evaluators,
            project=Project(name="Support"),
            evaluation=Evaluation(name="Support bot"),
        )

from mistralai import agents
from mistralai.workflows import workflow
from mistralai.workflows.plugins.evaluations import AgentSystem, evaluation
from mistralai.workflows.plugins.evaluations.types import Evaluation, Project, TaskContext


@agents.tool
async def lookup_order(order_id: str) -> dict[str, str]:
    """Get the status of an order."""
    return {"order_id": order_id, "status": "shipped on Monday"}  # read from your database


support_bot = agents.Agent(
    name="support-bot",
    model="mistral-small-latest",
    instructions="You are the support agent of Shopi.",
    tools=[lookup_order],
)


@evaluation.task(agents=[support_bot])
async def answer(ctx: TaskContext) -> str:
    result = await ctx.agent.run(ctx.input_record["question"])
    return result.text or ""


@workflow.define(name="support-bot-eval")
class SupportBotEval:
    @workflow.entrypoint
    async def run(self) -> None:
        await evaluation.run(
            system=AgentSystem(agent=support_bot, overrides={"model": "mistral-medium-latest"}),
            task=answer,
            dataset=dataset,
            evaluators=evaluators,
            project=Project(name="Support"),
            evaluation=Evaluation(name="Support bot"),
        )

dataset et evaluators sont ceux que vous construisez pour toute exécution : voir le guide de démarrage du plugin.

ctx.agent est l'agent avec les overrides de l'exécution. Il s'exécute dans l'activité de la tâche, sur le worker, avec ses outils et hooks réels. overrides, params et ce qui peut être surchargé fonctionnent comme dans le guide du SDK.

ctx.agent.run() accepte les mêmes paramètres que Agent.run() et renvoie le tour Completed. Un tour qui ne se termine pas lève AgentTurnError : son enregistrement échoue donc et n'est pas noté. Voir Tours qui ne se terminent pas.

Dans un workflow défini avec on_behalf_of=True, seul un agent déployé est pris en charge : il est recherché et exécuté en tant que l'utilisateur exécutant. evaluation.run() et evaluation.optimize() refusent un agent issu du code dans ce cas, car ses appels au modèle, ses connecteurs et ses serveurs MCP utiliseraient les identifiants du worker, et non ceux de l'utilisateur. Voir Workflows on-behalf-of.

Une tâche peut exécuter plusieurs agents. Déclarez-les tous, et l'AgentSystem de chaque exécution en choisit un. Leurs noms doivent être différents, car le worker retrouve l'agent par son nom.

@evaluation.task(agents=[support_bot, support_bot_v2])
async def answer(ctx: TaskContext) -> str: ...


for agent in (support_bot, support_bot_v2):
    await evaluation.run(system=AgentSystem(agent=agent), task=answer, ...)

@evaluation.task(agents=[support_bot, support_bot_v2])
async def answer(ctx: TaskContext) -> str: ...


for agent in (support_bot, support_bot_v2):
    await evaluation.run(system=AgentSystem(agent=agent), task=answer, ...)

Les variantes d'un même agent (un autre modèle, d'autres instructions) ne nécessitent aucune nouvelle déclaration : ce sont des overrides.

Passez le nom ou l'identifiant d'un agent déployé. Aucune déclaration n'est nécessaire : l'activité de la tâche charge le déploiement depuis l'API d'agents du serveur sur lequel le workflow évalue, avec les identifiants de l'évaluation. Il s'agit de la clé API du worker ou de son token de compte de service, ou encore de l'identité de l'utilisateur exécutant dans un workflow on_behalf_of.

@evaluation.task
async def answer(ctx: TaskContext) -> str:
    result = await ctx.agent.run(ctx.input_record["question"])
    return result.text or ""


await evaluation.run(
    system=AgentSystem(agent="support-bot", overrides={"additional_instructions": "Answer in French."}),
    task=answer,
    ...
)

@evaluation.task
async def answer(ctx: TaskContext) -> str:
    result = await ctx.agent.run(ctx.input_record["question"])
    return result.text or ""


await evaluation.run(
    system=AgentSystem(agent="support-bot", overrides={"additional_instructions": "Answer in French."}),
    task=answer,
    ...
)

L'Agents SDK doit être installé sur le worker, et l'exécution doit être enregistrée dans Studio (et non local=True). Pour savoir ce que vous pouvez surcharger sur un agent déployé, voir le guide du SDK.

evaluation.optimize() accepte également un AgentSystem. Enveloppez dans Tunable les overrides à explorer. Chaque candidat correspond à une exécution de l'agent avec les valeurs du candidat. Voir Optimisation.

from mistralai.workflows.plugins.evaluations import GEPA
from mistralai.workflows.plugins.evaluations.types import Tunable

result = await evaluation.optimize(
    system=AgentSystem(agent=support_bot, overrides={"instructions": Tunable(support_bot.instructions)}),
    task=answer,
    dataset=dataset,
    evaluators=evaluators,
    algo=GEPA(),
)

from mistralai.workflows.plugins.evaluations import GEPA
from mistralai.workflows.plugins.evaluations.types import Tunable

result = await evaluation.optimize(
    system=AgentSystem(agent=support_bot, overrides={"instructions": Tunable(support_bot.instructions)}),
    task=answer,
    dataset=dataset,
    evaluators=evaluators,
    algo=GEPA(),
)

L'exécution est refusée avant sa création lorsque sa tâche ne peut pas exécuter l'agent. La tâche doit être :

• une tâche @evaluation.task, et non un workflow, car ctx.agent.run() effectue des entrées-sorties, ce qu'un workflow ne peut pas faire ;
• async, avec un seul argument ctx: TaskContext (annoté) ;
• pour un agent issu du code, déclarée avec @evaluation.task(agents=[...]).

• Évaluer des agents de l'Agents SDK : le guide du SDK, avec les overrides, params et ce qu'une exécution enregistre.
• Modes de tâche : les types de tâche que evaluation.run() accepte.
• Optimisation : exécuter l'optimiseur en tant que workflow.