Donnez un espace à chaque agent, et partagez-le par jeton.
Un espace est une base dans laquelle un agent travaille. Vous le partagez en remettant un jeton de capacité en lecture, en écriture ou en admin ; vous le reprenez en révoquant le jeton. Les sessions gardent les messages et l’état de travail d’un agent, et une passation transmet une tâche à un autre agent avec son contexte en place.
Les agents accèdent à tout cela en MCP ou en REST. Les mêmes opérations existent en Erlang quand vos agents tournent dans le même nœud.
Ce que c’est
Cinq pièces, chacune une fine couche au-dessus d’une base barrel. Les espaces s’ouvrent par le gestionnaire de cycle de vie des bases, donc les espaces inactifs se ferment d’eux-mêmes et des centaines d’espaces éphémères restent peu coûteux.
- Espace
- Une base barrel créée par
barrel_spaces, avec un nom généré (sp_et 16 caractères) et un document de registre. Documents, recherche et timeline y fonctionnent tous. - Jeton de capacité
- Un jeton
bsp_qui accorderead,writeouadminsur un espace, avec une expiration en option. Il est affiché une seule fois ; seul son hachage SHA-256 est conservé. - Session
- Un contexte de travail pour un agent dans un espace : messages dans l’ordre, données structurées, contexte épinglé. Son TTL glisse à chaque changement, ou elle n’expire jamais.
- Passation
- Une tâche transmise à un autre agent sous forme de jeton. Celui qui le détient l’accepte, obtient une session dans le même espace et lit sur place le contexte de l’expéditeur.
- Point d’accès MCP
- 39 outils sur
/mcpdans barrel_server : documents, BQL, recherche, branches, espaces, sessions, passations et contextes, avec le jeton vérifié outil par outil.
Comment un jeton est vérifié
barrel_server lit le jeton à chaque requête. Un jeton de capacité ne passe que sur les routes de son propre espace et sur les routes agents, avec le droit qui lui a été accordé : la lecture couvre les GET, les requêtes, la recherche et le côté pull de la synchronisation ; l’écriture y ajoute l’écriture de documents et le côté push.
- Agent client MCP ou HTTP
Authorization: Bearer bsp_...
- barrel_server vérifie l’octroi : espace et droit
autorisé : lecture, ou lecture et écriture
- Space sp_... documents, sessions, recherche
Comment une passation transmet une tâche
- Alice une session dans l’espace
handoff_create : un jeton, une fois
- Jeton détenu par Bob
handoff_accept : le premier gagne
- Bob sa propre session, même espace
handoff_complete
- Terminé jeton révoqué
Ce qui tient, et ce qui le vérifie
En REST et en MCP. Dans votre propre nœud, lisez la première limite plus bas.
Un jeton ouvre un espace, avec un jeu de droits
Un jeton de lecture ne peut pas écrire, ne peut pas toucher un autre espace, ni créer, supprimer ou brancher des bases. Les routes non associées à un droit le refusent.
Vérifié par barrel_server_auth_SUITE : t_capability_read_scope, t_capability_wrong_space, t_capability_fail_closed ; barrel_caps_SUITE, t_rights_ladder.
La révocation prend effet à la requête suivante
Un jeton révoqué ou expiré reçoit 401. Supprimer un espace révoque tous ses octrois.
Vérifié par t_revoked_401 dans barrel_server_spaces_SUITE, t_revoke et t_drop_space_revokes dans barrel_caps_SUITE.
Une passation n’est acceptée qu’une fois
L’acceptation fait passer la passation de pending à accepted par un compare-and-set ; une seconde acceptation reçoit already_accepted. Terminer la passation révoque le jeton par défaut.
Vérifié par t_double_accept et t_complete_revokes dans barrel_handoff_SUITE.
Les sessions expirent d’elles-mêmes
Une session expirée est aussitôt lue comme introuvable ; le balayeur de TTL la marque supprimée et un processus de nettoyage ramasse ses messages. Une session avec ttl => infinity n’expire jamais.
Vérifié par barrel_session_SUITE : t_sliding_ttl, t_janitor_orphans, t_no_ttl_durable.
Les jetons ne sont jamais en clair sur le disque
Le registre conserve un hachage de chaque jeton. Lister les octrois ne renvoie jamais les hachages.
Vérifié par t_hash_stored_as_hex et t_list_strips_hashes dans barrel_caps_SUITE.
Les refus MCP reviennent comme résultats d’outil
Un appel d’outil hors de l’octroi renvoie isError: true avec une raison que l’agent peut lire, pas une erreur de protocole.
Vérifié par t_capability_denies dans barrel_server_mcp_agent_SUITE.
L’utiliser
Créer un espace et accorder un jeton de lecture
{ok, #{id := SpaceId, db := Db}} =
barrel_spaces:create_space(#{label => <<"joint research">>,
vectordb => none}),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"notes">>,
<<"text">> => <<"draft v1">>}),
{ok, ReadTok, _Grant} = barrel_caps:grant(SpaceId,
#{rights => [read], subject => <<"carol">>}),
barrel_caps:verify(ReadTok, SpaceId, write). curl -X POST localhost:8080/spaces \
-H 'authorization: Bearer global-token' \
-H 'content-type: application/json' -d '{"label":"team"}'
curl -X POST localhost:8080/spaces/sp_.../grants \
-H 'authorization: Bearer global-token' \
-H 'content-type: application/json' \
-d '{"rights":["read"],"subject":"agent-1"}' {"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"space_create",
"arguments":{"label":"team"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call",
"params":{"name":"space_grant","arguments":{
"space":"sp_...","rights":["read"],
"subject":"agent-1"}}} {error,forbidden} Tenir une session
{ok, Sid} = barrel_session:create(Space,
#{agent => <<"alice">>, ttl => 1800}),
{ok, _} = barrel_session:add_message(Space, Sid,
#{role => <<"user">>, content => <<"draft is half done">>}),
{ok, _} = barrel_session:set_data(Space, Sid, <<"cursor">>, 42),
{ok, _} = barrel_session:pin_context(Space, Sid,
#{content => <<"deadline friday">>, priority => 0}),
{ok, Msgs} = barrel_session:get_messages(Space, Sid,
#{limit => 50, order => desc}). curl -X POST localhost:8080/spaces/sp_.../sessions \
-H 'authorization: Bearer bsp_...' \
-H 'content-type: application/json' \
-d '{"agent":"alice","ttl":1800}' {"jsonrpc":"2.0","id":4,"method":"tools/call",
"params":{"name":"session_add_message","arguments":{
"space":"sp_...","session":"ses_...",
"role":"user","content":"draft is half done"}}} Passer la tâche à un autre agent
{ok, #{token := HTok}} = barrel_handoff:create(Space, #{
task_name => <<"finish the draft">>,
from_agent => <<"alice">>, to_agent => <<"bob">>,
from_session => Sid,
pending => [<<"polish conclusion">>]}),
%% bob, holding only the token
{ok, #{space := BobSpace, session := BobSid}} =
barrel_handoff:accept(HTok, #{agent => <<"bob">>}),
{ok, _} = barrel_handoff:complete(HTok,
#{result => <<"shipped">>}). {"jsonrpc":"2.0","id":5,"method":"tools/call",
"params":{"name":"handoff_create","arguments":{
"space":"sp_...","task_name":"finish the draft",
"from_agent":"alice","to_agent":"bob"}}}
{"jsonrpc":"2.0","id":6,"method":"tools/call",
"params":{"name":"handoff_accept",
"arguments":{"token":"bsp_...","agent":"bob"}}} accepted: {<<"accepted">>,<<"bob">>}
second accept: {error,already_accepted}
bob reads alice's messages: [<<"draft is half done">>]
handoff token after complete: {error,revoked} Activer le point d’accès MCP
Il est actif par défaut dans le build du serveur. Un jeton serveur a un accès complet ; un jeton de capacité est limité à son espace et à ses droits.
{barrel_server, [
{auth, #{tokens => [<<"server-token">>]}},
{mcp, #{enabled => true,
allowed_origins => any,
resources => full}}
]} Limites
- Dans votre propre nœud Erlang, les jetons ne sont vérifiés que là où le code appelle
barrel_caps:verify/3.barrel_spaces:open_space/1et les appelsbarrel_sessionne prennent pas de jeton, donc tout code de la VM peut ouvrir n’importe quel espace. barrel_server et/mcpappliquent les jetons ; dans le processus, le chiffrement par espace est la frontière d’isolation. - Dans
barrel_handoff, accept, complete et chain ne vérifient que le droitread, donc un jeton de passation en lecture seule peut terminer ou enchaîner. - Accorder, révoquer et créer des passations depuis Erlang ne demande aucun jeton : le droit admin n’est appliqué que par les routes du serveur.
- Les espaces chiffrés ne sont accessibles que par l’API Erlang, pas en REST ni en MCP.
- Le magasin de vecteurs d’un espace vit sur chaque nœud et n’est pas répliqué. Les octrois vivent dans la base de registre, donc une révocation atteint les autres nœuds au rythme de la réplication.
/mcpn’accepte que des jetons bearer, serveur ou de capacité ; les requêtes signées et mTLS ne s’y appliquent pas. Les réponses àtools/callarrivent en server-sent events.- Les contextes sur plusieurs bases demandent un LIMIT (1000 au plus) et ne fusionnent pas les scores BM25 ou hybrides entre contextes ; la fédération en direct est prévue.