Les architectures d’agents IA, expliquées simplement

import { StateGraph, StateSchema, ReducedValue, START, END } from "@langchain/langgraph";
import { ChatAnthropic } from "@langchain/anthropic";
import type { AIMessage } from "@langchain/core/messages";
import { z } from "zod";

const TIERS = ["small", "medium", "large"] as const;
type Tier = (typeof TIERS)[number];

const models: Record<Tier, ChatAnthropic> = {
  small: new ChatAnthropic({ model: "claude-haiku-5-5" }),
  medium: new ChatAnthropic({ model: "claude-sonnet-5-5" }),
  large: new ChatAnthropic({ model: "claude-opus-5-5" }),
};
// $ par million de tokens, à renseigner depuis la grille tarifaire en vigueur
declare const PRICING: Record<Tier, { input: number; output: number }>;
declare function estimateUsd(tier: Tier, task: string): number;

type CostLine = { step: string; tier: Tier; inTok: number; outTok: number; usd: number };
const costLine = (step: string, tier: Tier, raw: AIMessage): CostLine => {
  const u = raw.usage_metadata ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
  const p = PRICING[tier];
  const usd = (u.input_tokens * p.input + u.output_tokens * p.output) / 1e6;
  return { step, tier, inTok: u.input_tokens, outTok: u.output_tokens, usd };
};

const State = new StateSchema({
  task: z.string(),
  budgetUsd: z.number(),
  tier: z.enum(TIERS).default("small"),
  answer: z.string().default(""),
  confidence: z.number().default(0),
  // Journal du coût par décision : chaque appel ajoute sa ligne.
  ledger: new ReducedValue(z.array(z.custom<CostLine>()).default(() => []), {
    reducer: (all, added) => all.concat(added),
  }),
});
type S = typeof State.State;
const spent = (s: S) => s.ledger.reduce((t, l) => t + l.usd, 0);

// Routage par complexité : le plus petit modèle fait le tri.
async function triage(s: S) {
  const { raw, parsed } = await models.small
    .withStructuredOutput(z.object({ complexity: z.enum(["simple", "moderate", "hard"]) }), { method: "jsonSchema", includeRaw: true })
    .invoke(`Évalue la complexité de cette tâche : ${s.task}`);
  const tier = ({ simple: "small", moderate: "medium", hard: "large" } as const)[parsed.complexity];
  return { tier, ledger: [costLine("triage", "small", raw as AIMessage)] };
}

async function solve(s: S) {
  const { raw, parsed } = await models[s.tier]
    .withStructuredOutput(z.object({ answer: z.string(), confidence: z.number().min(0).max(1) }), { method: "jsonSchema", includeRaw: true })
    .invoke(s.task);
  return { ...parsed, ledger: [costLine("solve", s.tier, raw as AIMessage)] };
}

const escalate = (s: S) => ({ tier: TIERS[TIERS.indexOf(s.tier) + 1] });

// Sortie anticipée sur confiance, escalade tant que le budget le permet.
function next(s: S) {
  if (s.confidence >= 0.85) return END;
  const up = TIERS[TIERS.indexOf(s.tier) + 1];
  if (!up) return END;
  if (spent(s) + estimateUsd(up, s.task) > s.budgetUsd) return END;
  return "escalate";
}

export const graph = new StateGraph(State)
  .addNode("triage", triage)
  .addNode("solve", solve)
  .addNode("escalate", escalate)
  .addEdge(START, "triage")
  .addEdge("triage", "solve")
  .addConditionalEdges("solve", next, ["escalate", END])
  .addEdge("escalate", "solve")
  .compile();

// Le ledger part dans votre base : c'est lui qui dit ce que le routage fait gagner.
// const out = await graph.invoke({ task, budgetUsd: 0.05 });
// await analytics.insert(out.ledger.map((l) => ({ ...l, taskId })));

import { StateGraph, StateSchema, ReducedValue, Send, START, END } from "@langchain/langgraph";
import type { StructuredToolInterface } from "@langchain/core/tools";
import { z } from "zod";
import { llm } from "./models";

type Capability = "crm.read" | "crm.write" | "billing.read" | "email.send";

// Catalogue : chaque outil déclare les capacités qu'il exige.
declare const catalog: { tool: StructuredToolInterface; requires: Capability[] }[];

// Permission scoping : seuls les outils couverts par les scopes de l'appelant.
const allowedFor = (scopes: Capability[]) =>
  catalog.filter((e) => e.requires.every((c) => scopes.includes(c))).map((e) => e.tool);

const Step = z.object({
  tool: z.string(),
  args: z.record(z.string(), z.unknown()),
  reason: z.string(),
});
type Step = z.infer<typeof Step>;
type ToolResult = { tool: string; ok: boolean; output: string };

const State = new StateSchema({
  task: z.string(),
  scopes: z.array(z.custom<Capability>()),
  plan: z.array(Step).default(() => []),
  // Les résultats parallèles s'accumulent : sans reducer, le dernier écraserait les autres.
  results: new ReducedValue(z.array(z.custom<ToolResult>()).default(() => []), {
    reducer: (all, added) => all.concat(added),
  }),
  final: z.string().default(""),
});
type S = typeof State.State;

// Capability-based routing : le planner ne voit que les outils autorisés.
async function planner(s: S) {
  const allowed = allowedFor(s.scopes);
  const catalog = allowed.map((t) => `- ${t.name} : ${t.description}`).join("\n");
  const { steps } = await llm.withStructuredOutput(z.object({ steps: z.array(Step) }), { method: "jsonSchema" }).invoke(
    `Outils disponibles :\n${catalog}\n\nTâche : ${s.task}\n` +
      "Liste les appels indépendants nécessaires (ils seront exécutés en parallèle).",
  );
  // Défense en profondeur : on refiltre, le modèle peut inventer un outil.
  const names = new Set(allowed.map((t) => t.name));
  return { plan: steps.filter((st) => names.has(st.tool)) };
}

// Exécution parallèle : un Send par étape, tous dans le même super-step.
const fanOut = (s: S) =>
  s.plan.length ? s.plan.map((step) => new Send("execute", { step })) : "resolve";

async function execute({ step }: { step: Step }) {
  const t = catalog.find((e) => e.tool.name === step.tool)!.tool;
  try {
    const output = await t.invoke(step.args);
    return { results: [{ tool: step.tool, ok: true, output: String(output) }] };
  } catch (e) {
    return { results: [{ tool: step.tool, ok: false, output: (e as Error).message }] };
  }
}

// Conflict resolution : une règle de priorité explicite entre sources de vérité.
async function resolve(s: S) {
  const res = await llm.invoke(
    `Tâche : ${s.task}\nRésultats d'outils :\n${JSON.stringify(s.results, null, 2)}\n\n` +
      "Si deux sources se contredisent, la facturation fait foi sur le CRM. Signale explicitement chaque écart.",
  );
  return { final: res.text };
}

export const graph = new StateGraph(State)
  .addNode("planner", planner)
  .addNode("execute", execute)
  .addNode("resolve", resolve)
  .addEdge(START, "planner")
  .addConditionalEdges("planner", fanOut, ["execute", "resolve"])
  .addEdge("execute", "resolve")
  .addEdge("resolve", END)
  .compile();

// await graph.invoke({ task: "Résume le compte ACME", scopes: ["crm.read", "billing.read"] });

import { StateGraph, StateSchema, MessagesValue, START, END, GraphRecursionError } from "@langchain/langgraph";
import { ToolNode, toolsCondition } from "@langchain/langgraph/prebuilt";
import { tool } from "@langchain/core/tools";
import { AIMessage, HumanMessage, SystemMessage } from "@langchain/core/messages";
import { z } from "zod";
import { llm, fast } from "./models";

declare function searchInternalDocs(query: string): Promise<string>;

const searchDocs = tool(({ query }) => searchInternalDocs(query), {
  name: "search_docs",
  description: "Recherche dans la doc interne",
  schema: z.object({ query: z.string() }),
});
const tools = [searchDocs];
const model = llm.bindTools(tools);
// L'historique contient des tool_use : l'API Anthropic exige que les outils restent déclarés.
// tool_choice "none" les déclare sans permettre de les appeler.
const critic = fast.bindTools(tools, { tool_choice: "none" });
const finalizer = llm.bindTools(tools, { tool_choice: "none" });

const MAX_ITERATIONS = 8;
const REFLECT_EVERY = 3;

const State = new StateSchema({
  messages: MessagesValue,
  iterations: z.number().default(0),
});
type S = typeof State.State;

// Reason + Act : le modèle raisonne puis appelle (ou non) un outil.
async function agent(s: S) {
  const res = await model.invoke([
    new SystemMessage("Raisonne étape par étape, utilise les outils si nécessaire, puis réponds."),
    ...s.messages,
  ]);
  return { messages: [res], iterations: s.iterations + 1 };
}

// Reflect : auto-critique périodique pour casser les boucles improductives.
async function reflect(s: S) {
  const critique = await critic.invoke([
    ...s.messages,
    new HumanMessage("En 2 phrases : progresses-tu vers la réponse ou tournes-tu en rond ? Que changer ?"),
  ]);
  return { messages: [new HumanMessage(`[auto-critique] ${critique.text}`)] };
}

// Graceful degradation : une réponse partielle plutôt qu'une erreur.
async function degrade(s: S) {
  const res = await finalizer.invoke([
    ...s.messages,
    new HumanMessage("Limite d'itérations atteinte. Donne la meilleure réponse partielle et liste ce qui manque."),
  ]);
  return { messages: [res] };
}

// Observe : après les outils, la politique du système décide de la suite.
const afterTools = (s: S) => {
  if (s.iterations >= MAX_ITERATIONS) return "degrade";
  if (s.iterations % REFLECT_EVERY === 0) return "reflect";
  return "agent";
};

export const graph = new StateGraph(State)
  .addNode("agent", agent)
  .addNode("tools", new ToolNode(tools))
  .addNode("reflect", reflect)
  .addNode("degrade", degrade)
  .addEdge(START, "agent")
  .addConditionalEdges("agent", toolsCondition, ["tools", END])
  .addConditionalEdges("tools", afterTools, ["agent", "reflect", "degrade"])
  .addEdge("reflect", "agent")
  .addEdge("degrade", END)
  .compile();

// Filet de sécurité technique : recursionLimit, en super-steps.
export async function run(question: string) {
  try {
    return await graph.invoke({ messages: [new HumanMessage(question)] }, { recursionLimit: 40 });
  } catch (e) {
    if (e instanceof GraphRecursionError) return { messages: [new AIMessage("Je n'ai pas pu conclure.")] };
    throw e;
  }
}

import { StateGraph, StateSchema, ReducedValue, Command, GraphRecursionError, START, END } from "@langchain/langgraph";
import { createAgent, type ReactAgent } from "langchain";
import { tool } from "@langchain/core/tools";
import { z } from "zod";
import { llm, fast } from "./models";

// Ports : recherche web, CRM et facturation.
declare function webSearch(query: string): Promise<string>;
declare function crmAccount(company: string): Promise<string>;
declare function listInvoices(company: string): Promise<string>;

const webSearchTool = tool(({ query }) => webSearch(query), {
  name: "web_search",
  description: "Recherche web",
  schema: z.object({ query: z.string() }),
});
const crmTool = tool(({ company }) => crmAccount(company), {
  name: "crm_account",
  description: "Fiche du compte dans le CRM",
  schema: z.object({ company: z.string() }),
});
const invoicesTool = tool(({ company }) => listInvoices(company), {
  name: "list_invoices",
  description: "Factures et règlements du compte",
  schema: z.object({ company: z.string() }),
});

// Chaque spécialiste est un agent ReAct complet (createAgent) : son prompt, ses outils, son contexte.
const researcherAgent = createAgent({
  model: llm,
  tools: [webSearchTool],
  systemPrompt: "Tu enquêtes sur une entreprise : actualités, marchés publics, recrutements. Rends une synthèse sourcée.",
});
const analystAgent = createAgent({
  model: llm,
  tools: [crmTool, invoicesTool],
  systemPrompt: "Tu analyses la relation commerciale : contrats, factures, impayés. Rends une synthèse chiffrée.",
});

type Report = { agent: string; summary: string };
const MAX_ROUNDS = 6;

const State = new StateSchema({
  brief: z.string(),
  task: z.string().default(""),
  rounds: z.number().default(0),
  // Chaque spécialiste ajoute son compte rendu : le superviseur ne voit que ces synthèses.
  reports: new ReducedValue(z.array(z.custom<Report>()).default(() => []), {
    reducer: (all, added) => all.concat(added),
  }),
  final: z.string().default(""),
});
type S = typeof State.State;

const Route = z.object({
  next: z.enum(["researcher", "analyst", "writer", "FINISH"]),
  task: z.string().describe("Consigne courte pour l'agent choisi"),
});

// Le superviseur choisit qui intervient et avec quelle consigne ; le code borne la boucle.
async function supervisor(s: S) {
  if (s.final || s.rounds >= MAX_ROUNDS) return new Command({ goto: END });
  const done = s.reports.map((r) => `## ${r.agent}\n${r.summary}`).join("\n\n") || "(rien pour l'instant)";
  const route = await fast.withStructuredOutput(Route, { method: "jsonSchema" }).invoke(
    `Tu coordonnes la préparation d'un rendez-vous client.\nDemande : ${s.brief}\n\nDéjà fait :\n${done}\n\n` +
      "Qui doit intervenir maintenant, et avec quelle consigne ? Le rédacteur passe en dernier.",
  );
  if (route.next === "FINISH") return new Command({ goto: END });
  return new Command({ goto: route.next, update: { task: route.task, rounds: s.rounds + 1 } });
}

// Chaque spécialiste démarre avec un contexte vierge : la consigne du superviseur, rien d'autre.
// Un spécialiste qui boucle rend un compte rendu partiel au lieu de faire échouer tout le graphe.
const delegate = (name: string, agent: ReactAgent) => async (s: S) => {
  try {
    const out = await agent.invoke({ messages: [{ role: "user", content: s.task }] }, { recursionLimit: 20 });
    return { reports: [{ agent: name, summary: out.messages.at(-1)?.text ?? "" }] };
  } catch (e) {
    if (!(e instanceof GraphRecursionError)) throw e;
    return { reports: [{ agent: name, summary: "Enquête interrompue : limite d'étapes atteinte." }] };
  }
};

const researcher = delegate("researcher", researcherAgent);
const analyst = delegate("analyst", analystAgent);

// Le rédacteur n'a pas besoin d'outils : un simple appel au modèle suffit.
async function writer(s: S) {
  const notes = s.reports.map((r) => `## ${r.agent}\n${r.summary}`).join("\n\n");
  const res = await llm.invoke(`Rédige une fiche de préparation d'une page à partir de ces notes.\n\n${notes}`);
  return { final: res.text };
}

export const graph = new StateGraph(State)
  .addNode("supervisor", supervisor, { ends: ["researcher", "analyst", "writer", END] })
  .addNode("researcher", researcher)
  .addNode("analyst", analyst)
  .addNode("writer", writer)
  .addEdge(START, "supervisor")
  .addEdge("researcher", "supervisor")
  .addEdge("analyst", "supervisor")
  .addEdge("writer", "supervisor")
  .compile();

import { StateGraph, StateSchema, START, END } from "@langchain/langgraph";
import type { DocumentInterface } from "@langchain/core/documents";
import { z } from "zod";
import { llm } from "./models";

// Ports : vector store (pgvector, Qdrant…) et recherche web (Tavily, Exa…).
interface Retriever { search(q: string, k: number): Promise<DocumentInterface[]> }
interface WebSearch { search(q: string): Promise<DocumentInterface[]> }
declare const retriever: Retriever;
declare const web: WebSearch;

const Answer = z.object({
  text: z.string(),
  citations: z.array(z.string()).describe("ids des passages utilisés, ex. doc-12#3"),
  confidence: z.number().min(0).max(1),
});

const State = new StateSchema({
  question: z.string(),
  docs: z.array(z.custom<DocumentInterface>()).default(() => []),
  answer: Answer.extend({ flagged: z.boolean().optional() }).optional(),
  usedWeb: z.boolean().default(false),
});
type S = typeof State.State;

const retrieve = async (s: S) => ({ docs: await retriever.search(s.question, 6) });
const webSearch = async (s: S) => ({ docs: await web.search(s.question), usedWeb: true });

async function generate(s: S) {
  const context = s.docs.map((d) => `[${d.metadata.id}] ${d.pageContent}`).join("\n\n");
  const res = await llm.withStructuredOutput(Answer, { method: "jsonSchema" }).invoke([
    ["system",
      "Réponds UNIQUEMENT à partir du contexte. Chaque affirmation cite un id entre crochets. " +
      "Si le contexte ne suffit pas, dis-le et mets confidence < 0.5."],
    ["user", `Contexte :\n${context}\n\nQuestion : ${s.question}`],
  ]);

  // Grounding déterministe : on ne croit pas le modèle sur parole.
  const known = new Set(s.docs.map((d) => String(d.metadata.id)));
  const grounded = res.citations.length > 0 && res.citations.every((c) => known.has(c));
  return { answer: { ...res, confidence: grounded ? res.confidence : 0 } };
}

const flagLowConfidence = (s: S) => ({ answer: { ...s.answer!, flagged: true } });

function route(s: S) {
  if (s.answer!.confidence >= 0.6) return END;
  return s.usedWeb ? "flag" : "webSearch";
}

export const graph = new StateGraph(State)
  .addNode("retrieve", retrieve)
  .addNode("generate", generate)
  .addNode("webSearch", webSearch)
  .addNode("flag", flagLowConfidence)
  .addEdge(START, "retrieve")
  .addEdge("retrieve", "generate")
  .addConditionalEdges("generate", route, ["webSearch", "flag", END])
  .addEdge("webSearch", "generate")
  .addEdge("flag", END)
  .compile();

import { StateGraph, StateSchema, ReducedValue, Command, MemorySaver, START, END, interrupt } from "@langchain/langgraph";
import { z } from "zod";
import { llm } from "./models";

type Ticket = { id: string; customer: string; body: string; orderTotal: number };
interface Refunds { apply(ticketId: string, d: Decision, idempotencyKey: string): Promise<void> }
declare const refunds: Refunds;

const Decision = z.object({
  action: z.enum(["refund", "reject", "escalate"]),
  amount: z.number().nonnegative().optional(),
  rationale: z.string(),
  confidence: z.number().min(0).max(1),
});
type Decision = z.infer<typeof Decision>;

type AuditEntry = { at: string; actor: string; event: string; data?: unknown };
const audit = (actor: string, event: string, data?: unknown): AuditEntry => ({
  at: new Date().toISOString(), actor, event, data,
});

type HumanReview = {
  decision: "approve" | "edit" | "reject";
  reviewer: string;
  edited?: Decision;
  comment?: string;
};

const State = new StateSchema({
  ticket: z.custom<Ticket>(),
  proposal: Decision.optional(),
  approved: Decision.nullable().default(null),
  // Piste d'audit : chaque événement s'ajoute, rien ne s'efface.
  audit: new ReducedValue(z.array(z.custom<AuditEntry>()).default(() => []), {
    reducer: (all, added) => all.concat(added),
  }),
});
type S = typeof State.State;

async function propose(s: S) {
  const proposal = await llm.withStructuredOutput(Decision, { method: "jsonSchema" }).invoke(
    `Ticket SAV (commande de ${s.ticket.orderTotal} €) :\n${s.ticket.body}\nPropose une action et ta confiance.`,
  );
  return { proposal, audit: [audit("agent", "proposed", proposal)] };
}

// Seul un petit remboursement sûr passe seul : tout le reste (confiance basse, gros montant,
// montant absent, rejet ou escalade) va à un humain.
const needsHuman = (s: S) => {
  const p = s.proposal!;
  return p.action === "refund" && p.amount !== undefined && p.amount <= 200 && p.confidence >= 0.8
    ? "autoApprove"
    : "review";
};

const autoApprove = (s: S) => ({ approved: s.proposal!, audit: [audit("policy", "auto_approved")] });

function review(s: S) {
  // À la reprise, le nœud est rejoué depuis le début : aucun effet de bord avant interrupt().
  const human = interrupt<{ ticketId: string; proposal: Decision }, HumanReview>({
    ticketId: s.ticket.id,
    proposal: s.proposal!,
  });
  const entry = audit(human.reviewer, `human_${human.decision}`, { comment: human.comment, edited: human.edited });

  if (human.decision === "reject") {
    return new Command({ goto: END, update: { approved: null, audit: [entry] } });
  }
  const approved = human.decision === "edit" && human.edited ? human.edited : s.proposal!;
  return new Command({ goto: "execute", update: { approved, audit: [entry] } });
}

async function execute(s: S) {
  await refunds.apply(s.ticket.id, s.approved!, `refund:${s.ticket.id}`);
  return { audit: [audit("system", "executed", s.approved)] };
}

export const graph = new StateGraph(State)
  .addNode("propose", propose)
  .addNode("autoApprove", autoApprove)
  .addNode("review", review, { ends: ["execute", END] })
  .addNode("execute", execute)
  .addEdge(START, "propose")
  .addConditionalEdges("propose", needsHuman, ["review", "autoApprove"])
  .addEdge("autoApprove", "execute")
  .addEdge("execute", END)
  .compile({ checkpointer: new MemorySaver() }); // en production : PostgresSaver

// Un fil d'exécution par ticket : c'est lui qui permet de reprendre plus tard.
const thread = (ticketId: string) => ({ configurable: { thread_id: `ticket:${ticketId}` } });

// En cas de pause, le résultat contient __interrupt__ : la proposition à montrer au gestionnaire.
export const handleTicket = (ticket: Ticket) => graph.invoke({ ticket }, thread(ticket.id));

// Plus tard, depuis le back-office (une autre requête HTTP) :
export const resume = (ticketId: string, review: HumanReview) =>
  graph.invoke(new Command({ resume: review }), thread(ticketId));