Orchestration & Agents

Une **orchestration** coordonne raisonnement, outils, politiques, mémoire et LLM(s) pour accomplir une tâche de bout en bout, avec traçabilité et garde-fous.

Planner • ReAct • Plan&Execute Toolbox typée (JSON Schema) Policies & Guardrails Memory STM/LTM Telemetry, P95, coût

Rôle

Analyser l’intention utilisateur, **découper** en étapes/outils.
Produire un **plan exécutable** (liste d’actions avec inputs attendus).

Stratégies

ReAct : Reason → Act → Observe (boucle contrôlée).
Plan-and-Execute : un LLM planifie, un exécuteur suit le plan.
ToT/GoT : exploration en arbre/graph, votes/self-consistency.

Format plan (ex.)

{
 "goal": "Comparer 3 offres cloud pour RAG",
 "steps": [
  {"tool":"search_rag", "args":{"query":"Pinecone vs Milvus vs Weaviate"}},
  {"tool":"run_sql",   "args":{"sql":"SELECT price, sla FROM offers WHERE name IN (...)" }},
  {"tool":"py_exec",   "args":{"code":"analyser & synthétiser"}},
  {"tool":"send_email","args":{"to":"cto@ex.com","subject":"Comparatif","body":"..."}}
 ],
 "constraints": {"time_budget":"60s","max_steps":6}
}

Prompts utiles

Tu es un planificateur. Retourne un plan JSON strict :
- étapes atomiques
- outil à appeler + inputs typés
- hypothèses & contraintes (latence, coût)
- critères de succès

Déclaration typée (JSON Schema)

{
 "name": "run_sql",
 "description": "Exécute une requête SQL paramétrée",
 "input_schema": {
   "type":"object",
   "properties":{"sql":{"type":"string"}, "params":{"type":"array","items":{"type":"string"}}},
   "required":["sql"]
 },
 "output_schema":{"type":"object","properties":{"rows":{"type":"array"}}},
 "policies":{"pii":"deny","cost":"medium"}
}

Exemples d’outils : search_rag, run_sql, call_api, py_exec, shell_safe, send_email*.

Validation & sécurité

Validation Pydantic des inputs + **sanitizer** (SQL paramétré, URL allow-list).
Sandbox pour py_exec/shell_safe (quotas CPU, FS, net).
Déclarer coûts, latences, **scopes** et PII policy par outil.

Retour d’outil

{"ok": true, "data": {...}, "usage":{"latency_ms":120,"cost_usd":0.0012}}

Décisions du contrôleur

Ordonner les étapes, **appliquer guardrails** (pré/post), timeouts, quotas.
Gestion d’erreurs : retry/backoff, **circuit-breaker**, réponse partielle.

Policies (extraits)

- PII guard : si entrée contient PII → refuser ou masquer
- Allow-list API : {host: [...], methods: [...], rate_limit: ...}
- Tool budget : max_steps=6, time_budget=60s, cost_budget=$0.05

Anti-patterns

Pas de **stop criteria** (boucles infinies).
Appels d’outils sans validation d’inputs/outputs.
Absence d’explications (pas de trace thought→action→obs).

Short-term

Résumé du dialogue + derniers tours pertinents.
Aide à **éviter les boucles** (détection non-progress).

Long-term

Historique d’outils (inputs/outputs), préférences, secrets (vault).
Index vectoriel + graphe pour **rappel de faits** inter-sessions.

Schéma de trace mémoire

{"user_id":"u1","ts":"2025-09-09T10:00Z",
 "tool":"run_sql","args_hash":"...","result_hash":"...","summary":"...","cost":0.0012}

Utiliser TTL + purge + audit (qui/quoi/quand).

Routing de modèles

Petit modèle pour **planning** (coût/latence bas).
Grand modèle pour étapes **critiques** / reasoning / sécurité.

Paramètres de décodage

Plan : temperature=0, sortie JSON stricte.
Créatif : temp=0.7, top-p=0.9 (si résumé narratif).

Multi-LLM (ex.)

router(goal) -> {"model":"gpt-4o-mini"} or {"model":"mistral-large"}
executor(step) -> choose best (latency SLA, cost budget)

Traces

{"span":"agent.step","thought":"...","action":{"tool":"run_sql","args":{...}},
 "observation":{"rows":3},"latency_ms":180,"cost_usd":0.0018,"error":null}

Exporter vers OpenTelemetry / ELK / Prometheus.

KPIs

Task success, avg steps, tool precision.
Cost/answer, P95 latency, error rate.

Frameworks

LangChain, LlamaIndex, Haystack, Guidance, DSPy.
OpenAI Assistants / Function Calling, NeMo Guardrails.

Patterns

ReAct, MRKL (sélection d’experts/outils).
Plan-and-Execute, Router, Self-refine.
Toolformer / Function-calling JSON.

Quand utiliser quoi ?

Situation	Pattern recommandé
Problème séquentiel clair	Plan-and-Execute
Infos externes / API multiples	ReAct + MRKL
Qualité critique	Self-consistency / Self-refine
Coût/latence serrés	Router (petit modèle) + cache

Check-list intégration

Déclarer outils + schemas + policies.
Choisir un **controller** (états, retries, stop conditions).
Brancher telemetry, audit, **guardrails**.

KPIs

Task success rate (scénarios end-to-end).
Tool accuracy (SQL correct / résultat attendu).
Hallucination rate (réponse sans outils alors nécessaires).
Cost & Latency P95, robustesse (timeouts/erreurs API).

Tests automatiques

{
 "goal":"Top-3 articles RAG 2024",
 "expect":{
   "must_use":["search_rag"], "max_steps":6,
   "assert":["sources>=3","contains:'RAG'"]
 }
}

Diff-tests à chaque changement d’outil/prompt/LLM.

Logs → métriques

# simple aggregation pseudo
success = sum(1 for r in runs if r.status=="ok")/len(runs)
p95 = percentile([r.latency_ms for r in runs], 95)

# Style OpenAI Function Calling / LangChain
MAX_STEPS = 6
def agent(goal, tools, controller, memory):
    plan = planner_llm(goal, schema="json")
    ctx  = memory.short_tail() + memory.long_recall(goal)
    for i, step in enumerate(plan["steps"][:MAX_STEPS], start=1):
        controller.check_limits(step, i)
        tool = tools.get(step["tool"])
        args = controller.validate_inputs(tool, step["args"])
        controller.pre_guardrails(tool, args)
        obs  = tool.run(**args)            # call tool (typed)
        controller.post_guardrails(tool, obs)
        memory.log_tool(step, obs)
        ctx = controller.compress(ctx + [obs])
        if controller.success(goal, ctx): break
    return final_llm_answer(goal, ctx)

# Déclaration d'outil typée
@tool(name="search_rag", input_schema=SearchSchema, pii="deny")
def search_rag(query:str, k:int=8) -> dict: ...

Guardrails critiques

Stop si **non-progress** (répétitions de plan/outil).
Échec outil → retry/backoff limité + fallback.

Production

Observabilité complète + alerte temps réel.
Canary release & budgets par feature.

Orchestration & Agents

Planner (planificateur)

Toolbox (outils appelables)

Controller / Policy

Memory (optionnel)

LLM(s)

Telemetry & Logs

Écosystème & patterns

Stratégies clés

Évaluation

Exemple d’agent (pseudo-code)