3.7 KiB
Protocole d’outils agent V1
Statut : CURRENT local de laboratoire pour le poste Web local. Il ne livre ni modèle local, ni autonomie générale, ni processus d’outil supplémentaire.
Frontière
WorkspaceServer possède un AgentGateway Python éphémère et un agent de
démonstration déterministe, distinct de tout futur LLM. Le gateway ne lit pas
SQLite, ne lance ni shell ni processus et ne possède aucun stockage durable.
Il délègue exclusivement aux projections et commandes métier existantes.
Le catalogue backend inclut investigation.search, graph.get_node,
graph.get_neighbors, evidence.get_summary, evidence.read_excerpt,
provenance.trace, jobs.get, research.get_state et research.prepare.
Chaque outil expose tool_id, versions d’outil/capability, description,
schéma d’entrée, contrat de sortie, classes d’action/risque/coût, contact réseau,
besoin d’autorisation et disponibilité réelle. L’interface ne déduit jamais ces
attributs elle-même.
Les snapshots et le flux de recherche existants restent les sources de vérité. Le résultat mémoire du gateway est seulement une réponse de transport, jamais une projection métier parallèle.
HTTP, turns et sécurité
Les routes sont GET /api/v1/agent-tools/catalog,
POST /api/v1/agent-tools/turns, POST /api/v1/agent-tools/calls,
POST /api/v1/agent-tools/turns/{turn_id}/resume,
GET /api/v1/agent-tools/results/{result_id} et
GET /api/v1/agent-tools/events?cursor={sequence}.
Elles exigent le Host exact et la session locale ; les mutations exigent aussi
Origin, CSRF et le garde-fou de fréquence. Les résultats/événements sont isolés
par instance et workspace. Chaque call transporte turn_id, call_id,
tool_id, input, context, object_refs et idempotency_key ; call_id
et result_id sont deux UUID distincts. Un rejeu identique est idempotent,
une même clé avec une intention différente répond 409.
Résultats, événements et autorisation
Les résultats structurés utilisent COMPLETED, FAILED, DENIED,
AUTHORIZATION_REQUIRED, UNAVAILABLE et, pour un futur contrat annulable,
CANCELLED. Ils contiennent object_refs, artifacts, observations,
provenance_refs et un diagnostic borné plutôt qu’un gros contenu copié.
Le polling HTTP publie agent.turn.started, agent.plan.updated,
agent.tool.requested, agent.tool.started, agent.tool.completed,
agent.authorization.required, agent.turn.completed et agent.error.
Chaque événement porte séquence, horodatage, turn, call éventuel, références et
payload borné. L’UI rend les contenus non fiables avec textContent et peut
mettre en évidence des objets existants sans créer de nœud autoritatif.
L’agent déterministe livré réalise réellement :
USER → AGENT → PLAN → TOOL_REQUEST → TOOL_RESULT → AUTHORIZATION_REQUIRED → RESULT.
Il lit progressivement l’enquête puis appelle research.prepare. Cette étape
ne crée ni grant, ni campagne, ni contact réseau. Après la décision humaine
persistée et la campagne admise par le flux existant, l’UI demande la reprise du
même turn ; le gateway relit l’état puis publie le bilan. L’agent ne possède
aucune voie d’auto-autorisation.
Une instance conserve au plus 64 appels/résultats de 256 Kio et 128 événements, avec éviction FIFO ; toute cette mémoire disparaît à l’arrêt. Il n’existe pas de SSE opérationnel pour ce protocole.
Le runtime modèle local V1 s’ajoute au-dessus
du gateway sans modifier ses neuf outils ni sa policy. Il est CURRENT local
après validation fake OpenAI-compatible ; Qwen réel, resource governor
AMD/RAM/swap et stockage durable des conversations restent TARGET.