Agents & orchestration

Une réclamation pour retard tranchée sur pièces

Un transporteur routier reçoit une réclamation pour une livraison en retard. Répondre demande de croiser le suivi d'expédition, le contrat de transport et le barème de pénalités, dans trois outils qui ne se parlent pas. Ce cas est inventé.

Cas inventéCe cas n'est pas une mission. Il est inventé de bout en bout, et le code plus bas est le vrai code qui le ferait tourner.

1. Humain·La réclamation arrive

   Le service litiges écrit : le client de l'expédition EXP-48231 réclame. Il dit avoir été livré en fin de journée alors que le contrat promet midi. Est-ce que la pénalité de retard lui est due, et que lui répond-on ?

2. L'agent·Le choix de l'outil

   Trois serveurs MCP sont branchés : le suivi d'expédition, la gestion des contrats, la facturation. Je pars du suivi, parce que la pénalité se calcule sur les horodatages du terrain, pas sur une facture. J'écarte la facturation : elle porte le montant transporté, elle ne dit rien du créneau promis ni de ce qui s'est passé au quai.

   L'outil écarté l'est pour une raison lisible, pas parce qu'il n'a pas été trouvé.

3. Appel d'outil·Appel du suivi

   {
     "jsonrpc": "2.0",
     "id": 7,
     "method": "tools/call",
     "params": {
       "name": "lire_suivi_expedition",
       "arguments": {
         "reference": "EXP-48231"
       }
     }
   }

4. Retour de l'outil·Réponse du serveur

   {
     "jsonrpc": "2.0",
     "id": 7,
     "result": {
       "content": [
         {
           "type": "text",
           "text": "{\"reference\": \"EXP-48231\", \"client\": \"CL-7742\", \"creneau_contractuel\": \"2026-08-25T12:00:00+02:00\", \"evenements\": [{\"horodatage\": \"2026-08-24T06:12:00+02:00\", \"code\": \"ENLEVEMENT\", \"site\": \"quai-nord\", \"motif\": null}, {\"horodatage\": \"2026-08-25T11:48:00+02:00\", \"code\": \"PRESENTATION\", \"site\": \"site-client\", \"motif\": \"quai indisponible\"}, {\"horodatage\": \"2026-08-25T19:41:00+02:00\", \"code\": \"LIVRAISON\", \"site\": \"site-client\", \"motif\": null}]}"
         }
       ],
       "structuredContent": {
         "reference": "EXP-48231",
         "client": "CL-7742",
         "creneau_contractuel": "2026-08-25T12:00:00+02:00",
         "evenements": [
           {
             "horodatage": "2026-08-24T06:12:00+02:00",
             "code": "ENLEVEMENT",
             "site": "quai-nord",
             "motif": null
           },
           {
             "horodatage": "2026-08-25T11:48:00+02:00",
             "code": "PRESENTATION",
             "site": "site-client",
             "motif": "quai indisponible"
           },
           {
             "horodatage": "2026-08-25T19:41:00+02:00",
             "code": "LIVRAISON",
             "site": "site-client",
             "motif": null
           }
         ]
       },
       "isError": false
     }
   }

   Le jeton de l'appelant doit porter la portée de lecture sur les expéditions. Sans elle, la même requête renvoie une erreur, pas un dossier.

5. L'agent·Le croisement, puis l'arrêt

   Deux lectures suivent sur le même canal : le contrat de transport, puis le barème de pénalités. Le contrat fixe le créneau à midi. Le suivi montre une première présentation à 11 h 48, refusée parce que le quai du client était indisponible. La pénalité de l'article 8 ne se déclenche donc pas : le retard n'est pas imputable au transporteur. Un geste commercial reste possible, et c'est là que je m'arrête. Aucun outil d'écriture ne m'est exposé : je rédige la proposition, je ne l'accorde pas.

   L'agent ne peut pas passer un avoir, même en se trompant : le serveur n'expose que des lectures.

6. Réponse rendue·Ce qui revient

   Réponse rendue au service litiges. La pénalité n'est pas due : la première présentation est dans le créneau contractuel, le refus vient du quai réceptionnaire. Sources citées, dans l'ordre : suivi EXP-48231, contrat de transport, article 8 du barème. Proposition soumise à validation humaine : un geste commercial sur la prochaine expédition, à accorder ou à refuser par le service. Rien n'est écrit dans la facturation tant que personne n'a tranché.

from dataclasses import asdict, dataclass

from fastmcp import FastMCP
from fastmcp.exceptions import ToolError
from fastmcp.server.dependencies import get_access_token

mcp = FastMCP("litiges-transport")

PORTEE_PAR_DOMAINE = {"expeditions": "litiges:expeditions:lecture"}


@dataclass(frozen=True)
class Evenement:
    horodatage: str
    code: str
    site: str
    motif: str | None = None


DOSSIERS = {
    "EXP-48231": {
        "client": "CL-7742",
        "domaine": "expeditions",
        "creneau_contractuel": "2026-08-25T12:00:00+02:00",
        "evenements": [
            Evenement("2026-08-24T06:12:00+02:00", "ENLEVEMENT", "quai-nord"),
            Evenement("2026-08-25T11:48:00+02:00", "PRESENTATION", "site-client", "quai indisponible"),
            Evenement("2026-08-25T19:41:00+02:00", "LIVRAISON", "site-client"),
        ],
    }
}


@mcp.tool()
def lire_suivi_expedition(reference: str) -> dict:
    """Renvoie les événements de suivi d'une expédition, en lecture seule."""
    dossier = DOSSIERS.get(reference)
    if dossier is None:
        raise ToolError(f"référence inconnue : {reference}")
    jeton = get_access_token()
    # Un jeton absent vaut refus : sinon la garde tombe et le dossier sort de son service.
    if jeton is None or PORTEE_PAR_DOMAINE[dossier["domaine"]] not in set(jeton.scopes):
        raise ToolError(f"lecture refusée sur le dossier {reference}")
    return {
        "reference": reference,
        "client": dossier["client"],
        "creneau_contractuel": dossier["creneau_contractuel"],
        "evenements": [asdict(e) for e in dossier["evenements"]],
    }


# Aucun outil d'écriture n'est exposé : un geste commercial reste une décision humaine.
if __name__ == "__main__":
    mcp.run(transport="http")

Je ne donne pas à un agent le droit d'écrire dans un outil de gestion : ici il lit trois systèmes, il propose un geste commercial, et il s'arrête parce qu'aucun outil ne lui permet de l'accorder.