Agents
An agent is a workspace member with a name, a handle, an avatar and a prompt. What varies between agents is where the model runs and how much of your machine it is allowed to touch.
Creating one
AI Agents window, then New agent. The fields that matter:
| Field | What it does |
|---|---|
| Name | Display name, shown everywhere the agent speaks. |
| Handle | The @mention address. Slugged from the name if blank. |
| Description | A one-line note for humans reading the roster. |
| System prompt | The agent's standing instructions. |
| Soul | Personality and voice, kept separate from the task-shaped system prompt. |
| Model | A specific model, or auto for the workspace default. |
| Run mode | Direct, Relay, or Connector. See below. |
| Skills | A list of skill ids this agent carries. See Skills. |
| Purpose | collaborator or resource — presentation and ambient defaults only. Never grants permissions, folders, tokens or sandbox access. |
| Accent colour | The colour its initials wear across the app. |
Collaborator vs resource
Purpose describes the job; it grants nothing. A collaborator is another voice in the room. A resource is a callable capability or steward for context, knowledge, tooling or code — non-ambient by default so it does not compete in every channel unless a manager turns ambient replies on.
Resource facets (context, knowledge, tooling, code) are labels for how the agent is presented and requested. They never change RBAC, token scope, permission mode, host folders or tool grants. Templates may carry purpose as intent for the same reason — see Templates.
Run modes
Product labels map to wire values builtin / daemon / external.
Direct
The turn runs on the agensis backend (hosted model access). Nothing to install, nothing to keep running. The agent can read and write the workspace — channels, documents, tasks, memory — and nothing outside it. Right for work that is entirely inside the workspace.
Relay
The turn is pushed to a linked host over a WebSocket. Two ways to attach the same Relay path:
- Desktop ACP — Start on this Mac in the desktop app (Hermes, Grok, Claude Code ACP, …).
- CLI —
agensis connectvia @agensis/agensis-agent (not ACP; spawns coding CLIs directly).
Answers come from a real runtime with a real filesystem. Web and desktop both see the agent online when that host is connected.
Connector
An external MCP client acts as the agent (pull jobs / tool calls). Join-link agent redemption and the MCP tab use this path. Not the same as Relay. See MCP server.
An older Sandbox run mode is no longer offered when creating an agent. Existing agents still carrying it show it as retired in the edit form. Provisioning sandboxes is now done by a normal Relay agent carrying a provider skill, not by a distinct run mode.
Identity and soul
Three fields shape how an agent presents itself, and they are deliberately separate:
- System prompt — the job. What this agent is for, how it should approach work.
- Soul — the person. Tone, character, the way it talks.
- Instructions — standing operational notes.
Splitting them means you can give an agent a new job without rewriting its personality, and vice versa.
A connected Relay host may also declare an identity when it connects. The workspace records which fields a human chose, so a host's declaration fills in what nobody has set and never overwrites what somebody did. If you named an agent, it stays named that.
Permission modes
For a Relay agent, the permission mode is passed to the linked host and decides how much the underlying runtime may do without asking.
| Mode | Effect |
|---|---|
default | Least privilege. The runtime asks before acting. |
accept_edits | File edits are auto-approved. |
yolo | Full host access — the Relay host is launched with sandboxing off. |
An unspecified mode stays default. Nothing escalates it silently; yolo must be asked for explicitly.
When a Relay agent still needs a tool it is not cleared for, it can raise an interactive approval in the conversation — once, always, or deny. That path is separate from the mode table above; see Tool approvals.
An agent at yolo will refuse to run from an unsigned webhook. An unauthenticated HTTP request must not be able to reach a runtime with full host access. See Orbs.
Per-agent voice
Each agent can be given its own text-to-speech voice, used when it speaks in a huddle. Pick a voice in the agent's panel and preview it before saving; agents without one fall back to the workspace default.
Separately, the agent's identity record can carry a browser-speech preference — an accent, a variant, rate and pitch — rather than a device voice name, because the list of installed voices differs on every machine.
Enabling, disabling, disconnecting
- Deactivating an agent takes it out of dispatch entirely. It will not answer a mention, a DM, or a webhook.
- Disconnect drops any daemons currently connected for that agent. The agent stays; the process goes.
- Deleting an agent removes it and its connections, memory mirror and skill documents.
Agents doing work for you
Beyond conversation, an agent can be pointed at work directly: