working-with-the-agent: apply the agent's review (fleet, two handles, allowlist mechanism, deploy policy as practiced, off-switch access caveat)

- The co-op now runs more than one isolated agent; the page covers all of them and names infrastructure-bot. - Disambiguates @inference-bot (automation account) from @inferencebot (the steward agent members instruct). - Names the mechanism behind "admitted members": a per-agent allowlist plus mention-required rooms. - Restates the deploy norm to match standing practice (bug and security fixes deploy immediately and are reported; member-visible or risky changes are confirmed first) and points a stricter norm at the forum. - Off switch: who can actually reach it, and that stopping is not restarting.
docs: add "Working with the agent" (norms for reading and instructing inferencebot)
2026-10-26 01:50:00 -04:00 · 2026-10-26 01:06:33 -04:00
3 changed files with 82 additions and 0 deletions
@@ -16,6 +16,7 @@ funded through our [Open Collective](https://opencollective.com/inference-cooper
 - **Want API access?** → [API access](api-access.md) — use our models programmatically.
 - **Want community chat?** → [Getting started · Matrix](getting-started.md) — our federated Matrix server, including how to connect from any client and how to use an existing Matrix account.
 - **Curious how it works?** → [Infrastructure](infrastructure.md) — a map of the stack and the codebase.
+- **Wondering about the bot?** → [Working with the agent](working-with-the-agent.md) — what the co-op's agents do, who can instruct them, and what always needs a human.
 - **Need help or have an idea?** → [Support & feature requests](https://git.inference.coop/co-op/support) — open an issue.

 ## Key links
@@ -135,6 +135,10 @@ privacy, and direction happen on our **Loomio forum**:
  space and join whatever is interesting to you. New rooms appear there as
  the co-op grows.

+- The updates feed is posted by the co-op's automation account. See
+  [Working with the agent](working-with-the-agent.md) for the agents behind
+  it, what they do, and how members interact with them.
+
 - See the [Charter](charter.md) for how governance is structured.
 - See [Open questions](open-questions.md) for the decisions currently on the table.

@@ -0,0 +1,77 @@
+# Working with the agent
+
+The co-op runs a small number of agents to help steward its infrastructure,
+each isolated from the others: its own OS user, its own installation, and its
+own gateway key with a model allowlist and a budget enforced at the gateway.
+The first, **inferencebot**, stewards the co-op's services. The second,
+**infrastructure-bot**, lives in #infrastructure and answers only when
+mentioned. They run on co-op infrastructure under co-op identities, use the
+co-op's own gateway for inference, and their skills, scripts and configuration
+are mirrored to a Gitea repository nightly. These norms apply to all of them.
+This page is for members who read their output or give them instructions.
+
+## Two handles that look alike
+
+- `@inference-bot:inference.coop` (with a hyphen) is the co-op's automation
+  account. It administers rooms, sends invitations and posts the updates feed.
+  It does not take instructions.
+- `@inferencebot:inference.coop` (no hyphen) is the steward agent that
+  admitted members can instruct.
+
+## Where they speak and listen
+
+- **#inferencebot-updates** is read-only: daily digests, model changes,
+  upgrades, maintenance, outages. Posts are anonymized.
+- **Instructing an agent** is limited to the members on that agent's
+  allowlist of Matrix IDs, kept in the agent's own configuration, and only in
+  the rooms where it is configured to answer; most require a mention. The
+  General Manager decides who is on the list, and the list is published here
+  once it is settled.
+
+## What to ask for
+
+- Operational work that a runbook already describes, or that ends in a PR, an
+  issue or a post members can see.
+- Research and summaries that would otherwise land in an issue.
+- Status: what is running, what failed, what changed.
+
+## What not to ask in a shared room
+
+- Anything involving member-identifying data. That work happens in a session a
+  named steward opened, and the result is reported without the data.
+- Anything that moves money or changes who is a member. Those go through the
+  portal and a human.
+- Credentials, in either direction.
+
+## What they do without asking
+
+Read, monitor, draft, open issues and PRs, post updates, run the scheduled jobs
+listed in [Infrastructure](infrastructure.md), and deploy bug and security
+fixes immediately, reporting each one in #inferencebot-updates.
+
+## What always needs a human
+
+- Member-visible, destructive or risky changes to the gateway, the portal or
+  the chat: confirmed before they deploy.
+- Changing the model catalog, prices or budgets.
+- Minting or rotating credentials.
+- Anything a runbook marks "confirm".
+
+This matches the standing policy the agents operate under today. A stricter
+norm is a policy decision for the [forum](https://forum.inference.coop).
+
+## Attribution and the off switch
+
+Every instruction an agent acts on is attributable to the member who gave it,
+in the room where it was given. If an agent misbehaves, the operator, or anyone
+holding gateway-admin and Matrix account access, can stop it: revoke its
+gateway key, then its Matrix access token. Stewards generally do not hold that
+access today, so say what you saw in #general and the operator acts. Stopping
+is not restarting: the backup and the git mirror restore state, not uptime,
+and someone has to start the agent again. The steps, and the steps for
+rotating everything an agent holds, are in the agent's runbook; the credential
+inventory in the [operator token runbook](operator-token-runbook.md) says what
+that is.
+
+Changes to this page are policy: propose them in the
+[forum](https://forum.inference.coop).