Construire un agent IA spécifique à votre métier — une PME au Sénégal qui veut un assistant facturation, une agence web qui veut un agent SEO, un cabinet comptable qui veut un agent de pré-saisie — passe par l’écriture d’un agent custom basé sur le Claude Agent SDK. Ce tutoriel vous guide pas à pas dans la création d’un agent réel : un assistant qui lit les emails entrants, identifie les demandes de devis, consulte le catalogue de produits, et propose une réponse argumentée à valider par l’humain. Toutes les techniques utilisées sont transposables à d’autres cas métier.
Ce tutoriel s’inscrit dans notre série Claude Agent SDK. Pour les bases conceptuelles, lisez d’abord notre guide pratique Claude Agent SDK 2026.
Le cas d’usage
Vous gérez une boutique de matériel informatique à Dakar. Vous recevez 30-50 emails par jour, dont 10-15 demandes de devis. Aujourd’hui, votre commercial passe 2-3 heures par jour à lire ces emails, ouvrir le catalogue Excel, vérifier le stock, et rédiger des réponses. L’objectif : un agent qui prépare une réponse argumentée que le commercial valide ou amende en 2 minutes au lieu de 15.
L’agent doit pouvoir : lire un email, chercher les produits demandés dans le catalogue, vérifier le stock dans la base, proposer un prix avec marge configurable, rédiger une réponse en français professionnel, et ne JAMAIS envoyer l’email lui-même — toujours laisser l’humain valider.
Prérequis
- Bun ou Node.js 20+
- Clef API Anthropic (variable ANTHROPIC_API_KEY)
- Une base SQLite ou PostgreSQL avec un schéma produits/stock (on en simulera une simple)
- Niveau attendu : intermédiaire avancé
- Temps : 2-3 heures
Étape 1 — Setup du projet
mkdir agent-devis && cd agent-devis
bun init -y
bun add @anthropic-ai/claude-agent-sdk zod
bun add -D @types/bun
echo "ANTHROPIC_API_KEY=sk-ant-api03-..." > .envÉtape 2 — Catalogue et stock simulés
// src/data.ts
export const catalogue = [
{ ref: "LAP-DELL-7530", nom: "Laptop Dell Latitude 7530 i7 16Go 512Go", prixAchat: 650000, marge: 0.20 },
{ ref: "LAP-HP-840", nom: "Laptop HP EliteBook 840 i5 16Go 256Go", prixAchat: 580000, marge: 0.18 },
{ ref: "ECR-DELL-24", nom: "Écran Dell P2422H 24 pouces", prixAchat: 95000, marge: 0.25 },
{ ref: "CLA-LOG-MX", nom: "Clavier Logitech MX Keys", prixAchat: 75000, marge: 0.30 },
{ ref: "SOU-LOG-MX", nom: "Souris Logitech MX Master 3", prixAchat: 65000, marge: 0.30 },
{ ref: "ROU-CIS-2960", nom: "Routeur Cisco Catalyst 2960", prixAchat: 280000, marge: 0.22 },
];
export const stock: Record<string, number> = {
"LAP-DELL-7530": 5, "LAP-HP-840": 2, "ECR-DELL-24": 12,
"CLA-LOG-MX": 8, "SOU-LOG-MX": 15, "ROU-CIS-2960": 1,
};
export function calculerPrix(ref: string, quantite: number) {
const item = catalogue.find((p) => p.ref === ref);
if (!item) return null;
const prixUnitaire = Math.round(item.prixAchat * (1 + item.marge));
return { prixUnitaire, total: prixUnitaire * quantite };
}Étape 3 — Définir les outils custom
// src/tools.ts
import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
import { catalogue, stock, calculerPrix } from "./data";
export const searchCatalogue = tool(
"searchCatalogue",
"Cherche des produits dans le catalogue par mot-clé",
{ keyword: z.string() },
async ({ keyword }) => {
const results = catalogue.filter((p) =>
p.nom.toLowerCase().includes(keyword.toLowerCase()) ||
p.ref.toLowerCase().includes(keyword.toLowerCase()),
);
return {
found: results.length,
products: results.map(({ ref, nom }) => ({ ref, nom })),
};
},
);
export const getStock = tool(
"getStock",
"Vérifie la quantité en stock pour une référence",
{ ref: z.string() },
async ({ ref }) => ({
ref,
stock: stock[ref] ?? 0,
disponible: (stock[ref] ?? 0) > 0,
}),
);
export const computePrice = tool(
"computePrice",
"Calcule le prix de vente pour une référence et quantité",
{ ref: z.string(), quantite: z.number().int().positive() },
async ({ ref, quantite }) => {
const result = calculerPrix(ref, quantite);
if (!result) return { error: "Référence inconnue" };
return result;
},
);Étape 4 — System prompt métier
// src/prompt.ts
export const SYSTEM_PROMPT = `Tu es un assistant commercial pour ITHardware Dakar, boutique de matériel informatique au Sénégal.
Pour chaque demande de devis :
1. Identifie les produits demandés
2. Cherche dans le catalogue avec searchCatalogue
3. Vérifie le stock avec getStock pour chaque référence
4. Calcule le prix avec computePrice
5. Rédige une réponse professionnelle en français
RÈGLES STRICTES :
- Si un produit n'est pas en stock, propose une alternative équivalente
- Mentionne toujours le délai de livraison (24h Dakar, 3-5 jours reste du Sénégal)
- Reste poli, en français professionnel, sans tutoiement
- Termine par "Pour valider ce devis, merci de répondre par email ou WhatsApp au +221 XX XXX XX XX"
- N'invente jamais une référence qui n'existe pas dans le catalogue
- Ne lance JAMAIS d'envoi d'email réel — tu ne fais que préparer le brouillon`;Étape 5 — L’agent principal
// src/agent.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
import { searchCatalogue, getStock, computePrice } from "./tools";
import { SYSTEM_PROMPT } from "./prompt";
export async function traiterEmail(emailContent: string) {
console.log("=== AGENT DEVIS — démarrage ===");
const result = query({
prompt: `Email reçu :
---
${emailContent}
---
Prépare un brouillon de réponse devis détaillé.`,
options: {
systemPrompt: SYSTEM_PROMPT,
customTools: [searchCatalogue, getStock, computePrice],
allowedTools: ["searchCatalogue", "getStock", "computePrice"],
model: "claude-sonnet-4-6",
enableCaching: true,
maxTurns: 12,
},
});
let finalResponse = "";
for await (const message of result) {
if (message.type === "tool_use") console.log(`→ outil : ${message.toolName}`);
else if (message.type === "assistant_text") finalResponse += message.text;
}
return finalResponse;
}Étape 6 — Tester
// src/main.ts
import { traiterEmail } from "./agent";
const email = `Bonjour,
Je suis directeur d'une PME à Thiès et je cherche à équiper 3 nouveaux postes :
- 3 laptops (gamme Dell Latitude)
- 3 écrans 24 pouces
- 3 ensembles clavier-souris Logitech
Pouvez-vous me faire un devis ?
M. Diop`;
const reponse = await traiterEmail(email);
console.log(reponse);Lancez avec bun run src/main.ts. L’agent appelle searchCatalogue plusieurs fois, getStock pour chaque ref, computePrice pour chaque ligne, et synthétise une réponse complète en français. Comptez 8-15 secondes, ~0.05-0.10 USD de tokens.
Étape 7 — Intégration emails
- IMAP polling : un cron qui se connecte toutes les 5 minutes, récupère les nouveaux emails, lance l’agent, écrit le brouillon dans « Brouillons » Outlook/Gmail. Le commercial valide depuis Outlook et envoie.
- Webhook via service tiers : Mailgun, Postmark ou Sendgrid permettent de déclencher un webhook à chaque email reçu. Plus rapide et plus moderne.
Architecture recommandée : agent en mode « préparer le brouillon », validation humaine systématique avant envoi. Pour une vraie automatisation totale, ajoutez un score de confiance et n’auto-envoyez que les réponses simples avec score > 0.95.
Étape 8 — Améliorations à itérer
- Historique client : ajouter
getClientHistorypour adapter la marge fidélité - Marge dynamique : selon volume, type de client, période
- Multi-devises : convertir FCFA ↔ USD pour clients internationaux
- Détection gros comptes : escalader à un commercial senior si devis > seuil
- Caching de prompt : déjà activé, le SYSTEM_PROMPT est mis en cache après le premier appel
Sécurité et permissions
- allowedTools strict : ne mettre QUE les outils nécessaires. Pas de Bash, pas de Write, pas de WebFetch sauf justification.
- Validation côté code : ne pas faire confiance aux paramètres reçus de l’agent. Validez avec Zod, ajoutez des contrôles métier (montant max, ref existe).
- Logging exhaustif : toutes les exécutions d’outils, prompts, réponses dans une base d’audit.
Coût et ROI
50 emails par jour à ~0.05-0.10 USD chacun = 2-5 USD par jour, soit 60-150 USD par mois. En face, le commercial économise 2 heures par jour, soit 40-50 heures par mois. Au taux horaire d’un commercial à 5 000 FCFA, c’est 200 000-250 000 FCFA d’économie nette mensuelle (~330-410 USD). ROI très positif dès le premier mois.
Adaptation Afrique de l’Ouest
Ajustements pertinents : prix en FCFA, mention paiement Mobile Money (Wave, Orange Money), délais réalistes selon les villes (Dakar/Abidjan rapides, intérieur plus lent), formules de politesse en français formel, certificat d’origine si export CEDEAO.
Erreurs fréquentes
| Erreur | Cause | Solution |
|---|---|---|
| Agent invente une référence | Pas dans le catalogue | Règle stricte system prompt + validation côté code |
| Boucle infinie tool calls | maxTurns absent | maxTurns: 10-15 |
| Prix erroné | Agent improvise | Toujours passer par computePrice |
| Réponse en anglais | System prompt ambigu | Préciser « rédige en français » |
| Cache miss | System prompt dynamique | Hardcoder, ne pas reconstruire à chaque appel |
Pour aller plus loin
- guide pratique Claude Agent SDK 2026
- MCP server custom métier
- Sub-agents et orchestration
- Hooks et permissions
- Documentation officielle : docs.anthropic.com/en/api/agent-sdk
À lire aussi : utiliser vLLM comme backend d’inférence.