Aller au contenu

Docs · Internals

Un contrat pour tous les agents de code

Project Orchestrator joint Claude Code, un modèle compatible OpenAI, Codex ou n'importe quel agent ACP par le même petit jeu de types. Cette page parcourt ce contrat, qui vit dans le SDK nexus.

Ce que ça fait

Le backend ne parle jamais le protocole d'un fournisseur. Il ouvre une session sur un provider et lit un flux d'événements neutres.

Chaque provider déclare ce qu'il sait faire, modèle par modèle. Quand une capacité manque, le contrat applique un repli écrit ou répond Unsupported, jamais un succès silencieux.

Les permissions, les erreurs et les jetons de reprise ont aussi une forme neutre : le tableau de bord montre les mêmes cartes quel que soit l'agent dessous.

Le schéma

Le contrat d'agent dans le SDK nexusSchéma de flux. Le ChatManager du backend demande un provider au ProviderRegistry. Le registre garde les fournisseurs de modèle à part des harnais et vérifie la paire avant tout lancement. Un AgentProvider ouvre ou reprend une AgentSession. La session produit des AgentEvent, applique une ToolPolicy et signale des ProviderError. Le provider expose des Capabilities par modèle et la session peut émettre un ResumeToken. En bas, les anciens types du client Claude Code sont rattachés aux types neutres.open / resume(ResumeToken)CHAT_PROVIDERArc dyn AgentSessionwrapped byClaudeCodeProvidergeneralised intomapped toconverted toChatManager(backend)ProviderRegistryone registry, instance id to providerconfig carries no secret: vault: | env: | noneModel provider, kept apartanthropic_messages | openai_chat | openai_responsesopen_session(harness, spec)pair checked before any launchelse model_protocol_mismatchAgentProviderid, kind, health, catalog,capabilities(model), open, resumeAgentSessionsend_turn, answer_permission, answer_question,interrupt(scope), cancel_tools(scope),set_model, set_policy_mode, out_of_band, closeAgentEvent17 variants, one terminal event:Done | ErrorToolPolicymode + allow + denydeny always winsCapabilitiesper model, 18 fields,a written fallback for eachResumeTokenopaque kind, version, dataProviderError17 kinds, retryable(),details redactedInteractiveClientMessage / ContentBlockPermissionModeSdkError

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-contract (vérifié 2026-10-05). Les libellés sont les noms utilisés dans le code.
Description textuelle du schéma

Schéma de flux. Le ChatManager du backend demande un provider au ProviderRegistry. Le registre garde les fournisseurs de modèle à part des harnais et vérifie la paire avant tout lancement. Un AgentProvider ouvre ou reprend une AgentSession. La session produit des AgentEvent, applique une ToolPolicy et signale des ProviderError. Le provider expose des Capabilities par modèle et la session peut émettre un ResumeToken. En bas, les anciens types du client Claude Code sont rattachés aux types neutres.

Lecture guidée

  1. Étape 1. Un seul registre

    Un unique ProviderRegistry dans nexus associe un identifiant d'instance à un AgentProvider, construit à la demande et mis en cache. La configuration d'une instance ne contient aucun secret, seulement une référence : vault:nom, env:VAR ou none. L'instance claude-code intégrée ne peut pas être supprimée, et une configuration modifiée se recharge sans perturber les sessions déjà ouvertes.

  2. Étape 2. Harnais et modèle sont appariés, et la paire est vérifiée

    Un fournisseur de modèle est gardé à part du harnais. Avant tout lancement, open_session vérifie que le harnais consomme le protocole que parle le fournisseur de modèle (anthropic_messages, openai_chat ou openai_responses). Une paire incompatible est refusée avec model_protocol_mismatch.

  3. Étape 3. AgentProvider

    Un provider expose son identifiant et son genre, un contrôle de santé qui renvoie une valeur au lieu d'échouer, le catalogue de modèles, les capacités d'un modèle donné, et open ou resume pour créer une session.

  4. Étape 4. AgentSession

    Une session mène la conversation : send_turn, answer_permission, answer_question, interrupt et cancel_tools avec une portée, set_model, set_policy_mode, out_of_band et close. Un tour se termine par exactement un événement terminal, Done ou Error.

  5. Étape 5. Les types neutres

    AgentEvent a 17 variantes. ToolPolicy combine un mode avec des listes allow et deny, et deny l'emporte. Capabilities a 18 champs par modèle, chacun avec un repli écrit. Un ResumeToken est opaque pour tout sauf le provider qui l'a émis. ProviderError a 17 genres ; chacun sait s'il peut être réessayé, et ses détails sont expurgés.

  6. Étape 6. Ce que le contrat enveloppe

    Les boîtes de gauche sont le code qui existait avant : le client Claude Code, ses messages, ses modes de permission et ses erreurs. Chacune est rattachée à un type neutre, c'est ainsi que le premier provider a été écrit sans changer ce que reçoit le tableau de bord.

Pourquoi c'est conçu ainsi

Refuser plutôt que faire semblant

Une capacité absente renvoie Unsupported ou applique le repli écrit. Un provider qui ne sait pas annuler des outils le dit. Le contrat ne déclare jamais un succès qui n'a pas eu lieu.

Deny l'emporte, et une règle mal formée est une erreur

Dans une ToolPolicy, un deny l'emporte toujours sur un allow. Un motif mal formé ou un mode inconnu échoue à la construction : une règle deny perdue en silence élargirait la politique.

Une version testable

CONTRACT_VERSION monte dès qu'une forme sérialisée ou une signature de trait change. Les instantanés JSON des tests portent la version : changer une forme sans la faire monter casse le build. La constante vaut 3 aujourd'hui, et les montées jusqu'ici étaient additives.

Aucun secret dans la configuration

La configuration ne porte que des références. Le résolveur d'identifiants transforme vault:nom en secret au dernier moment. Un coffre verrouillé répond credentials_locked au lieu de basculer sur un autre provider, et les messages d'erreur ne répètent jamais un identifiant.

Un tour à la fois

send_turn pendant un tour actif renvoie turn_in_progress. Pas de file cachée, pas d'interruption implicite : la file d'attente reste dans le backend.

Ce qui n'est pas établi

  • Le lien modèle-harnais n'est pas appliqué à Codex (sa configuration de fournisseur personnalisé n'a pas été vérifiée contre un vrai app-server) ni à ACP (l'agent choisit son modèle). Aucune vraie passerelle tierce n'a été essayée.