L’API moderne createAgent construit une boucle basée sur LangGraph. Le modèle choisit parmi les outils déclarés jusqu’à produire une réponse ou atteindre une condition d’arrêt.
Installer
~~~bash npm install langchain @langchain/openai zod ~~~
Configurez OPENAI_API_KEY et un modèle actif côté serveur.
Définir l’outil
~~~typescript import { createAgent, tool } from 'langchain'; import * as z from 'zod';
const calculateVat = tool( ({ amount, rate }) => { if (amount > 100000) throw new Error('Montant hors limite'); return JSON.stringify({ total: Math.round(amount * (1 + rate) * 100) / 100 }); }, { name: 'calculate_vat', description: 'Calcule un total TTC depuis un montant HT positif.', schema: z.object({ amount: z.number().nonnegative(), rate: z.number().min(0).max(0.3).default(0.2), }), }, ); ~~~
Le schéma borne l’appel avant exécution. Pour une valeur métier comme un taux officiel, récupérez-la côté serveur plutôt que de la laisser au modèle.
Créer et invoquer
~~~typescript const agent = createAgent({ model: 'openai:votre-modele-actif', tools: [calculateVat], systemPrompt: 'Utilise l’outil pour tout calcul de TVA.', });
const result = await agent.invoke({ messages: [{ role: 'user', content: 'Quel total pour 120 € HT à 20 % ?' }], });
console.dir(result.messages.at(-1), { depth: null }); ~~~
Vérifiez dans la trace que l’outil a réellement été appelé. Testez montant négatif, taux hors limite et demande sans calcul.
Production
Fixez un maximum d’étapes, timeout et budget. Un outil qui écrit doit contrôler identité et autorisation dans le code, demander confirmation et utiliser une clé d’idempotence. Les sorties d’outils sont des données non fiables, même si elles viennent de votre base.
FAQ
Pourquoi Zod ?
Il produit le schéma visible par le modèle et valide les arguments à l’exécution.
createAgent remplace-t-il tous les workflows ?
Non. Pour un processus déterministe, un graphe explicite reste souvent plus prévisible.
Agent avec outil typé et limite de capacité
~~~python from langchain.agents import create_agent from langchain_core.tools import tool
@tool def get_order_status(order_id: str) -> str: """Retourne le statut d’une commande autorisée.""" if not order_id.startswith("ORD-"): raise ValueError("identifiant invalide") return order_repository.status(order_id)
agent = create_agent( model="openai:gpt-4.1-mini", tools=[get_order_status], system_prompt=( "Utilise uniquement les outils fournis. " "Ne devine jamais le statut d’une commande." ), ) result = agent.invoke({ "messages": [{"role": "user", "content": "Statut de ORD-123 ?"}] }) print(result["messages"][-1].content) ~~~
L’outil doit appliquer authentification et autorisation : le modèle ne décide pas quelles commandes l’utilisateur peut lire. Ajoutez timeout, nombre maximal d’étapes et traces d’outils. Exigez une confirmation avant toute opération d’écriture et testez argument invalide, outil indisponible et tentative d’injection.