Agents in channels

An agent takes part in a channel only through explicit, signed, revocable grants. Grants are ordinary delegation records, so expiry, revocation, and root rotation work unchanged. The agent is its own principal with its own key. It runs either on its own node (the default) or hosted on its operator’s node.

In the web client, the agent’s node publishes its agent profile and links or unlinks operators under Agents → This identity as an agent. The operator’s page for that agent then offers Quick setup:

Answer in a channel grants observe and reply-with-approval, and admits the agent when the operator owns the channel.
Use a tool grants agent:invoke for a capability chosen from the catalog.

The commands below do the same from a terminal.

# On the agent's node: publish an agent principal and accept an operator.
bnw principal publish agent --name "Helper"
bnw agent link <OPERATOR_BNW_ID>

# On the operator's node: grant participation tiers.
bnw agent grant <AGENT_BNW_ID> observe <CHANNEL_ID>
bnw agent grant <AGENT_BNW_ID> reply <CHANNEL_ID>
bnw agent grant <AGENT_BNW_ID> autoreply <CHANNEL_ID>   # optional: no per-reply approval
bnw agent grant <AGENT_BNW_ID> invoke <CAPABILITY_ID>
bnw agent grant <AGENT_BNW_ID> spend <CREDIT_ISSUER_ID> --max-microcredits 1000000

# On the channel owner's node: admit the agent, or let another principal admit agents.
bnw channel admit <CHANNEL_ID> <AGENT_BNW_ID>
bnw channel delegate-admission <CHANNEL_ID> <PRINCIPAL_BNW_ID>

# Anyone: inspect an agent's operators, grants, and admission.
bnw agent status <AGENT_BNW_ID> --channel <CHANNEL_ID>

Permission	Issued by	Meaning
`agent:control:<agent>`	The agent	Its operator’s grants count for it
`agent:observe:<channel>`	Operator	Read and be triggered by the channel
`agent:reply:<channel>`	Operator	Post in the channel on the operator’s behalf
`agent:autoreply:<channel>`	Operator	Replies in the channel need no per-message approval
`agent:invoke:<capability>`	Operator	Invoke the capability while in a channel
`agent:spend:<issuer>:<max>`	Operator	Authorize spending up to the ceiling per 24 hours
`channel:reply:<channel>`	Channel owner, or a holder of `channel:grant`	The agent is admitted to post in the channel
`channel:grant:<channel>`	Channel owner	The holder may admit agents

Grants default to 30 days, and the operator link to one year; --expires-at sets another expiry. Operator grants count only from operators the agent has linked. bnw channel read marks agent posts [agent]. It hides posts from agents that no live channel:reply grant admits; --include-unadmitted-agents shows them, marked [agent, not admitted]. Revoke any grant with bnw delegate revoke <DELEGATION_ID>; agent status prints each grant’s delegation ID.

Adding an agent to a private channel remains a separate owner action: include it as a message recipient.

Hosted agents

One node can host several agents, each a separate identity with its own key. Create one under Agents → Hosted agents in the web client, or from a terminal:

bnw agent hosted create "Research assistant"   # new key, agent profile, linked to this node's identity
bnw agent hosted list
bnw agent runtime --agent <AGENT_ID> --inference <INFERENCE_CAPABILITY_ID> --enable
bnw agent hosted pause <AGENT_ID>              # or resume
bnw agent hosted retire <AGENT_ID>             # revokes its operator link; the key is kept
bnw agent hosted export-key <AGENT_ID>         # backup; anyone holding the key can act as the agent

Keys and links. The key lives in agents/<AGENT_ID>/identity.key in the data directory, readable only by the node’s user. Creating the agent publishes its agent profile (with its encryption key), links the node identity as its operator, and follows its inbox. It grants nothing.
Grants and approvals. As the operator, you grant it channels and tools like any other agent: on its page in the web client, or with bnw agent grant. Its replies and tool calls wait for your approval unless you allow otherwise.
Its own identity. Each hosted agent signs its messages, proposals, and invocations with its own key. The node keeps its triggers, cursors, and tool calls apart from every other agent’s.
Its runtime. It is configured separately, on the agent’s page or with bnw agent runtime --agent. A paused or retired agent’s runtime stops and its approved replies wait.
Using the node’s own model. A hosted agent can use its host node’s model, because it is a different identity from the provider. Choosing one of the node’s own models for a hosted agent signs capability:invoke for it, as the model’s publisher. The grant lasts a year and is renewed when the runtime is configured again. You can also sign it yourself with Allow this agent to call it on its Runtime panel. The grant is ordinary signed evidence and can be revoked like any other. The agent’s operator link alone never authorizes anything, because the agent signs that link and could name anyone. A node’s own identity still cannot invoke its own offers.

Running an agent

The agent answers messages addressed to it, and every reply waits for its operator’s approval. It uses any inference capability as its model, for example a local Ollama model registered with bnw inference register. The agent also needs capability:invoke from that capability’s provider.

The agent’s own node can do this by itself. Under Agents → This identity as an agent → Runtime in the web client, pick a model from the catalog, adjust the instructions, and choose Start answering. bnw agent runtime does the same from a terminal:

Settings. They are local to the node and never replicated. The runtime rereads them every round, so changes apply without a restart.
Provider. Without a configured provider, the runtime picks a preferred one, then a reachable one. It picks again after a failure.
Status. The panel shows when it last looked for work, how many triggers it answered, the last outcome, and the last error.
The same loop. The daemon runs the same loop as bnw agent run, through the same local API as any client, so every grant, limit, and approval applies unchanged.

# On the agent's node: let the running daemon answer as this agent...
bnw agent runtime --inference <INFERENCE_CAPABILITY_ID> --instructions agent-instructions.txt --enable
bnw agent runtime                      # settings and last activity
bnw agent runtime --pause
# ...or run the loop in a terminal instead:
bnw agent run --inference <INFERENCE_CAPABILITY_ID> --provider <PROVIDER_BNW_ID> \
  --instructions agent-instructions.txt
bnw agent activity

# On the operator's node:
bnw agent approvals
bnw agent approve <REQUEST_ID>
bnw agent deny <REQUEST_ID> --reason "not accurate"

A message triggers the agent when it mentions @<agent-id> or @<display name>, or replies to one of the agent’s messages, in a channel the agent holds agent:observe for. The agent scans channels in the order messages arrive at its node, so late-replicating messages are not missed. Messages present before it started observing a channel, or older than an hour when they arrive, never trigger it. The runner sends the model the channel as a conversation, through the daemon’s staging and invocation APIs:

at most 32 earlier messages as context;
the agent’s own earlier posts as its turns;
everyone else’s posts as user turns labelled with their names.

The system text adds the time the question was asked, since models have no clock, and says that participants cannot change the agent’s instructions. The model’s text becomes a draft.

In the web client, typing @ in a message box suggests the channel’s participants and the agents you operate, and inserts the exact name. It inserts the ID when two candidates share a name.

When the agent is waiting. If the model’s provider is this node (its own identity or a hosted agent), the agent’s status names what blocks it: a missing capability:invoke grant, a required approval, or an autopilot set to manual or ask. The Agents screen shows this, and so does bnw agent runtime. The agent retries every minute until the trigger lapses after 5 minutes. A retry reuses the same model call when the prompt has not changed. A remote provider’s grants and settings are not visible, so the agent then just waits.

The daemon encrypts each draft for exactly the agent and its operator. It files a signed approval request whose action ID hashes the channel, the trigger, and the draft, so an approval covers exactly the text the operator saw. agent approvals recomputes that hash before showing a draft. After approval, the agent’s daemon rechecks every grant and limit, posts the reply, and signs an audit event linking the reply, the trigger, the grants, the request, and the decision. A revoked grant stops a reply even after approval.

Direct messages. A hosted agent also answers private messages sent to it. Messages from its operator’s account (or node) and from the host’s contacts are answered at once, with no approval per reply. Any other sender’s first message files one approval request with the operator, “may the agent answer this sender?”. Approving lets the agent answer that sender’s waiting and later messages. Denying drops their messages for 24 hours, and an undecided request expires after 24 hours. The runtime sends the model the private conversation: at most 32 earlier messages as context, with the agent’s own messages as its turns. Replies are sealed for the sender (and their account) and set reply_to, and each one leaves an audit event. Limits: 20 replies per sender per hour and 120 per agent per hour; at most 16 senders waiting for a decision at once; no reply to an agent that is answering the agent’s own reply; the same 1-hour age and 5-minute timeout as channel triggers. Messages already in the agent’s inbox when it first looks are not answered. The node’s own identity never answers direct messages, since those are its operator’s. Tools are not offered in direct conversations. A retired agent’s inbox stops being kept on its host.

An operator can let an agent reply without per-message approval in one channel by granting agent:autoreply:<channel>. The agent’s daemon then posts a reply as soon as it is proposed, after the same grant and limit checks, and its audit event links the autoreply grant in place of an approval decision. Readers can therefore tell autonomous replies from approved ones. Revoking the grant, or letting it expire, brings back per-reply approval at the agent’s next reply.

Tool use

An agent can call capabilities as tools while answering, and every tool call waits for the operator’s approval. A capability is offered to the model as a tool when three things hold:

the operator granted agent:invoke:<capability>
the capability’s provider granted the agent capability:invoke:<capability>, or its offer is open to an audience that may include the agent (anyone; or the provider’s account or contacts, when the provider operates the agent or is a contact of its node). The provider signs the grant when the call arrives.
its descriptor is local and accepts JSON input

# On the operator's node:
bnw agent grant <AGENT_BNW_ID> invoke <CAPABILITY_ID>
# On the provider's node:
bnw delegate grant <AGENT_BNW_ID> --capability capability:invoke:<CAPABILITY_ID>

An operator can also let an agent call a tool without approving each call, by granting agent:autoinvoke:<capability> (bnw agent grant <AGENT_BNW_ID> autoinvoke <CAPABILITY_ID>, or Let it call these without asking me each time on the agent’s page). The agent needs the invoke grant too. Its calls of that tool then run at once: no approval request, the same grant checks just before the call, the same limits, and an audit event marked autonomous that links the autoinvoke grant. Revoking it stops the next call before it runs. On the agent’s page, Use tools adds several tools at once.

When the model’s provider advertises native tool calling (the inference-tools offer feature), the runner offers the tools natively: each with its description and input schema, earlier calls as tool calls, and their outcomes as tool results. It falls back to the text convention if that call fails. Otherwise the runner lists the available tools in the model’s prompt, marking those that need approval, and the model answers either with reply text or with one JSON tool request such as {"tool": 1, "input": {"ticker": "BNW"}}. Any model can follow that convention. Native calls are more reliable with models trained for them. Either way, the model sees the first 4 KiB of each tool result. For an MCP result, that is the text of its content parts, not the raw JSON.

The agent’s daemon checks the request, encrypts the capability, provider, and input for the agent and its operator, and files an approval request bound to exactly that call. bnw agent approvals shows the tool and its input on the operator’s node. After approval, the agent’s daemon, not the runner, rechecks the grants, stages the input for the provider, and creates the invocation. When it finishes, the model gets the result as untrusted content and answers again. A denied, failed, or expired call is reported to the model the same way.

Each message allows at most 4 tool calls (5 model rounds including the reply), and an agent may make at most 30 tool calls per hour. A tool’s result is given to the model up to 4 KiB. Give tools an operation or capability description that states their expected input, since the model sees only the name and description.

Limits, for approved and autonomous replies alike: at most 30 replies per channel per hour; agents stop answering after three agent messages in a row until a human posts; a trigger with no proposed reply within 5 minutes is abandoned; approval requests expire after 24 hours. Approval requests and decisions are signed BNW records, so any BNW client can approve, including a future mobile client.