#Pourquoi construire un agent IA local

Un agent IA local répond à trois besoins que le cloud gère mal. D'abord la confidentialité : quand un agent lit vos emails, interroge votre base de données ou parcourt vos fichiers, chaque appel envoyé à une API externe est une fuite potentielle. En local, le contexte ne sort jamais de la machine. Ensuite le coût : un agent enchaîne des dizaines d'appels au modèle pour une seule tâche, et la facture d'une API à l'usage explose vite. Enfin l'autonomie : pas de limite de débit, pas de coupure réseau, pas de changement de politique tarifaire du jour au lendemain.

Le prix à payer est réel : un modèle local de 14B ou 32B ne raisonne pas aussi finement que les meilleurs modèles propriétaires. La conception de l'agent — outils bien découpés, prompts stricts, garde-fous — compte donc davantage que dans le cloud. C'est précisément ce que couvre ce guide sur l'agent IA local.

Agent ≠ chatbot

Un chatbot répond. Un agent décide quoi faire, exécute une action (appel d'outil), lit le résultat, puis recommence jusqu'à atteindre l'objectif. Cette boucle « raisonner → agir → observer » est le cœur du sujet.

#Anatomie d'un agent

Peu importe le framework, un agent IA local repose toujours sur les mêmes briques. Les comprendre permet de choisir ses outils en connaissance de cause plutôt que de suivre un tutoriel à l'aveugle.

Le modèle (raisonnement): Le LLM qui décide de l'action suivante. Il doit gérer le tool calling de façon fiable : Qwen 3.x, Granite 4.x ou Mistral Small sont de bons candidats en local.
Les outils (actions): Des fonctions Python que l'agent peut appeler : lire un fichier, requêter une API, exécuter une recherche, écrire dans une base. Chaque outil est décrit par un schéma JSON que le modèle lit.
La mémoire (état): Court terme (l'historique de la conversation en cours) et long terme (un vector store qui survit entre les sessions). C'est le rôle du RAG, détaillé plus bas.
L'orchestrateur (boucle): Le code qui enchaîne raisonnement, appel d'outil et observation jusqu'à la condition d'arrêt. C'est ce que fournit un framework comme CrewAI ou AutoGen.
Le planificateur (stratégie): La logique qui découpe un objectif complexe en sous-tâches ordonnées. Il peut être explicite (un agent planificateur dédié) ou implicite (le modèle raisonne étape par étape).

Un agent minimal se contente d'un modèle, de deux ou trois outils et d'une boucle. Un système avancé ajoute mémoire persistante, planification multi-étapes et plusieurs agents spécialisés qui collaborent. Commencez simple : la plupart des tâches ne justifient pas une équipe de dix agents.

#Prérequis et stack recommandée

La stack de référence pour un agent IA local tient en trois couches : Ollama pour servir le modèle, un framework d'orchestration en Python, et un modèle capable de tool calling. Ollama écoute par défaut sur http://localhost:11434 et expose un endpoint compatible OpenAI, ce qui simplifie l'intégration avec la plupart des frameworks.

GPU / VRAM: Un agent raisonne mieux avec un modèle 14B+ que 7B. Comptez ~9 Go de VRAM pour un 14B en Q4_K_M, ~19 Go pour un 32B. Une RTX 4070 12 Go fait tourner du 14B confortablement ; une RTX 4090 24 Go ou un Mac M4 Pro visent le 32B.
Modèle: Choisissez un modèle réputé fiable en tool calling. La qualité du function calling compte plus que la taille brute : un 14B rigoureux bat un 32B qui invente des arguments.
Python 3.10+: CrewAI et AutoGen sont des bibliothèques Python. Travaillez dans un environnement virtuel dédié pour éviter les conflits de dépendances.
Quantization: Q4_K_M est le bon compromis par défaut. Montez en Q5_K_M ou Q8_0 si le modèle commet des erreurs de raisonnement et que la VRAM le permet.

Terminal — préparer la stack

# 1. Vérifier qu'Ollama tourne
curl http://localhost:11434/api/tags

# 2. Récupérer un modèle capable de tool calling
ollama pull qwen3:14b

# 3. Environnement Python isolé
python -m venv .venv && source .venv/bin/activate
pip install crewai crewai-tools

→

Testez le tool calling avant tout

Avant de brancher un framework, vérifiez que votre modèle appelle correctement une fonction simple via l'API d'Ollama. Un agent construit sur un modèle qui hallucine ses appels d'outils sera ingérable — mieux vaut le découvrir tout de suite.

#CrewAI ou AutoGen : lequel choisir ?

Les deux frameworks orchestrent des agents, mais avec des philosophies différentes. Le bon choix dépend de votre tâche, pas d'un classement absolu.

CrewAI: Orienté « équipe » : on définit des agents avec un rôle, un objectif et des outils, puis on leur assigne des tâches ordonnées. Approche déclarative, lisible, idéale pour des pipelines métier (rechercher → rédiger → relire). Mémoire RAG intégrée.
AutoGen: Orienté « conversation » : les agents dialoguent entre eux jusqu'à converger. Plus flexible pour les problèmes ouverts et le raisonnement collaboratif, mais demande plus de réglage pour rester borné en local. La v0.4 se branche sur Ollama via son client compatible OpenAI.
Quand rester simple: Pour un agent unique avec quelques outils, un framework léger (ou LangChain) suffit. CrewAI et AutoGen prennent tout leur sens dès qu'il y a plusieurs rôles ou une orchestration non triviale.

Python — CrewAI branché sur Ollama

from crewai import Agent, Task, Crew, LLM

# CrewAI passe par LiteLLM : préfixe 'ollama/' + base_url local
llm = LLM(
    model="ollama/qwen3:14b",
    base_url="http://localhost:11434",
)

chercheur = Agent(
    role="Analyste documentaire",
    goal="Extraire les faits clés des documents fournis",
    backstory="Expert méthodique, ne répond que sur la base des sources.",
    llm=llm,
    verbose=True,
)

tache = Task(
    description="Résume les 3 points essentiels du rapport fourni.",
    expected_output="Une liste à puces de 3 points, sourcés.",
    agent=chercheur,
)

equipe = Crew(agents=[chercheur], tasks=[tache])
print(equipe.kickoff())

Python — AutoGen 0.4 vers l endpoint Ollama

from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent

# Endpoint OpenAI-compatible d'Ollama : /v1
client = OpenAIChatCompletionClient(
    model="qwen3:14b",
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # ignore par Ollama, mais requis par le client
    model_info={
        "function_calling": True,
        "json_output": True,
        "vision": False,
        "family": "unknown",
    },
)

agent = AssistantAgent(name="assistant", model_client=client)

#Construire l'agent pas à pas

Voici la démarche pour passer d'un modèle brut à un agent IA local qui accomplit une tâche réelle. L'ordre compte : chaque étape valide la précédente.

01
Définir l'objectif et la condition d'arrêt
Écrivez en une phrase ce que l'agent doit produire et comment on sait qu'il a fini. Un objectif flou (« aide-moi ») produit un agent qui tourne en rond ; un objectif borné (« classe ces 20 factures par fournisseur dans un CSV ») produit un agent contrôlable.
02
Découper en outils atomiques
Chaque action externe devient une fonction Python avec un nom explicite, des arguments typés et une docstring claire — c'est cette description que le modèle lit. Préférez plusieurs petits outils précis à un gros outil fourre-tout.
03
Rédiger le prompt système
Cadrez le rôle, les outils disponibles et les règles (ne jamais inventer, toujours citer la source, s'arrêter en cas de doute). En local, un prompt strict compense la moindre finesse de raisonnement du modèle.
04
Câbler la boucle d'orchestration
Laissez le framework gérer la boucle raisonner → agir → observer, mais fixez une limite d'itérations (par exemple 10) pour éviter qu'un agent bloqué ne consomme indéfiniment. C'est un garde-fou essentiel en autonomie.
05
Ajouter la mémoire
Branchez un vector store pour la mémoire long terme si l'agent doit se souvenir entre les sessions (voir section suivante). Sans ce besoin, l'historique de conversation suffit.
06
Tester sur des cas réels et itérer
Lancez l'agent sur des entrées variées, lisez les traces d'exécution (verbose), corrigez les prompts et les descriptions d'outils. 80 % du travail d'un agent local se passe ici, pas dans le code initial.

#Mémoire à long terme avec le RAG

Un agent sans mémoire recommence de zéro à chaque session. La mémoire long terme repose sur le même principe que le RAG (Retrieval-Augmented Generation) : on stocke les informations sous forme de vecteurs dans une base, et on récupère les plus pertinentes au moment voulu pour les réinjecter dans le contexte.

Embeddings locaux: Générez les vecteurs avec un modèle d'embedding servi par Ollama (par exemple nomic-embed-text ou mxbai-embed-large) : les données à mémoriser ne quittent pas la machine, cohérent avec l'objectif de confidentialité.
Vector store: ChromaDB est le choix par défaut en local : léger, persistant sur disque, intégré nativement à CrewAI. Pour de plus gros volumes, Qdrant en self-host prend le relais.
Mémoire intégrée CrewAI: CrewAI expose une mémoire prête à l'emploi (mémoire courte, longue et d'entité) que l'on peut configurer pour utiliser un embedder Ollama, sans monter le pipeline RAG à la main.

Python — mémoire CrewAI avec embeddings Ollama

from crewai import Crew

equipe = Crew(
    agents=[chercheur],
    tasks=[tache],
    memory=True,  # active la memoire long terme (ChromaDB sous le capot)
    embedder={
        "provider": "ollama",
        "config": {"model": "nomic-embed-text"},
    },
)

→

Ne mémorisez pas tout

Une mémoire qui gonfle sans filtre finit par ramener du bruit à chaque requête et dégrade les réponses. Décidez explicitement ce qui mérite d'être retenu (faits durables, préférences utilisateur) et laissez le reste dans la mémoire de session éphémère.

#Planification de tâches

La planification, c'est la capacité de l'agent à découper un objectif complexe en étapes ordonnées avant d'agir. Sans elle, un modèle local a tendance à foncer sur la première action venue et à se perdre. Deux approches coexistent.

Planification implicite (ReAct): Le modèle raisonne à voix haute étape par étape, choisit une action, observe, puis replanifie. Simple à mettre en place, mais fragile sur les petits modèles qui perdent le fil au bout de quelques tours.
Planification explicite: Un agent (ou une première tâche) dédié à la planification produit une liste d'étapes, que des agents d'exécution traitent ensuite. Plus robuste en local : on sépare « penser » et « faire », ce qui allège la charge de chaque appel.
Décomposition hiérarchique: Pour les tâches longues, CrewAI permet un processus hiérarchique où un agent « manager » délègue et supervise. Puissant, mais à réserver aux cas qui le justifient — la coordination coûte des tokens.

Règle pratique en local : plus le modèle est petit, plus la planification doit être explicite et le périmètre de chaque étape restreint. Un 14B qui traite une micro-tâche bien cadrée est plus fiable qu'un 32B lâché sur un objectif vague.

#Sécurité des données

Le tout-local supprime la fuite vers des API tierces, mais un agent autonome introduit ses propres risques : il exécute des actions, parfois destructrices, sur la base d'un texte généré. La confidentialité ne dispense pas de garde-fous.

Principe du moindre privilège: Ne donnez à l'agent que les outils strictement nécessaires. Un agent qui n'a pas besoin d'écrire sur le disque ne doit pas avoir d'outil d'écriture — c'est la première barrière contre les dégâts.
Validation humaine des actions sensibles: Pour tout ce qui est irréversible (supprimer, envoyer, payer, modifier une base), insérez une confirmation manuelle. L'autonomie totale ne se justifie que sur des actions sûres et réversibles.
Isolation de l'exécution de code: Si l'agent exécute du code, faites-le dans un conteneur ou un environnement bac à sable, jamais directement sur la machine hôte. Un prompt malveillant glissé dans un document peut détourner un agent (injection de prompt).
Journalisation des actions: Tracez chaque appel d'outil et chaque décision. En cas de comportement inattendu, la trace est votre seul moyen de comprendre ce que l'agent a réellement fait.

L'injection de prompt reste la menace principale

Un agent qui lit des contenus non fiables (emails, pages web, fichiers reçus) peut être manipulé par des instructions cachées dans ces contenus. Ne mélangez jamais données de confiance et données externes dans le même contexte sans traiter les secondes comme hostiles.

#Astuces et dépannage

L'agent boucle sans jamais s'arrêter: Vérifiez la condition d'arrêt et la limite d'itérations. Souvent l'objectif est trop flou ou l'agent ne reconnaît pas qu'il a terminé : rendez le résultat attendu explicite dans le prompt.
Appels d'outils mal formés: Le modèle invente des arguments ou oublie des champs. Simplifiez les schémas d'outils, montez d'un cran de quantification (Q4 → Q5) ou passez à un modèle plus fiable en tool calling.
Réponses lentes en multi-agents: Chaque agent est un appel complet au modèle. En local, réduisez le nombre d'agents, raccourcissez les prompts système et vérifiez que le modèle tient entièrement en VRAM (sinon l'offload CPU écroule le débit).
La mémoire ne retrouve rien de pertinent: Mauvais modèle d'embedding ou chunks trop gros/trop petits. Vérifiez que l'embedder Ollama tourne, et ajustez la taille des morceaux stockés.
Connexion refusée sur :11434: Ollama n'est pas lancé ou écoute sur une autre interface. Confirmez avec « curl http://localhost:11434/api/tags » et vérifiez la base_url passée au framework.

#Pour aller plus loin

Ce guide pose l'architecture ; ces tutoriels entrent dans l'implémentation concrète de chaque brique :

Multi-agents avec CrewAI: « CrewAI + Ollama : orchestrer plusieurs agents IA en local » détaille la mise en place d'une équipe d'agents spécialisés, rôles et tâches à l'appui.
Un agent en Python de A à Z: « Créer un agent IA local en Python avec LangChain et Ollama » construit pas à pas un agent capable d'appeler des outils et de lire des fichiers.
La brique mémoire (RAG): « RAG en local avec ChromaDB et Ollama : tutoriel Python » couvre le pipeline complet embeddings → recherche → réponse, cœur de la mémoire long terme.

Ce guide vous a aidé ?

Un retour, une erreur, une précision ? Faites-nous signe, ça améliore le guide pour tout le monde.

Suite logique

Développement · 14 min