36 lines
2 KiB
Markdown
36 lines
2 KiB
Markdown
# Agent roster and privileges
|
|
|
|
Agents are a **flat set**: no agent manages another by position. The
|
|
`manage_root_agent` permission is the one grant that reaches another agent.
|
|
|
|
## Who is on the roster
|
|
|
|
The swarm decides. An agent exists in the swarm if and only if it has an identity
|
|
in the swarm's authelia identity store, which `swarmctl agent create` or the
|
|
swarm UI writes once. `GET /api/agents` on the swarm controller lists them.
|
|
|
|
Each hive also keeps a small file of its own, `topology.json`, with the agents
|
|
this hive has state or config for. You never edit it: the hive rebuilds it from
|
|
what it sees locally, so a hand edit is overwritten, and one that doesn't parse
|
|
stops the rebuild until you fix it. It matters for one thing, covered next.
|
|
|
|
## Who may reach whose state
|
|
|
|
An agent holding no permission sees its own directories and nothing else. An
|
|
agent holding `manage_root_agent` gets every other agent's `state` directory on
|
|
this hive mounted read-write at `/agents/<name>/state`, never `config` or
|
|
`harness`. It's the only grant that reaches another agent's state. Ruth, the
|
|
root agent, holds it, and the swarm UI's setup assistant creates her from the
|
|
[`ruth` archetype](../swarm/archetypes.md#the-built-in-archetypes), which grants it and sets her model to `sonnet`. A ruth created before the archetype keeps her model; set `sonnet` in her inference settings in the swarm UI if wanted. The
|
|
mounts follow the roster: an empty file means no mounts until the next rebuild.
|
|
|
|
## The manager is a normal agent
|
|
|
|
`ruth` differs from other agents in her name and in that grant. You create her
|
|
like any other agent, from the swarm UI or `swarmctl agent create`; the hive
|
|
creates nothing at boot. Her permissions, prompt and tools work as for every
|
|
agent, and destroying her is as final as for any other.
|
|
|
|
How the hive reads and rebuilds the file, the wire protocol and the prompt blocks:
|
|
[`roster.md`](../../4-implementation/agent-state/roster.md). The operator/agent
|
|
trust boundary is a separate axis: [`boundary.md`](../hives/boundary.md).
|