Comment construire un harnais d'agent personnalisé

Comment construire un harnais d'agent personnalisé

Construire un harnais d'agent personnalisé est une manière pratique d'orchestrer des agents IA, de gérer leurs outils et de contrôler leurs interactions. Contrairement aux frameworks prêts à l'emploi, un harnais personnalisé vous offre un contrôle précis sur le comportement de l'agent, la gestion du contexte et la récupération d'erreurs. Cet article vous guide à travers une implémentation complète et pratique en Python, en mettant l'accent sur la clarté et l'extensibilité.

Prérequis

Avant de commencer, assurez-vous que votre environnement répond à ces exigences :

• Python 3.10 ou version ultérieure installé sur votre système
• Le gestionnaire de paquets pip (fourni avec Python)
• Une familiarité de base avec les outils en ligne de commande et la syntaxe Python
• Une clé API pour au moins un fournisseur LLM (OpenAI est utilisé dans les exemples)

Les paquets Python suivants sont nécessaires :

• `openai` – pour les appels API LLM
• `httpx` – pour les requêtes HTTP vers les outils
• `pydantic` – pour la validation des données et la configuration

Installation étape par étape

1. Configurer un environnement virtuel Python

Isolez les dépendances pour éviter les conflits avec d'autres projets.

python -m venv agent-harness
source agent-harness/bin/activate  # Sur Windows : agent-harness\Scripts\activate

2. Installer les paquets requis

Installez les bibliothèques principales pour la communication API et la modélisation des données.

pip install openai httpx pydantic

3. Créer la structure du projet

Organisez votre code en modules pour une meilleure maintenabilité.

mkdir -p agent_harness/tools
touch agent_harness/__init__.py
touch agent_harness/core.py
touch agent_harness/tools/__init__.py
touch agent_harness/tools/search.py
touch agent_harness/tools/calculator.py
touch main.py

4. Configurer les variables d'environnement

Stockez vos clés API de manière sécurisée. Créez un fichier `.env` (non commité dans le contrôle de version) ou exportez-les directement.

export OPENAI_API_KEY="votre-clé-api-ici"

Construire le harnais d'agent principal

La classe Agent

Le cœur du harnais est une classe `Agent` qui gère le LLM, les outils et l'historique des conversations.

# agent_harness/core.py
import os
from typing import List, Dict, Any, Callable
from openai import OpenAI

class Tool:
    """Représente un outil que l'agent peut utiliser."""
    def __init__(self, name: str, description: str, function: Callable):
        self.name = name
        self.description = description
        self.function = function

class Agent:
    def __init__(self, model: str = "gpt-4", tools: List[Tool] = None):
        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
        self.model = model
        self.tools = tools or []
        self.history = []
        
    def add_tool(self, tool: Tool):
        """Enregistrer un nouvel outil."""
        self.tools.append(tool)
        
    def build_system_prompt(self) -> str:
        """Créer le prompt système listant les outils disponibles."""
        tool_descriptions = "\n".join(
            [f"- {t.name}: {t.description}" for t in self.tools]
        )
        return f"""Vous êtes un assistant utile avec accès aux outils suivants :
{tool_descriptions}

Lorsque vous devez utiliser un outil, répondez avec :
OUTIL : nom_outil
ARGS : arg1=valeur1, arg2=valeur2

Sinon, répondez directement."""

Ajouter l'exécution des outils

Le harnais doit analyser les appels aux outils et les exécuter en toute sécurité.

# agent_harness/core.py (suite)
    def run(self, user_input: str) -> str:
        """Traiter l'entrée utilisateur et retourner la réponse de l'agent."""
        self.history.append({"role": "user", "content": user_input})
        
        # Construire les messages pour le LLM
        messages = [{"role": "system", "content": self.build_system_prompt()}]
        messages.extend(self.history)
        
        # Obtenir la réponse du LLM
        response = self.client.chat.completions.create(
            model=self.model,
            messages=messages,
            temperature=0.7
        )
        
        content = response.choices[0].message.content
        
        # Vérifier l'invocation d'un outil
        if content.startswith("OUTIL:"):
            tool_name = content.split("\n")[0].replace("OUTIL:", "").strip()
            args_line = content.split("\n")[1].replace("ARGS:", "").strip()
            args = self._parse_args(args_line)
            
            # Exécuter l'outil
            for tool in self.tools:
                if tool.name == tool_name:
                    result = tool.function(**args)
                    self.history.append({"role": "assistant", "content": content})
                    self.history.append({"role": "tool", "content": str(result)})
                    return self.run(f"Résultat de l'outil : {result}")
                    
        self.history.append({"role": "assistant", "content": content})
        return content
        
    def _parse_args(self, args_str: str) -> Dict[str, Any]:
        """Analyser les arguments clé=valeur depuis une chaîne."""
        args = {}
        for pair in args_str.split(","):
            key, value = pair.split("=")
            args[key.strip()] = value.strip()
        return args

Construire des exemples d'outils

Outil de recherche web

Un outil simple qui effectue une recherche web simulée. En production, remplacez par une API réelle.

# agent_harness/tools/search.py
import httpx

def web_search(query: str) -> str:
    """Effectuer une recherche web simulée."""
    # En production, utilisez une vraie API de recherche comme SerpAPI ou Bing
    return f"Résultats de recherche simulés pour '{query}' : 3 documents pertinents trouvés."

Outil de calculatrice

Une calculatrice sécurisée utilisant `eval` de Python avec des globals restreints.

# agent_harness/tools/calculator.py
def calculator(expression: str) -> str:
    """Évaluer une expression mathématique en toute sécurité."""
    allowed_names = {"abs", "round", "min", "max", "sum", "pow"}
    try:
        # Autoriser uniquement les opérations mathématiques de base
        result = eval(expression, {"__builtins__": {}}, {name: __builtins__.__dict__[name] for name in allowed_names})
        return f"Résultat : {result}"
    except Exception as e:
        return f"Erreur : {str(e)}"

Exemples d'utilisation

Exécuter le harnais

Créez un script principal pour démontrer l'agent en action.

# main.py
from agent_harness.core import Agent, Tool
from agent_harness.tools.search import web_search
from agent_harness.tools.calculator import calculator

def main():
    # Initialiser l'agent
    agent = Agent(model="gpt-4")
    
    # Enregistrer les outils
    agent.add_tool(Tool(
        name="web_search",
        description="Rechercher des informations sur internet",
        function=web_search
    ))
    agent.add_tool(Tool(
        name="calculator",
        description="Évaluer des expressions mathématiques",
        function=calculator
    ))
    
    # Boucle interactive
    print("Harnais d'agent prêt. Tapez 'exit' pour quitter.")
    while True:
        user_input = input("\nVous : ")
        if user_input.lower() == "exit":
            break
            
        response = agent.run(user_input)
        print(f"Agent : {response}")

if __name__ == "__main__":
    main()

Exécutez le harnais :

python main.py

Exemple d'interaction :

Harnais d'agent prêt. Tapez 'exit' pour quitter.

Vous : Combien font 2 + 2 ?
Agent : 4

Vous : Recherche les dernières actualités IA
Agent : Résultats de recherche simulés pour 'dernières actualités IA' : 3 documents pertinents trouvés.

Configuration avancée

Ajoutez la prise en charge de la mémoire de conversation et du délai d'attente des outils.

# agent_harness/core.py (ajouter à la classe Agent)
    def clear_history(self):
        """Réinitialiser le contexte de conversation."""
        self.history = []
        
    def run_with_timeout(self, user_input: str, timeout: int = 30) -> str:
        """Exécuter avec un délai d'attente pour la sécurité."""
        import signal
        
        def handler(signum, frame):
            raise TimeoutError("L'exécution de l'agent a expiré")
            
        signal.signal(signal.SIGALRM, handler)
        signal.alarm(timeout)
        
        try:
            return self.run(user_input)
        finally:
            signal.alarm(0)

Bonnes pratiques

Gestion des erreurs

Encapsulez l'exécution des outils dans des blocs try-except pour éviter les plantages de l'agent.

# Dans Agent.run()
try:
    result = tool.function(**args)
except Exception as e:
    result = f"L'exécution de l'outil a échoué : {str(e)}"

Limitation de débit

Implémentez un backoff exponentiel pour les appels API.

import time
from openai import RateLimitError

def run_with_retry(self, user_input: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            return self.run(user_input)
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

Journalisation

Ajoutez une journalisation structurée pour le débogage et la surveillance.

import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Dans Agent.run()
logger.info(f"Entrée utilisateur : {user_input}")
logger.info(f"Outil invoqué : {tool_name}")

Conclusion

Construire un harnais d'agent personnalisé vous donne un contrôle total sur le fonctionnement de vos agents IA. Cette implémentation fournit une base solide avec :

• Une architecture modulaire qui sépare la logique principale des outils
• Une exécution sécurisée des outils avec gestion des erreurs
• Une gestion propre de l'historique des conversations
• Une extensibilité facile pour de nouvelles capacités

Le harnais peut être étendu avec des fonctionnalités comme l'exécution parallèle d'outils, les réponses en streaming ou l'état persistant. Commencez avec cette base, puis ajoutez des outils spécifiques à votre domaine — qu'il s'agisse de requêtes de base de données, d'intégrations API ou de traitement de données personnalisé. La clé est de maintenir la séparation entre le raisonnement de l'agent et l'exécution des outils, ce qui rend le débogage et la mise à l'échelle simples.

En construisant des agents plus complexes, n'oubliez pas de prioriser la sécurité via la validation des entrées, les mécanismes de délai d'attente et la surveillance des ressources. Un harnais bien construit servira de colonne vertébrale fiable pour vos applications IA, que vous alimentiez un chatbot, un assistant de recherche ou un système de workflow automatisé.