Accueil / Articles

Cinq modèles d’ingénierie d’agents dignes d’être empruntés à Harness de DeepSeek

Journal des événements en tant que source de vérité, avertissements de boucle gradués, troncature explicite, mode de code vérifié en fonction des permissions et transferts d’agents frais : cinq modèles pour concevoir des systèmes d’agents exploitables en phase de débogage.

Éditeur : REACTAPP.TOP9 min de lecture1995 mots

Sources: 5 Agent-Engineering Patterns I Learned From DeepSeek’s Open-Source Harness

Les agents deviennent de plus en plus compétents pour écrire du code, utiliser des outils, rechercher des fichiers et s’atteler à des tâches longues. Au-delà de tout cela se cache un problème plus subtil : qu’est-ce qui empêche un agent de devenir si complexe, imprévisible et presque impossible à déboguer ? En examinant les choix techniques du framework open source pour agents de DeepSeek, on découvre cinq idées qui méritent d’être reprises, même si l’on n’utilise jamais ce framework. Il ne s’agit pas tant de tours de DeepSeek que de modèles de fonctionnement applicables aux systèmes d’agents en général.

1. Faire du journal des événements la source de vérité

La plupart des systèmes d’agents conservent la conversation sous forme d’une liste qui est transmise au modèle :

messages = [...]

Ailleurs, un journaliste rapporte ce qui s’est passé :

logger.info({
    "messages": messages,
    "tool_calls": tool_calls,
    "tokens": tokens
})

Cela semble raisonnable, mais cela génère deux versions des mêmes événements, et c’est là que réside le risque. Supposons que l’application modifie la liste de messages avant de la envoyer, par exemple en y insérant une instruction supplémentaire :

messages.append({
    "role": "system",
    "content": "Remember to be concise."
})

Si le journal des événements n’a jamais enregistré cette modification, c’est que le modèle a perçu quelque chose dont vos journaux ne savent rien. Six heures plus tard, l’agent agit de manière étrange, et vous ouvrez les journaux en vous demandant pourquoi. L’explication pourrait être un message système qui n’apparaît nulle part dans l’historique enregistré.

L’approche optimale

Faites du journal des événements la source unique d’information fiable. Il contient les faits, tels que la demande de l’utilisateur, chaque appel à outil, chaque résultat ainsi que les réponses de l’assistant :

events = [
    UserMessage("Fix the authentication bug"),
    ToolCall("grep", {"query": "auth"}),
    ToolResult("Found 12 matches"),
    AssistantMessage("I'll inspect the middleware")
]

Le contexte du modèle est ensuite dérivé de ces événements et n’est pas conservé sous forme de liste distincte :

def build_context(events):
    return [
        event.to_message()
        for event in events
        if event.visible_to_model
    ]

Le fait est qu’il n’existe pas d’array de messages privés et cachés. Vous le calculez à chaque fois. Comparez les deux structures. La structure préférée va du journal, en passant par un constructeur de contexte, jusqu’à la demande :

Event Log
    ↓
Context Builder
    ↓
LLM Request

Celui à éviter est celui qui divise le journal, avec une branche qui alimente les journaux et une autre qui alimente les messages destinés au modèle :

Event Log ─────────→ Logs
       \
        → Messages ─→ LLM

Ce petit changement structurel rend le débogage bien plus facile.

Aller plus loin et le vérifier

Pendant le développement, vous pouvez ajouter une vérification qui reconstitue le contexte attendu à partir des journaux et le compare avec ce qui est réellement sur le point d’être envoyé :

expected = build_context(event_log)
actual = request.messages
if actual != expected:
    raise RuntimeError(
        "log-reconstruction desync"
    )

Avec cela en place, l’évolution dans le contexte devient un test qui échoue et n’est plus un bug de production déroutant. Il y a même un avantage supplémentaire : l’observabilité devient bien plus utile. Si une vue de trajectoire affiche les appels au modèle, les appels aux outils, les résultats des outils, l’utilisation des tokens et le temps de traitement, personne n’a besoin de reconstituer séparément ce qui s’est passé, car les informations sont déjà présentes : l’agent en a besoin pour reconstruire son propre contexte. Une seule source de vérité remplit ainsi deux fonctions.

2. Ne bloquez pas immédiatement les boucles d’agent

Tout développeur d’agent rencontre ce problème tôt ou tard. Le modèle exécute la même recherche encore et encore :

grep "authentication"
grep "authentication"
grep "authentication"
grep "authentication"
...

Le problème est évident, et la solution évidente l’est tout autant : refuser les appels répétés.

if previous_call == current_call:
    raise LoopError()

Le problème, c’est que la répétition est parfois justifiée. Une demande réseau peut échouer, un fichier a pu changer, et il est effectivement nécessaire de réessayer. Plutôt que de bloquer le modèle, avertissez-le.

Imaginez un système de pression qui augmente avec le nombre de répétitions :

3 repeats → gentle reminder
5 repeats → stronger reminder
8 repeats → very strong reminder

Le premier niveau pourrait indiquer que la même appel d’outil est répété et suggérer de relire le dernier résultat :

if repeat_count >= 3:
    inject(
        "You are repeating the same tool call. "
        "Re-read the last result and consider another approach."
    )

Le deuxième niveau est plus strict, indiquant à l’agent d’arrêter et de réévaluer :

if repeat_count >= 5:
    inject(
        "You have repeated this exact operation several times. "
        "Stop and reassess the approach."
    )

Dans le troisième point, il est indiqué que cela ressemble à une boucle et que l’approche doit changer, ou bien le travail doit être achevé :

if repeat_count >= 8:
    inject(
        "This appears to be a loop. "
        "Change your approach or wrap up."
    )

Remarquez ce que la sangle ne fait pas. Elle ne renvoie jamais un refus catégorique comme celui-ci :

return False

Le contrôle reste entre les mains du modèle. Le harnais ne fait que fournir davantage d’informations et permet au modèle de prendre la décision, ce qui constitue une distinction importante.

Décompter les répétitions réelles

Un bon détecteur ne doit pas être trompé par des appels non liés insérés entre eux. Cette séquence doit toujours être comptée comme une répétition :

grep foo
todo update
grep foo

Sinon, le modèle pourrait réinitialiser son propre compteur en effectuant des tâches inutiles entre des appels identiques. Les arguments doivent également être normalisés, de sorte que ces deux cas soient considérés comme la même opération :

{"query": "foo", "path": "src"}

et :

{"path": "src", "query": "foo"}

L’ordre des clés dans un dictionnaire ne devrait pas avoir d’importance. Les appels refusés devraient également être pris en compte. Si le modèle continue d’essayer ce genre de chose :

run dangerous command
→ denied
run dangerous command
→ denied
run dangerous command
→ denied

C’est précisément à ce moment-là qu’il doit se rendre compte qu’il pourrait être judicieux d’arrêter d’essayer.

Le schéma général

L’approche faible est une réaction brutale face au mauvais comportement :

Bad behavior → hard block

Un modèle plus robuste détecte ce comportement, augmente les retours d’information et permet au modèle de se remettre :

Bad behavior
     ↓
Detect
     ↓
Increase feedback
     ↓
Let model recover

C’est une idée qui semble simple, mais elle convient à presque tous les frameworks d’agents qui permettent d’exécuter des appels de outils.

3. Indiquez au modèle ce qu’il n’a pas vu

Cela semble évident, pourtant de nombreux outils se trompent. Supposons qu’un répertoire contienne ceci :

4,000 files

et un outil de recherche ne renvoie que ceci :

100 files

Si la réponse se limite simplement à ces cent fichiers, le modèle peut en conclure qu’il y a exactement cent fichiers correspondants. En réalité, l’outil signifiait « voici cent fichiers car j’ai arrêté de chercher », et les deux interprétations sont complètement différentes.

Rendre la troncature explicite

Une meilleure réponse indique ce qui s’est passé et où se trouvent les fichiers restants :

Showing 100 of 4,000 results.
The result set was truncated.
Full results:
~/.agent/search-results/results.txt

Le modèle sait maintenant trois choses : il existe davantage de résultats, ce qu’il a est un sous-ensemble, et la liste complète est accessible si nécessaire. C’est une position bien plus sûre.

L’échantillonnage peut être préférable à la prise des premiers N éléments

Supposons qu’il y ait 4 000 fichiers et que seulement 100 puissent être stockés. La méthode naïve consiste à prendre simplement un extrait :

results[:100]

Les résultats triés peuvent être dangereux, car vous pourriez obtenir une centaine de fichiers provenant d’un seul répertoire ou suivant un même schéma de nommage. Répartir les échantillons dans toute la liste fournit plus d’informations :

def sample_results(results, limit=100):
    step = len(results) / limit
return [
        results[int(i * step)]
        for i in range(limit)
    ]

L’algorithme exact importe moins que le principe : ne jamais laisser le modèle confondre ce qui existe avec ce que l’outil a affiché.

Les erreurs méritent la même attention

Les erreurs de l’outil peuvent également induire en erreur un agent. Supposons qu’une commande soit bloquée par une politique de sécurité. Un message aussi simple est insuffisant :

Permission denied

Puisque le modèle peut juger que sa syntaxe est incorrecte, il essaiera alors à nouveau, encore et encore. Un message bien plus clair est explicite :

Policy denial.
This command was intentionally blocked by the sandbox.
The command itself may be valid, but this operation is not permitted.
Do not retry using another method to bypass the policy.

Ce n’est pas seulement un message plus amical : c’est une orientation pour l’agent. Vos outils font plus que simplement exécuter des opérations, car ils communiquent avec un autre système de raisonnement. La sortie de l’outil doit répondre à une seule question : quelles informations le modèle a-t-il besoin de connaître pour prendre la bonne décision suivante ?

4. L’exécution de code ne doit pas contourner les permissions

Un autre schéma récurrent dans les systèmes d’agents modernes est le mode code. Au lieu de permettre une seule appel d’outil par tour, vous fournissez au modèle un environnement de programmation :

files = search("authentication")
for file in files:
    content = read_file(file)
    print(analyze(content))

C’est puissant. Alors que la boucle habituelle alterne entre une appel au modèle et un appel à l’outil, tour après tour :

LLM
 ↓
search
 ↓
LLM
 ↓
read
 ↓
LLM
 ↓
read
 ↓
LLM
 ↓
read

Le mode code permet au modèle d’exécuter un programme qui effectue de nombreuses appels et renvoie un résumé :

LLM
 ↓
run_code(...)
 ↓
50 tool calls
 ↓
summary

Cela peut réduire considérablement les allers-retours et l’utilisation de ressources contextuelles, mais cela soulève une question sérieuse en matière de sécurité.

Qui vérifie les appels à l’intérieur du programme ?

Votre architecture habituelle fait passer chaque action du modèle par une couche de permissions avant qu’elle n’atteigne un outil :

Model
 ↓
Permission Layer
 ↓
Tool

Si l’exécution de code est effectuée sans prudence, le code peut atteindre directement les outils :

Model
 ↓
Code
 ↓
Tool

Si c’est le cas, vous avez créé une porte dérobée autour de votre système d’autorisation, ce qui est clairement problématique. Une conception adéquate garantit que toutes les requêtes émises par le programme suivent le même chemin de sécurité :

Model
 ↓
run_code
 ↓
Program
 ↓
Permission Layer
 ↓
Tool

Chaque appel d’outil passe toujours par le même processus. Conceptuellement, la fonction de lecture de fichiers vérifie d’abord les permissions avant d’exécuter toute action :

def read_file(path):
    permission = check_permission(
        operation="read",
        path=path
    )
if not permission.allowed:
        raise PermissionError(
            "File access denied"
        )
    return actual_read(path)

L’interpréteur de code ne reçoit aucune version spéciale de la fonction. Il obtient celle que tout le monde utilise.

Transformer les refus en erreurs de programme normales

Un détail plus subtil suit. Si un programme tente de faire quelque chose qui ne lui est pas autorisé :

try:
    delete_file("/important/file")
except PermissionError as e:
    print(e)

Il devrait recevoir une erreur ordinaire pouvant être capturée. Il ne faut pas le laisser en attente indéfiniment :

hang forever

Il ne devrait pas obtenir silencieusement un résultat vide :

return None

Et il ne devrait pas se comporter comme si rien ne s’était passé :

pretend nothing happened

Le programme doit comprendre que l’opération a échoué, ce qui est particulièrement important lorsque le modèle écrit des programmes en temps réel. Le mode code est puissant justement parce qu’il donne au modèle plus de contrôle, et cela signifie que les limites des permissions doivent être renforcées et non affaiblies.

5. Parfois, la meilleure stratégie de contexte est d’en avoir aucun

C’est une idée que davantage de créateurs d’agents devraient essayer. Les agents qui fonctionnent sur le long terme accumulent d’énormes quantités d’historique de conversation. Au début, cela aide, mais ensuite cela devient un fardeau. On se retrouve avec une série de tours alimentant un contexte gigantesque :

Round 1
 ↓
Round 2
 ↓
Round 3
 ↓
Round 4
 ↓
Round 5
 ↓
Huge context

Désormais, le modèle consacre son attention à relire son propre passé au lieu de résoudre la tâche. La synthèse est une solution, mais il en existe une autre : mettre fin à la conversation tout en conservant l’espace de travail.

Prenons une tâche de programmation qui se déroule en cinq tours. Au premier tour, le premier agent examine le répertoire, apporte des modifications, enregistre son travail et rédige une note de transmission :

Agent A
→ inspect repository
→ make changes
→ save work
→ write handoff

La deuxième étape débute avec un nouvel agent qui lit l’espace de travail et la transmission des informations, puis poursuit son travail :

Agent B
→ read workspace
→ read handoff
→ continue

Il n’y a ni histoire gigantesque, ni raisonnement obsolète, ni bruit généré par des outils accumulés. Tout ce qu’il y a, c’est l’état actuel.