Aller au contenu

Docs · Internals

Quatre façons de lancer un agent, une seule suite de tests

Le SDK nexus livre quatre adaptateurs derrière le contrat d'agent : Claude Code, un harnais natif sur tout endpoint compatible OpenAI, Codex et un client ACP générique. Cette page montre en quoi ils diffèrent et comment une suite de conformité les garde honnêtes.

Ce que ça fait

claude_code enveloppe le CLI Claude Code. native fait tourner sa propre boucle d'outils sur un endpoint de modèle en HTTP. codex pilote codex app-server. acp parle l'Agent Client Protocol à tout agent que tu peux lancer.

Chaque adaptateur est compilé derrière sa propre feature cargo (provider-native, provider-codex, provider-acp). Seul claude_code est toujours construit.

La même suite de conformité et la même suite de sécurité sont rejouées contre chaque adaptateur, avec des faux exécutables à la place des vrais services.

Le schéma

Les quatre adaptateurs de provider et leur banc de testSchéma de flux. Le contrat d'agent est implémenté par quatre adaptateurs : claude_code, native, codex et acp. claude_code parle à la ligne de commande claude, native à un endpoint chat completions compatible OpenAI, codex à codex app-server et acp à n'importe quel agent ACP. Les processus de native, Codex et ACP sont lancés par un lanceur unique à l'environnement en liste blanche. Un banc de test contient une suite de conformité de 25 scénarios, une suite de sécurité de 5 scénarios, des faux exécutables et un provider scripté en mémoire ; les suites sont rejouées contre les adaptateurs.implemented byMCP stdio serversstand in forreplayed againstreplayed againstAgent contractAgentProvider, AgentSession, AgentEventtransport::spawn::isolated_commandsingle launcher under providers/ (checked by a test):allow-listed environment, process group,no secret on argvclaude_code (always compiled)ClaudeCodeProvider, facade on InteractiveClientoptional remote instance over SSHnative (feature provider-native)NativeProvider: tool loop, MCP tools only, budgetson a ModelEndpoint: HTTP + SSE, quirks, price tablecodex (feature provider-codex)codex app-server, JSON-RPC over stdioone process per sessionacp (feature provider-acp)generic Agent Client Protocol clientone process per sessionclaude CLIstream-jsonOpenAI-compatible/chat/completionscodex app-serverany ACP agent(command in config)Conformance suite25 scenarios, same suite for every providerabsent capability: its fallback is checkedSecurity suite, 5 mandatory scenariosunknown policy refused, env isolation,no secret on argv, no credential in errors,tool outside profile refusedFake executablesfake_claude, fake_openai + fake_mcp,fake_codex, fake_acpScriptedProviderin-memory provider, replays transcripts

Fais glisser pour te déplacer. Pince, Ctrl + molette ou les touches + et - pour zoomer ; flèches pour bouger ; 0 ou double-clic pour ajuster. Choisis un nœud pour allumer ses liens.

DézoomerZoomerPlein écran
Redessiné depuis le diagramme vérifié nexus-agent-providers (vérifié 2026-10-06). Les libellés sont les noms utilisés dans le code.
Description textuelle du schéma

Schéma de flux. Le contrat d'agent est implémenté par quatre adaptateurs : claude_code, native, codex et acp. claude_code parle à la ligne de commande claude, native à un endpoint chat completions compatible OpenAI, codex à codex app-server et acp à n'importe quel agent ACP. Les processus de native, Codex et ACP sont lancés par un lanceur unique à l'environnement en liste blanche. Un banc de test contient une suite de conformité de 25 scénarios, une suite de sécurité de 5 scénarios, des faux exécutables et un provider scripté en mémoire ; les suites sont rejouées contre les adaptateurs.

Lecture guidée

  1. Étape 1. claude_code

    ClaudeCodeProvider est une façade sur le client interactif. Une pompe par session lit les messages et les demandes de contrôle, les projette en événements et les route vers le tour actif ou vers le canal hors tour. Une instance peut aussi lancer le même flux par SSH. Les fonctions qui exigent la machine locale (un serveur MCP par session, des dossiers locaux, un mode sans confirmation) sont refusées plutôt qu'ignorées.

  2. Étape 2. native

    NativeProvider compose un endpoint de modèle avec une boucle d'outils : un tour est plusieurs allers-retours modèle et outils, les appels d'outils parallèles s'exécutent en concurrence, et des budgets bornent le tour. Les outils viennent uniquement de serveurs MCP.

  3. Étape 3. L'endpoint de modèle

    OpenAiEndpoint parle chat completions en HTTP et en server-sent events. Les particularités des serveurs (DeepSeek, Ollama, vLLM, llama-server, NIM) sont des drapeaux et des préréglages. Une sonde d'appel d'outil vérifie un modèle avant usage, et la table de prix ne renvoie rien plutôt que 0 quand un prix est inconnu. Les URL d'endpoint sont validées : https hors boucle locale, pas d'identifiants dans l'URL, plages d'adresses internes refusées après résolution DNS, pas de redirection.

  4. Étape 4. codex et acp

    CodexProvider pilote codex app-server en JSON-RPC sur stdio, un processus par session. AcpProvider est un client générique de l'Agent Client Protocol dont la commande vient de la configuration. Les deux démarrent par le lanceur unique : environnement en liste blanche, groupe de processus, aucun secret en ligne de commande. Fermer une session tue le processus et ses descendants.

  5. Étape 5. La suite de conformité

    La suite pilote une session à travers 25 scénarios et vérifie les invariants du flux. Quand un provider n'a pas une capacité, le scénario n'est pas sauté : le repli écrit est vérifié. Une capacité déclarée mais jamais mise en scène est refusée.

  6. Étape 6. La suite de sécurité

    Cinq scénarios obligatoires qu'aucune capacité ne peut désactiver : une politique inconnue est refusée, l'environnement est isolé, aucun secret n'atteint la ligne de commande, les erreurs ne portent aucun identifiant, et un outil hors profil est refusé.

  7. Étape 7. Les faux d'abord

    Chaque adaptateur est construit contre un faux exécutable (fake_claude, fake_openai avec fake_mcp, fake_codex, fake_acp). Pour Codex et ACP, les faux suivent un schéma et des transcriptions tirés de la documentation publique des protocoles.

Pourquoi c'est conçu ainsi

Le faux est la spécification

Un nouveau provider livre un faux exécutable et une transcription avant tout code de transport : le comportement attendu est écrit sous une forme qui s'exécute.

Un seul lanceur

Un test cherche dans les sources tout lancement direct de processus sous le dossier des providers et échoue s'il en trouve un : un nouvel adaptateur ne peut pas contourner les règles d'isolation.

La suite de sécurité a trouvé de vrais défauts

Son premier passage a montré Codex et ACP démarrant sans dossier personnel dédié, et un affichage de débogage de la configuration qui imprimait des variables d'environnement. Les deux ont été corrigés.

Les adaptateurs tiers restent derrière une porte

Ils sont désactivés par défaut et n'ajoutent aucune dépendance. Le registre refuse toute instance tierce tant que l'hôte n'a pas attesté la porte de sécurité, ce qui ne se défait pas une fois fait.

Ce qui n'est pas établi

  • Aucun vrai Codex, aucun vrai agent ACP et aucun vrai endpoint de modèle n'a été exercé par ces suites : chacun n'est vu qu'à travers son faux exécutable. L'adaptateur Codex exige codex app-server 0.130.0 ou plus récent.