Agents¶
Les agents sont la couche de logique agentique de Diapason. Ce sont eux qui décident comment une question est traitée — envoyée directement à un modèle, passée dans une boucle d'appel d'outils, raisonnée façon ReAct, exécutée comme du code façon CodeAct, décomposée récursivement, ou confiée à un environnement d'agent externe. Tous les agents implémentent la classe abstraite BaseAgent et sont enregistrés dans l'AgentRegistry.
Vue d'ensemble¶
| Agent | Clé de registre | accepts_tools |
Multi-tours | Description |
|---|---|---|---|---|
SimpleAgent |
simple |
Non | Non | Question-réponse en un seul tour |
OrchestratorAgent |
orchestrator |
Oui | Oui | Boucle d'appel d'outils multi-tours (function_calling + structured) |
NativeReActAgent |
native_react |
Oui | Oui | Boucle Pensée-Action-Observation |
NativeOpenHandsAgent |
native_openhands |
Oui | Oui | Exécution de code façon CodeAct + appels d'outils |
RLMAgent |
rlm |
Oui | Oui | Modèle récursif avec REPL persistant |
OpenHandsAgent |
openhands |
Non | Oui | Enveloppe le vrai openhands-sdk |
ClaudeCodeAgent |
claude_code |
Non | Oui | Claude Agent SDK via un sous-processus Node.js |
OpenCodeAgent |
opencode |
Non | Oui | L'agent de code opencode sur ton moteur local |
OperativeAgent |
operative |
Oui | Oui | Agent planifié persistant, avec gestion d'état |
MonitorOperativeAgent |
monitor_operative |
Oui | Oui | Agent de longue haleine, avec 4 axes de stratégie configurables |
Le persona persistant : SOUL.md, MEMORY.md, USER.md¶
Le prompt système de chaque agent est assemblé au début de la conversation par le SystemPromptBuilder, qui y injecte jusqu'à trois fichiers Markdown facultatifs — le persona persistant. Ce sont des fichiers en texte brut, à toi, que tu modifies, et qui sont chargés au début de chaque conversation. Il n'y a derrière eux ni base vectorielle ni cache d'embeddings.
| Fichier | Ce qu'il contient | Exemple de ligne |
|---|---|---|
SOUL.md |
Comment l'agent doit se comporter — le ton, la longueur, ce sur quoi il doit te contredire | Sois concis. Conteste les hypothèses fragiles. |
MEMORY.md |
Des faits sur toi, tes projets, tes préférences | Je déploie sur Postgres, jamais sur MySQL. |
USER.md |
Qui tu es — ton rôle, ton équipe, ton contexte | Ingénieur back-end chez Acme, dans l'équipe paiements. |
Ce persona est distinct du moteur de mémoire et de sa recherche : le persona est un contexte Markdown toujours actif, chargé dans le prompt, tandis que le moteur de mémoire est un stockage de longue durée, interrogeable, que l'agent consulte à la demande.
Où ils vivent¶
Par défaut, les fichiers sont lus depuis le dossier de configuration :
(Le dossier de configuration respecte $DIAPASON_HOME / $XDG_DATA_HOME quand ils sont définis.) Les chemins se configurent sous [memory_files] :
[memory_files]
soul_path = "~/.diapason/SOUL.md"
memory_path = "~/.diapason/MEMORY.md"
user_path = "~/.diapason/USER.md"
persona_name = "" # persona nommé, facultatif — voir plus bas
Comment ils sont chargés¶
Au début de chaque conversation, SystemPromptBuilder lit chaque fichier en UTF-8 et ajoute son contenu comme une section du prompt système, après le gabarit de l'agent et avant le catalogue de compétences :
- Les trois sont facultatifs. Un fichier absent ou vide est ignoré : n'importe quel sous-ensemble fonctionne, et une installation dépourvue de fichiers de persona se comporte exactement comme avant.
- Les modifications prennent effet à la conversation suivante. Les fichiers sont lus une seule fois, quand le prompt d'une conversation est construit : rien à redémarrer, rien à réindexer — modifie ou supprime une ligne, et elle s'applique dès la prochaine conversation que tu démarres.
- Chaque section est bornée en longueur. Les fichiers sont tronqués selon un budget de caractères par section, pour qu'un gros
MEMORY.mdne puisse pas chasser le reste du prompt.
Les personas nommés¶
Une même installation peut répondre sous plusieurs personas sans toucher à la configuration globale. Un persona nommé vit dans son propre dossier :
~/.diapason/personas/<name>/SOUL.md
~/.diapason/personas/<name>/MEMORY.md
~/.diapason/personas/<name>/USER.md
Choisis-en un à chaque appel, ou renonce complètement :
diapason ask --persona work "résume mes PR ouvertes"
diapason ask --persona none "combien font 2 + 2 ?" # n'injecte aucun persona
Définis persona_name sous [memory_files] pour faire d'un persona nommé celui par défaut. persona_name = "none" (ce qui revient à --persona none) désactive l'injection de persona pour cette exécution.
Les modifier¶
SOUL.md, MEMORY.md et USER.md sont du Markdown ordinaire — ouvre-les dans n'importe quel éditeur. MEMORY.md et USER.md peuvent aussi être mis à jour par l'agent lui-même, par les outils memory_manage et user_profile_manage quand ils sont activés : l'agent peut donc noter un fait nouveau au milieu d'une conversation. Ces outils visent toujours les MEMORY.md et USER.md par défaut (sous ~/.diapason/), jamais les copies d'un persona nommé — celles-là, modifie-les à la main.
BaseAgent ABC¶
Tous les agents dérivent de la classe abstraite BaseAgent.
from abc import ABC, abstractmethod
from diapason.agents._stubs import AgentContext, AgentResult
class BaseAgent(ABC):
agent_id: str
accepts_tools: bool = False
def __init__(
self,
engine: InferenceEngine,
model: str,
*,
bus: Optional[EventBus] = None,
temperature: float = 0.7,
max_tokens: int = 1024,
) -> None: ...
@abstractmethod
def run(
self,
input: str,
context: AgentContext | None = None,
**kwargs,
) -> AgentResult:
"""Exécute l'agent sur l'entrée donnée."""
L'attribut de classe accepts_tools décide si un agent peut recevoir des outils, par --tools en ligne de commande ou par tools= dans le SDK. Les agents dont accepts_tools = False ignorent les arguments d'outils.
BaseAgent fournit aussi des méthodes utilitaires concrètes (_emit_turn_start, _emit_turn_end, _build_messages, _generate, _max_turns_result, _strip_think_tags) dont les sous-classes se servent pour ne pas dupliquer la logique commune. Le détail est dans la documentation d'architecture.
ToolUsingAgent est une classe de base intermédiaire (elle dérive de BaseAgent) qui pose accepts_tools = True et ajoute un ToolExecutor ainsi qu'une limite de boucle max_turns. Tous les agents qui se servent d'outils dérivent de cette classe.
AgentContext¶
Le contexte d'exécution remis à un agent à chaque appel.
| Champ | Type | Description |
|---|---|---|
conversation |
Conversation |
L'historique des messages (pré-rempli avec le contexte si l'injection de mémoire est active) |
tools |
list[str] |
Les noms des outils dont l'agent dispose |
memory_results |
list[Any] |
Les résultats de mémoire récupérés à l'avance |
metadata |
dict[str, Any] |
Des métadonnées libres pour l'exécution |
AgentResult¶
Le résultat rendu quand un agent a fini son exécution.
| Champ | Type | Description |
|---|---|---|
content |
str |
Le texte de la réponse finale |
tool_results |
list[ToolResult] |
Les résultats des outils exécutés pendant l'exécution |
turns |
int |
Le nombre de tours (d'appels d'inférence) effectués |
metadata |
dict[str, Any] |
Des métadonnées libres sur l'exécution |
SimpleAgent¶
Le SimpleAgent est un agent à un seul tour : il envoie la question directement au moteur d'inférence et rend la réponse. Il ne gère pas l'appel d'outils.
Comment il marche :
- Il construit une liste de messages à partir du contexte de conversation (s'il y en a un) et de la question de l'utilisateur.
- Il appelle le moteur d'inférence via
_generate(). - Il rend la réponse sous forme d'
AgentResult, avecturns=1.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Le moteur d'inférence à utiliser |
model |
str |
-- | L'identifiant du modèle |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
temperature |
float |
0.7 |
La température d'échantillonnage |
max_tokens |
int |
1024 |
Le nombre maximum de jetons à produire |
Quand s'en servir : pour de la question-réponse directe, sans appel d'outils ni raisonnement sur plusieurs tours.
OrchestratorAgent¶
L'OrchestratorAgent est un agent multi-tours qui met en œuvre une boucle d'appel d'outils. C'est l'agent principal pour les questions qui demandent un calcul, une recherche de connaissances ou un raisonnement structuré. Il dérive de ToolUsingAgent.
Comment il marche :
- Il construit la liste de messages initiale à partir du contexte et de la question de l'utilisateur.
- Il envoie les messages au moteur, accompagnés des définitions d'outils (au format function-calling d'OpenAI).
- Si le moteur répond avec des
tool_calls, leToolExecutorrépartit chaque appel. - Les résultats d'outils sont ajoutés comme messages
TOOL, et la boucle continue. - Si aucun
tool_callsn'est rendu, la réponse est tenue pour la réponse finale. - La boucle s'arrête après
max_turnsitérations (10 par défaut) et rend le contenu disponible, assorti du drapeau de métadonnéemax_turns_exceeded.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Le moteur d'inférence à utiliser |
model |
str |
-- | L'identifiant du modèle |
tools |
list[BaseTool] |
[] |
Les instances d'outils à mettre à disposition |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
max_turns |
int |
10 |
Le nombre maximum de tours d'appel d'outils |
temperature |
float |
0.7 |
La température d'échantillonnage |
max_tokens |
int |
1024 |
Le nombre maximum de jetons à produire |
mode |
str |
"function_calling" |
Le mode d'appel d'outils (function_calling ou structured) |
system_prompt |
str |
None |
Un prompt système personnalisé |
Quand s'en servir : pour les questions qui demandent un calcul, une recherche en mémoire, des appels à un sous-modèle, la lecture de fichiers ou un raisonnement en plusieurs étapes.
La boucle d'appel d'outils
L'orchestrateur suit la convention function-calling d'OpenAI. Pour que la boucle s'enclenche, le moteur doit savoir renvoyer des tool_calls dans sa réponse. Si des outils sont fournis mais que le moteur ne renvoie aucun appel d'outil, l'agent se comporte comme un agent à un seul tour.
NativeReActAgent¶
Le NativeReActAgent met en œuvre une boucle Pensée-Action-Observation, suivant le motif ReAct. Il demande au modèle de produire une sortie structurée (Thought:, Action:, Action Input:, Final Answer:) et analyse la réponse pour déclencher l'exécution des outils. Il dérive de ToolUsingAgent.
Comment il marche :
- Il construit un prompt système avec des descriptions d'outils enrichies (noms, schémas de paramètres, catégories) via
build_tool_descriptions(). L'analyse ne tient pas compte de la casse. - Il produit une réponse et analyse la sortie structurée ReAct.
- S'il y trouve un
Final Answer:, il le rend. - S'il y trouve une
Action:, il exécute l'outil et réinjecte le résultat commeObservation:. - Il boucle jusqu'à ce qu'une réponse finale soit produite, ou que
max_turnssoit dépassé.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Le moteur d'inférence à utiliser |
model |
str |
-- | L'identifiant du modèle |
tools |
list[BaseTool] |
[] |
Les instances d'outils à mettre à disposition |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
max_turns |
int |
10 |
Le nombre maximum de tours de raisonnement |
temperature |
float |
0.7 |
La température d'échantillonnage |
max_tokens |
int |
1024 |
Le nombre maximum de jetons à produire |
Quand s'en servir : pour les questions qui gagnent à un raisonnement explicite, étape par étape, avec usage d'outils — quand tu veux voir le cheminement de pensée de l'agent.
Compatibilité ascendante
L'alias de registre "react" pointe vers NativeReActAgent. L'ancien import from diapason.agents.react import ReActAgent fonctionne encore.
NativeOpenHandsAgent¶
Le NativeOpenHandsAgent est un agent façon CodeAct : il produit et exécute du code Python, à côté d'appels d'outils structurés. Il peut aussi aller chercher à l'avance le contenu des URL présentes dans l'entrée de l'utilisateur, pour donner au modèle un contexte direct. Il dérive de ToolUsingAgent.
Comment il marche :
- Il construit un prompt système détaillé, avec des descriptions d'outils enrichies (via le constructeur partagé
build_tool_descriptions()) et des instructions d'exécution de code. - Il va chercher à l'avance les URL présentes dans l'entrée de l'utilisateur, et en insère le contenu directement.
- À chaque tour, il produit une réponse et tente d'en extraire des blocs de code ou des appels d'outils.
- Le code est exécuté par
code_interpreter; les appels d'outils sont répartis parToolExecutor. - S'il ne trouve ni l'un ni l'autre, il rend le contenu comme réponse finale.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Le moteur d'inférence à utiliser |
model |
str |
-- | L'identifiant du modèle |
tools |
list[BaseTool] |
[] |
Les instances d'outils à mettre à disposition |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
max_turns |
int |
3 |
Le nombre maximum de tours |
temperature |
float |
0.7 |
La température d'échantillonnage |
max_tokens |
int |
2048 |
Le nombre maximum de jetons à produire |
Quand s'en servir : pour les questions qui portent sur le contenu d'une URL, pour de l'exécution de code, ou pour les tâches où le modèle peut écrire et lancer du Python afin de résoudre le problème.
RLMAgent¶
Le RLMAgent met en œuvre la décomposition récursive au moyen d'un REPL persistant, d'après l'article RLM. Le contexte est rangé dans une variable Python plutôt qu'injecté dans le prompt, ce qui permet de traiter des entrées de longueur quelconque par des appels récursifs à un sous-modèle. Il dérive de ToolUsingAgent.
Comment il marche :
- Il crée un REPL persistant, doté des rappels
llm_query()etllm_batch(). - Il injecte le contexte venu d'
AgentContextdans le REPL, sous forme de variable. - Il produit du code et l'exécute dans le REPL.
- Si
FINAL(value)est appelé, il rend cette valeur comme réponse finale. - S'il ne trouve aucun bloc de code, il traite le contenu comme une réponse textuelle directe.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Le moteur d'inférence à utiliser |
model |
str |
-- | L'identifiant du modèle |
tools |
list[BaseTool] |
[] |
Les instances d'outils (facultatif) |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
max_turns |
int |
10 |
Le nombre maximum de tours d'exécution de code |
temperature |
float |
0.7 |
La température d'échantillonnage |
max_tokens |
int |
2048 |
Le nombre maximum de jetons à produire |
sub_model |
str |
identique à model |
Le modèle des appels au sous-modèle |
sub_temperature |
float |
0.3 |
La température des appels au sous-modèle |
sub_max_tokens |
int |
1024 |
Les jetons maximum des appels au sous-modèle |
max_output_chars |
int |
10000 |
Le nombre maximum de caractères en sortie du REPL |
system_prompt |
str |
RLM_SYSTEM_PROMPT |
Remplace le prompt système |
Quand s'en servir : pour les tâches à long contexte qui gagnent à une décomposition récursive — résumer de gros documents, traiter des données structurées, ou tout ce qui demande de manipuler le contexte par programme.
OpenHandsAgent (SDK)¶
L'OpenHandsAgent enveloppe le vrai paquet openhands-sdk, pour du développement logiciel piloté par l'IA. Il dérive directement de BaseAgent (la gestion des outils est assurée en interne par le SDK).
Comment il marche :
- Il importe
openhands.sdkà l'exécution. - Il crée un LLM, un Agent et une Conversation issus du SDK.
- Il envoie l'entrée et déroule la conversation.
- Il rend le contenu du message final.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Le moteur d'inférence (solution de repli) |
model |
str |
-- | L'identifiant du modèle |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
temperature |
float |
0.7 |
La température d'échantillonnage |
max_tokens |
int |
1024 |
Le nombre maximum de jetons à produire |
workspace |
str |
os.getcwd() |
Le dossier de travail de l'agent |
api_key |
str |
$LLM_API_KEY |
La clé d'API du fournisseur de LLM |
Quand s'en servir : pour les tâches de développement logiciel (débogage, édition de code, réparation de tests) où le SDK OpenHands fournit un environnement d'agent de développement complet.
Dépendance facultative
Nécessite openhands-sdk (uv sync --extra openhands) et Python 3.12 ou plus.
Se servir des agents¶
En ligne de commande¶
# L'agent simple
diapason ask --agent simple "Quelle est la capitale de la France ?"
# L'orchestrateur, avec des outils
diapason ask --agent orchestrator --tools calculator,think "Combien vaut sqrt(256) ?"
# NativeReActAgent
diapason ask --agent native_react --tools calculator "Combien font 2+2 ?"
# L'alias ReAct (identique à native_react)
diapason ask --agent react --tools calculator,think "Résous étape par étape : 15 % de 340"
# NativeOpenHandsAgent
diapason ask --agent native_openhands --tools calculator,web_search "Résume example.com"
# RLMAgent
diapason ask --agent rlm "Résume ce long document"
# L'agent OpenHands (SDK)
diapason ask --agent openhands "Corrige le bug dans test_utils.py"
Par le SDK Python¶
from diapason import Diapason
j = Diapason()
# L'agent simple
response = j.ask("Bonjour", agent="simple")
# L'orchestrateur, avec des outils
response = j.ask(
"Calcule 15 % de 340",
agent="orchestrator",
tools=["calculator"],
)
# NativeReActAgent, avec des outils
response = j.ask(
"Combien vaut sqrt(256) ?",
agent="native_react",
tools=["calculator", "think"],
)
# Le résultat complet, avec le détail des outils
result = j.ask_full(
"Quelle est la racine carrée de 144 ?",
agent="orchestrator",
tools=["calculator", "think"],
)
print(result["content"])
print(result["turns"])
print(result["tool_results"])
j.close()
ClaudeCodeAgent¶
Le ClaudeCodeAgent enveloppe le SDK @anthropic-ai/claude-code par un pont vers un sous-processus Node.js livré avec Diapason. Contrairement aux autres agents, l'inférence est entièrement prise en charge par le Claude Agent SDK — le paramètre engine n'est accepté que pour respecter l'interface de BaseAgent, et il n'est pas utilisé.
Ce qu'il faut
Nécessite Node.js 22 ou plus dans le PATH, et une variable d'environnement ANTHROPIC_API_KEY (ou passe api_key= directement). Le lanceur livré avec Diapason s'installe tout seul dans ~/.diapason/claude_code_runner/ au premier usage, par npm install.
Comment il marche :
- Au premier appel, il copie le
claude_code_runner/livré avec Diapason vers~/.diapason/claude_code_runner/et lancenpm install --productionsinode_modulesmanque. - Il construit une charge utile de requête JSON (prompt, clé d'API, espace de travail, outils autorisés, prompt système, identifiant de session) et l'envoie sur le
stdind'un sous-processusnode dist/index.js. - Le lanceur Node.js appelle le Claude Agent SDK et écrit sur
stdoutdu JSON délimité par des sentinelles. - Côté Python, la sortie comprise entre les marqueurs
---DIAPASON_OUTPUT_START---et---DIAPASON_OUTPUT_END---est analysée : contenu, résultats d'outils et métadonnées en sont extraits. - Il rend un
AgentResultavecturns=1.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Accepté pour respecter l'interface ; non utilisé |
model |
str |
-- | Accepté pour respecter l'interface ; non utilisé |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
temperature |
float |
0.7 |
Accepté pour respecter l'interface ; non utilisé |
max_tokens |
int |
1024 |
Accepté pour respecter l'interface ; non utilisé |
api_key |
str |
$ANTHROPIC_API_KEY |
La clé d'API Anthropic |
workspace |
str |
os.getcwd() |
Le dossier de travail de l'agent Claude |
session_id |
str |
"" |
Un identifiant de session facultatif, pour la continuité de la conversation |
allowed_tools |
list[str] |
None (tous) |
Les noms des outils Claude Code à autoriser |
system_prompt |
str |
"" |
Un prompt système supplémentaire pour l'agent |
timeout |
int |
300 |
Le délai d'attente du sous-processus, en secondes |
Quand s'en servir : pour les tâches de génie logiciel où les outils intégrés du Claude Agent SDK (édition de code, exécution shell, opérations sur les fichiers) offrent des capacités que les agents à outils de Diapason n'ont pas.
from diapason.agents.claude_code import ClaudeCodeAgent
agent = ClaudeCodeAgent(
engine=None, # non utilisé
model="", # non utilisé
workspace="/path/to/project",
allowed_tools=["Read", "Write", "Bash"],
timeout=120,
)
result = agent.run("Ajoute des annotations de type à toutes les fonctions de utils.py")
print(result.content)
# En ligne de commande
diapason ask --agent claude_code "Refactorise les tests pour qu'ils utilisent des fixtures pytest"
accepts_tools = False
Le ClaudeCodeAgent n'accepte pas les outils Diapason par --tools. L'accès aux outils de l'agent Claude se règle à part, par le paramètre de constructeur allowed_tools, qui transmet des noms d'outils compris par le Claude Agent SDK lui-même.
OpenCodeAgent¶
L'OpenCodeAgent délègue les tâches de code à opencode, l'agent de code open-source, en le faisant tourner sur ton moteur local. opencode s'occupe de la boucle agentique, des modifications de fichiers et de l'usage des outils ; Diapason fournit le modèle — le travail d'agent de code reste ainsi local d'abord.
Ce qu'il faut
Nécessite le binaire opencode dans le PATH (npm i -g opencode-ai ou brew install anomalyco/tap/opencode). Il n'est pas livré avec Diapason ; run() rend une erreur claire s'il manque. Aucune ANTHROPIC_API_KEY n'est nécessaire — l'inférence passe par ton moteur Diapason.
Comment il marche :
- Il déduit du
engineune URL de base compatible OpenAI (Ollama, vLLM ou llama.cpp à<host>/v1, par exemple) et écrit dans l'espace de travail unopencode.jsonqui l'enregistre comme fournisseur@ai-sdk/openai-compatible(diapason/<model>). - Il lance un
opencode servesans interface (en boucle locale, sur un port tiré au hasard) et attend/global/health. - Il crée une session (
POST /session) et envoie la tâche (POST /session/{id}/message) avecmodel={providerID, modelID}et l'agentchoisi (buildouplan). - Il analyse les
partsdu message rendu — les parties texte verscontent, les parties outil verstool_results— pour en faire unAgentResult. close()libère la session et le serveur.
Paramètres du constructeur (une sélection) :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Sert à déduire l'URL du fournisseur local compatible OpenAI |
model |
str |
-- | L'identifiant du modèle servi par le fournisseur (qwen3:8b, par exemple) |
workspace |
str |
os.getcwd() |
Le dossier dans lequel opencode travaille |
agent |
str |
"build" |
L'agent opencode : build (accès complet) ou plan (lecture seule) |
provider_base_url |
str |
déduite | Remplace l'URL de base OpenAI déduite du moteur |
provider_id |
str |
"diapason" |
L'identifiant de fournisseur opencode à enregistrer et utiliser |
model_id |
str |
model |
L'identifiant du modèle chez le fournisseur |
server_password |
str |
$OPENCODE_SERVER_PASSWORD |
Une authentification basique facultative pour le serveur opencode |
timeout |
int |
600 |
Le délai d'attente HTTP, en secondes |
from diapason.agents.opencode import OpenCodeAgent
agent = OpenCodeAgent(engine, "qwen3:8b", workspace="/path/to/project", agent="build")
result = agent.run("Ajoute des annotations de type à utils.py et lance les tests")
print(result.content)
agent.close()
# En ligne de commande (opencode doit être installé)
diapason ask --agent opencode "Refactorise le parseur pour qu'il utilise une machine à états"
Les fournisseurs traversants
Si aucune URL de base ne peut être déduite du engine, passe model sous la forme provider/model (ollama/llama3, par exemple) : opencode le résout depuis sa propre configuration, et aucun opencode.json n'est écrit.
La capacité du modèle compte
La boucle agentique d'opencode (planifier, appeler correctement les outils, mener à terme plusieurs étapes) demande un modèle raisonnablement capable. À l'essai, un modèle local 27B (Qwen3.5-27B servi par vLLM) a résolu proprement une suite de 7 tâches de code (création, modification, correction de bug, implémentation jusqu'à faire passer les tests, multi-fichiers — vérifié en lançant le code et les tests). Un modèle 8B (qwen3:8b) s'est montré peu fiable : appels d'outils mal formés, code syntaxiquement cassé, tâches à moitié faites. Pour du vrai travail de code, préfère un modèle local capable (ou un modèle distant).
OperativeAgent¶
L'OperativeAgent est un agent autonome, persistant et planifié, avec persistance de session et rappel d'état intégrés. Il est conçu pour les « opérateurs » — des agents autonomes qui tournent à intervalles réguliers, avec gestion automatique de l'état d'un battement à l'autre. Il dérive de ToolUsingAgent.
Comment il marche :
- Chargement de la session — il restaure l'historique de conversation des battements précédents depuis le magasin de sessions.
- Rappel d'état — il récupère le JSON d'état précédent depuis le moteur de mémoire.
- Injection du prompt système — il injecte les instructions de protocole de l'opérateur.
- Boucle d'outils — la boucle function-calling standard (la même que celle de l'OrchestratorAgent).
- Enregistrement de la session — il consigne le prompt et la réponse du battement dans le magasin de sessions.
- Persistance de l'état — il enregistre l'état automatiquement si l'agent ne l'a pas fait explicitement via l'outil
memory_store.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Le moteur d'inférence à utiliser |
model |
str |
-- | L'identifiant du modèle |
tools |
list[BaseTool] |
[] |
Les instances d'outils à mettre à disposition |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
max_turns |
int |
20 |
Le nombre maximum de tours d'appel d'outils |
temperature |
float |
0.3 |
La température d'échantillonnage |
max_tokens |
int |
2048 |
Le nombre maximum de jetons à produire |
system_prompt |
str |
None |
Un prompt système personnalisé pour l'opérateur |
operator_id |
str |
None |
L'identifiant unique pour la persistance de la session et de l'état |
session_store |
Any |
None |
Le magasin de sessions pour l'historique de conversation |
memory_backend |
Any |
None |
Le moteur de mémoire pour le rappel et la persistance de l'état |
Quand s'en servir : pour les agents autonomes qui tournent à intervalles réguliers (via TaskScheduler, par exemple) et doivent garder un état entre deux appels. L'agent gère tout seul l'historique de session et la persistance de l'état d'un battement à l'autre.
from diapason.agents.operative import OperativeAgent
agent = OperativeAgent(
engine,
model="qwen3:8b",
tools=[...],
operator_id="daily-report",
session_store=session_store,
memory_backend=memory_backend,
system_prompt="Tu es un agent de rapport quotidien. Rassemble et résume l'actualité.",
)
result = agent.run("Produis le rapport du jour")
MonitorOperativeAgent¶
Le MonitorOperativeAgent est un agent de longue haleine, doté de quatre axes de stratégie configurables pour gérer l'information d'un tour et d'une session à l'autre. Il étend ToolUsingAgent avec une compression des observations, une extraction en mémoire, une récupération et une décomposition des tâches, toutes pilotées par la stratégie. Il hérite aussi de la persistance d'état entre sessions du motif OperativeAgent.
Les axes de stratégie :
| Axe | Valeurs admises | Défaut | Description |
|---|---|---|---|
memory_extraction |
causality_graph, scratchpad, structured_json, none |
causality_graph |
Comment les constats sont consignés en mémoire |
observation_compression |
summarize, truncate, none |
summarize |
Comment les sorties d'outils sont compressées avant d'entrer dans le contexte |
retrieval_strategy |
hybrid_with_self_eval, keyword, semantic, none |
hybrid_with_self_eval |
Comment le contexte antérieur est rappelé au début de chaque exécution |
task_decomposition |
phased, monolithic, hierarchical |
phased |
Comment les tâches complexes sont découpées |
Comment il marche :
- Il construit un prompt système avec la configuration de stratégie et les descriptions d'outils.
- Il rappelle l'état précédent depuis le moteur de mémoire.
- Il charge l'historique de session des battements précédents.
- Il déroule une boucle d'outils function-calling, en appliquant les stratégies configurées :
- Compression des observations : les longues sorties d'outils sont résumées (par le modèle) ou tronquées avant d'entrer dans le contexte de messages.
- Extraction en mémoire : après chaque appel d'outil, les constats sont extraits et rangés selon la stratégie de mémoire (relations causales, notes de brouillon, ou JSON structuré).
- Il enregistre la session et consigne l'état automatiquement.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
engine |
InferenceEngine |
-- | Le moteur d'inférence à utiliser |
model |
str |
-- | L'identifiant du modèle |
tools |
list[BaseTool] |
[] |
Les instances d'outils à mettre à disposition |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
max_turns |
int |
25 |
Le nombre maximum de tours d'appel d'outils |
temperature |
float |
0.3 |
La température d'échantillonnage |
max_tokens |
int |
4096 |
Le nombre maximum de jetons à produire |
system_prompt |
str |
None |
Un prompt système personnalisé (remplace celui par défaut) |
memory_extraction |
str |
"causality_graph" |
La stratégie d'extraction en mémoire |
observation_compression |
str |
"summarize" |
La stratégie de compression des observations |
retrieval_strategy |
str |
"hybrid_with_self_eval" |
La stratégie de récupération |
task_decomposition |
str |
"phased" |
La stratégie de décomposition des tâches |
operator_id |
str |
None |
L'identifiant unique pour la persistance de la session et de l'état |
session_store |
Any |
None |
Le magasin de sessions pour l'historique de conversation |
memory_backend |
Any |
None |
Le moteur de mémoire pour la persistance de l'état et des constats |
Quand s'en servir : pour l'évaluation sur des bancs d'essai de longue haleine et les tâches complexes en plusieurs étapes, qui gagnent à des stratégies configurables de gestion de la mémoire, de compression du contexte et de décomposition des tâches. Particulièrement utile sur des bancs comme GAIA, FRAMES et LifelongAgent, où le choix de stratégie pèse sur les résultats.
from diapason.agents.monitor_operative import MonitorOperativeAgent
agent = MonitorOperativeAgent(
engine,
model="qwen3:8b",
tools=[...],
operator_id="research-agent",
memory_extraction="causality_graph",
observation_compression="summarize",
retrieval_strategy="hybrid_with_self_eval",
task_decomposition="phased",
session_store=session_store,
memory_backend=memory_backend,
)
result = agent.run("Cherche la cause première de la panne en production")
# En ligne de commande
diapason ask --agent monitor_operative "Analyse les constats de l'audit de sécurité"
SandboxedAgent¶
Le SandboxedAgent est une enveloppe transparente qui exécute n'importe quel BaseAgent à l'intérieur d'un conteneur Docker (ou Podman). Il suit le même motif d'enveloppe que GuardrailsEngine — la configuration de l'agent interne est sérialisée et envoyée sur le stdin du conteneur, et le résultat est relu sur son stdout.
Voir aussi la référence ContainerRunner plus bas, qui gère le cycle de vie du conteneur.
Comment il marche :
- Il construit une charge utile JSON avec le prompt, l'identifiant de l'agent enveloppé et le modèle.
- Il appelle
ContainerRunner.run(), qui démarre un conteneur avec--network noneet--rm, écrit la charge utile sur stdin et attend une sortie JSON sur stdout. - Les chemins montés sont confrontés à une liste blanche configurable avant que le conteneur ne démarre.
- Il analyse la sortie délimitée par des sentinelles et rend un
AgentResult.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
agent |
BaseAgent |
-- | L'agent enveloppé, à exécuter dans le conteneur |
runner |
ContainerRunner |
-- | Le lanceur de conteneur qui gère le cycle de vie Docker |
engine |
InferenceEngine |
None |
Remplace le moteur (par défaut, celui de l'agent enveloppé) |
model |
str |
"" |
Remplace le modèle (par défaut, celui de l'agent enveloppé) |
workspace |
str |
"" |
Le dossier de travail à l'intérieur du conteneur |
mounts |
list[str] |
[] |
Les chemins de l'hôte à monter (en lecture seule) |
secrets |
dict[str, str] |
{} |
Injectés dans la charge utile (pas dans les variables d'environnement) |
bus |
EventBus |
None |
Le bus d'événements pour la télémétrie |
from diapason.sandbox import ContainerRunner, SandboxedAgent
from diapason.agents.simple import SimpleAgent
runner = ContainerRunner(
image="diapason-sandbox:latest",
timeout=60,
mount_allowlist_path="/etc/diapason/mount_allowlist.json",
)
inner = SimpleAgent(engine, model="qwen3:8b")
agent = SandboxedAgent(
agent=inner,
runner=runner,
mounts=["/home/user/data"],
)
result = agent.run("Résume les fichiers CSV de /home/user/data")
ContainerRunner¶
Le ContainerRunner gère le cycle de vie du conteneur Docker (ou Podman) pour l'exécution en bac à sable. Le SandboxedAgent s'en sert directement, mais il s'utilise aussi tout seul.
Paramètres du constructeur :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
image |
str |
"diapason-sandbox:latest" |
L'image Docker à lancer |
timeout |
int |
300 |
La durée maximale d'exécution du conteneur, en secondes |
mount_allowlist_path |
str |
"" |
Le chemin du fichier JSON de liste blanche des montages |
max_concurrent |
int |
5 |
Le nombre maximum de conteneurs simultanés (indicatif) |
runtime |
str |
"docker" |
Le binaire d'exécution de conteneurs (docker ou podman) |
Format de la liste blanche des montages :
{
"roots": [
{"path": "/home/user/projects", "read_only": false},
{"path": "/data/shared", "read_only": true}
],
"blocked_patterns": [".ssh", ".env", "*.pem", "*.key"]
}
Si mount_allowlist_path n'est pas défini, aucune restriction de racine n'est appliquée. Les motifs bloqués comprennent toujours, par défaut, .ssh, .env, *.pem, *.key, les fichiers d'identifiants et les dossiers de configuration des services cloud.
Docker est nécessaire
Le ContainerRunner lève une RuntimeError si le moteur d'exécution configuré (docker ou podman) est introuvable dans le PATH.
L'enregistrement des agents¶
Les agents s'enregistrent par le décorateur @AgentRegistry.register(), ce qui les rend trouvables par leur nom à l'exécution :
from diapason.core.registry import AgentRegistry
# Vérifier qu'un agent est enregistré
AgentRegistry.contains("orchestrator") # True
# Récupérer la classe de l'agent
agent_cls = AgentRegistry.get("orchestrator")
# Lister toutes les clés d'agents enregistrées
AgentRegistry.keys()
# ["simple", "orchestrator", "native_react", "react", "native_openhands",
# "rlm", "openhands", "claude_code", "operative", "monitor_operative"]
L'intégration au bus d'événements¶
Tous les agents publient des événements sur l'EventBus quand un bus leur est fourni :
| Événement | Quand |
|---|---|
AGENT_TURN_START |
Au début d'une exécution (via _emit_turn_start) |
AGENT_TURN_END |
À la fin d'une exécution (via _emit_turn_end) |
TOOL_CALL_START |
Avant chaque exécution d'outil (sous-classes de ToolUsingAgent) |
TOOL_CALL_END |
Après chaque exécution d'outil (sous-classes de ToolUsingAgent) |
Les événements d'inférence
Les événements INFERENCE_START / INFERENCE_END sont publiés par l'enveloppe InstrumentedEngine, pas par les agents eux-mêmes. La télémétrie reste ainsi facultative et transparente pour le code des agents.
Ces événements permettent aux systèmes de télémétrie et de traces d'enregistrer automatiquement le détail des interactions.
Le flux des agents gérés¶
L'API des agents gérés (/v1/managed-agents/{id}/messages) sait diffuser les vrais jetons du modèle au fil de l'eau, par SSE. Envoie un message avec stream: true pour recevoir les jetons de la réponse à mesure qu'ils sont produits, au lieu d'attendre la réponse entière.
Comment ça marche¶
Le point d'entrée de diffusion appelle directement engine.stream_full(), qui produit des objets StreamChunk contenant des jetons de contenu, des fragments d'appels d'outils et des motifs de fin. C'est un vrai flux jeton par jeton venu du modèle — pas un rejeu mot à mot après coup.
Pour les agents multi-tours qui appellent des outils, la boucle de diffusion, d'elle-même :
- Transmet les jetons de contenu au client à mesure qu'ils arrivent.
- Accumule les fragments d'appels d'outils (OpenAI les envoie par morceaux).
- Exécute les outils dès réception de
finish_reason="tool_calls". - Émet les résultats d'outils sous forme d'événements SSE nommés (
event: tool_result). - Réinjecte les résultats dans le modèle pour le tour suivant.
- Recommence jusqu'à ce que le modèle produise une réponse textuelle finale, ou que
max_turnssoit atteint.
Diffuser des messages¶
curl -N -X POST http://localhost:8000/v1/managed-agents/{id}/messages \
-H "Content-Type: application/json" \
-d '{"content": "Combien font 2+2 ?", "stream": true}'
La réponse suit le format SSE d'OpenAI :
- Les morceaux de contenu —
data: {"choices": [{"delta": {"content": "token"}}]} - Les appels d'outils (si le modèle demande à se servir d'un outil) —
event: tool_calls\ndata: {"calls": [{"tool_name": "...", "arguments": "..."}]} - Les résultats d'outils —
event: tool_result\ndata: {"tool_name": "...", "output": "..."} - Le morceau final —
data: {"choices": [{"delta": {}, "finish_reason": "stop"}]} - La sentinelle de fin —
data: [DONE]
Avec stream: false (le défaut), le point d'entrée se comporte exactement comme avant — le message est mis en file, et l'agent doit être déclenché à part, par /run.
Le détail du comportement¶
- Le message de l'utilisateur est toujours rangé en base avant que la diffusion commence.
- Une fois la diffusion terminée, la réponse complète ainsi rassemblée est consignée comme message
agent_to_user. - L'historique des messages précédents est chargé automatiquement comme contexte du modèle.
- C'est la méthode
stream_full()du moteur qui assure le vrai flux de jetons. Les moteurs qui ne la redéfinissent pas retombent sur l'implémentation par défaut, laquelle enveloppe la méthodestream()ordinaire. - Si le moteur n'est pas disponible sur le serveur, une erreur
503est rendue. - Pendant la diffusion, l'exécution des outils passe par le
ToolRegistrypour trouver et instancier les outils.