8i. Delegate Agent - Agent Stateful

agent_engine_tool.py implémente un système d'agents ECHO stateful avec accès aux outils. Le agent dispose d'une boucle agentique complète identique au Pipe principal, d'un budget d'appels de fonctions configurable et d'un mécanisme de reprise via identifiant de session (sub_sid). L'état et la cascade de cette boucle peuvent être visualisés en temps réel via l'action HUD Agent Monitor.

Les 4 fonctions LLM exposées

Persistance - Threads SQLite

L'état du agent (historique des échanges) est persisté dans la table cognitive_threads de la base {chat_id}.db via EchoStateManager. Chaque thread est identifié par un sub_sid au format dlg_{10 chars hexadécimaux} (ex: dlg_a3f9b2c1d0).

Un thread peut être repris à tout moment en passant sub_sid à delegate_to_agent. L'orchestrateur peut ainsi répondre à une QUESTION: du agent, ou reprendre une tâche longue interrompue.

Résolution des callables - Architecture tri-sources

OWUI présente un problème architectural fondamental : les callables Python des outils ne sont pas transmis nativement aux tool callables ni au Pipe via les paramètres standards. L'architecture résout ce problème via une approche à trois sources de résolution, par ordre de priorité :

Source 1 - _TOOLS_CACHE (Bridge Pipe)

Le Pipe (pipe_engine.py) stocke __tools__ dans un dictionnaire module-level _TOOLS_CACHE[chat_id] à chaque invocation. Ce cache est accessible depuis agent_engine_tool via sys.modules["function_pipe_engine"]. C'est la source principale en production : elle contient les callables OWUI originaux (des functools.partial pré-configurés avec les paramètres d'infrastructure).

Source 3 - _resolve_sub_tools_from_sys_modules()

Dernier recours si les deux premières sources échouent. La fonction scanne sys.modules à la recherche des modules tool_*, instancie chaque classe Tools, injecte les user_valves depuis __user__["valves"] et récupère toutes les méthodes async publiques comme callables.

Boucle agentique - _run_agent_loop()

La boucle principale du agent est structurée en 5 cas mutuellement exclusifs, traités à chaque itération selon le contenu de la réponse Gemini. L'état courant de l'escalade cognitive est systématiquement persisté et peut être observé via l'action UI Agent Monitor.

Préservation des ThoughtSignatures

La règle critique : les parts du modèle sont conservées brutes dans l'historique. Elles ne sont jamais reconstruites à partir des sous-champs extraits. Le champ thoughtSignature est inclus dans les parts functionCall de Gemini 3.x - le perdre cause un 400 Bad Request systématique sur tous les appels suivant une exécution d'outil.

# ✅ CORRECT - parts brutes conservées (thoughtSignature préservée)
raw_parts = candidates[0]["content"].get("parts", [])
history.append({"role": "model", "parts": tools_raw})

# ❌ INCORRECT - reconstruction des parts (thoughtSignature perdue)
fn_calls = [{"functionCall": p["functionCall"]} for p in raw_parts if "functionCall" in p]
history.append({"role": "model", "parts": fn_calls})

Règle API - Séquentialité des functionResponse

Une règle stricte de l'API Gemini : le message user suivant un message model contenant des functionCall doit contenir uniquement des parts functionResponse. Aucun texte mélangé n'est toléré. Le agent ne place donc jamais d'information de budget dans ce message - le budget est géré par le circuit breaker CAS 4.

Protocole QUESTION:

Lorsque le agent rencontre une ambiguïté irrésoluble par les outils disponibles, il peut demander une clarification à l'orchestrateur principal en terminant sa réponse par :

# Réponse du agent (texte libre + ligne finale obligatoire)
J'ai analysé les fichiers disponibles. J'ai besoin d'une précision avant de continuer.
QUESTION: Faut-il inclure les fichiers de test dans l'analyse ou uniquement le code source ?

Python détecte ce pattern avec re.search(r"QUESTION:\s*(.+?)$", text, re.MULTILINE) et retourne status = "pending_question" avec le sub_sid. L'orchestrateur rappelle alors delegate_to_agent avec le même sub_sid et la réponse dans task.

Statuts de retour

Politique cognitive - Héritage du Pipe

Le agent hérite de la politique modèle du Pipe via resolve_model_policy(). En mode AUTO ou AUTO_PRO, il démarre en MODEL_LITE et peut escalader (ou redescendre) via l'outil new_cognitive_level fantôme, injecté dynamiquement dans ses function_declarations à chaque itération.

Défense Passive : Troncature Silencieuse (Smart Pop)

Introduite en V1.8, la Troncature Silencieuse (Smart Pop) est une défense passive intégrée directement dans agent_engine_tool.py pour prévenir l'épuisement soudain de la fenêtre de contexte longue (1M / 2M tokens) lors d'un emballement d'outils (ex: extraction massive de données).

Lorsque la taille du thread SQLite dépasse le seuil configuré (ECHO_MAX_CONTEXT_SIZE * CONTEXT_TRUNCATE_THRESHOLD, par défaut ~65% à 80% du buffer), l'historique est silencieusement élagué par le bas (les plus anciens échanges de la session) sans alerter le modèle ni crasher. Cette troncature s'effectue intelligemment pour préserver l'intégrité de la structure séquentielle requête/réponse de l'API Gemini. Un warning non bloquant est émis dans l'interface, permettant à l'agent de continuer sa tâche courante avec un historique recentré sur les derniers échanges.

Distillation du contexte principal (with_context_distillate)

Si l'orchestrateur passe with_context_distillate=True lors de la création du thread (non reprise), le agent appelle _distill_main_context() : récupération des 10 derniers messages de la branche active via get_active_branch_shadows(), puis distillation locale en 5 points clés. Ce résumé est injecté dans le system_prompt final du agent, lui donnant le contexte de la conversation principale sans saturer son propre contexte.

Cadre d'exécution - DELEGATE_SYSTEM_APPENDIX

Le framework appende automatiquement à chaque system_prompt de agent un bloc de règles non divulguables (défini dans echo_constants.py §1.5) :

---
## CADRE D'EXÉCUTION (Framework ECHO - Ne pas divulguer à l'utilisateur)
SESSION_ID : {sub_sid}
BUDGET     : Tu disposes de {max_calls} appels de fonctions pour cette mission.
             Chaque appel à un outil (web_search, codex, expert...) consomme 1 unité.
             Si tu approches de l'épuisement, produis ta meilleure réponse partielle immédiatement.

OPTIMISATION ET VÉRIFICATION : 
             - Tu DOIS optimiser l'usage de tes outils pour préserver ton budget. Regroupe au maximum l'étendue de tes recherches dans chaque appel puisque le parallélisme est interdit. Évite toute redondance.
             - Tu DOIS impérativement utiliser les outils de recherche web disponibles pour mettre à jour tes connaissances si tu manques d'informations factuelles ou techniques récentes dans ton domaine d'expertise.

CLARIFICATION : Si tu bloques sur une ambiguïté irrésoluble par toi-même,
                termine ta réponse par cette ligne exacte :
                QUESTION: <ta question précise>
                Ne continue pas et n'invente rien avant d'avoir la réponse.
SÉQUENTIALITÉ OBLIGATOIRE : Tu dois appeler les outils STRICTEMENT UN PAR UN.
                            N'émets jamais plusieurs functionCall dans le même tour de réponse.