Agent configuration
This reference lists every field on the agent entity, plus the enums and flags it uses. For a step-by-step walkthrough of creating or editing an agent in the app, see Create and configure an agent.
Agent entity fields
Section titled “Agent entity fields”| Field | Type | Required | Description |
|---|---|---|---|
id |
String |
Yes | Unique agent identifier |
name |
String |
Yes | Short identifier for @-mentions |
title |
String |
Yes | Human-readable role title |
agentMdPath |
String |
Yes | Absolute path to the agent’s .md definition file |
workspaceId |
String |
Yes | Owning workspace (non-null) |
reportsTo |
String? |
No | Parent agent ID |
skills |
AgentSkills |
Yes | Set of skill identifiers |
persona |
String? |
No | Free-text behavioural instructions |
systemPrompt |
String? |
No | Override the default system prompt |
adapterId |
String? |
No | Inference adapter id |
modelId |
String? |
No | Model id within the adapter |
strictMode |
bool |
No | Default false. Written to the row and to the agent’s AGENTS.md |
effort |
String? |
No | Reasoning level id (e.g. 'low', 'xhigh'), sourced from the selected model’s thinkingLevels |
contextSize |
int? |
No | Max context window size |
role |
AgentRole? |
No | Agent role |
monthlyBudgetMicros |
int |
No | Monthly spending cap in micro-dollars (default 0, unlimited) |
silenceTimeoutMinutes |
int? |
No | Silence-timeout override in minutes; must be null or in 1–240 (constructor-asserted) |
maxConcurrentTasks |
int |
No | Default 1. Capacity figure the presence model reports (running and queued counts are compared against it) |
visibility |
AgentVisibility |
No | Default workspace |
lifecycleStatus |
AgentLifecycleStatus |
No | Governance status (default active). Written by the budget hard-stop and rendered on the org chart and presence roster. Dispatch still accepts work from a paused agent |
budgetPolicyId |
String? |
No | Shared budget policy id; when null monthlyBudgetMicros applies directly |
runtimeProfileId |
String? |
No | Custom runtime profile id |
createdAt |
DateTime |
Yes | Creation timestamp |
name and title must both be non-empty (constructor-asserted). Default
monthlyBudgetMicros of 0 means unlimited. Write a ceiling with agents.upsert.
AgentRole enum
Section titled “AgentRole enum”| Role | Label | Description |
|---|---|---|
ceo |
CEO | Coordination and delegation |
coder |
Coder | Code implementation |
reviewer |
Reviewer | PR review and analysis |
qa |
QA | Testing and quality assurance |
designer |
Designer | UI/UX implementation |
security |
Security | Security review and auditing |
devops |
DevOps | Infrastructure and deployment |
pm |
PM | Product management |
general |
General | Flexible, multi-purpose |
AgentVisibility enum
Section titled “AgentVisibility enum”| Value | Description |
|---|---|
workspace |
The default; unknown and null stored values parse to it |
private |
Private to the creating user |
AgentLifecycleStatus enum
Section titled “AgentLifecycleStatus enum”| Value | Description |
|---|---|
active |
The default. isDispatchable is true only for this value |
paused |
Set by the budget hard-stop. Shown on the presence roster; dispatch still accepts work |
archived |
Retired and hidden from active rosters |
Permissions
Section titled “Permissions”An agent carries no permission flags. Pushing, opening and publishing pull requests, writing to a tracker and network egress are action classes (gitPush, prCreate, prPublish, vendorSyncWrite, networkEgress) that the guardrails resolve at the workspace, agent or space scope. A run’s GitHub token is always read-scoped; pushes go through the agent run gateway, which asks the gitPush rule before forwarding them.
AgentSkills
Section titled “AgentSkills”An immutable, case-insensitive set of skill identifiers. At dispatch those slugs are synced as skill links in the agent’s overlay; the harness then autoloads the linked skills’ frontmatter into the prompt.
{'flutter', 'dart', 'rest-api'}Shell hooks
Section titled “Shell hooks”Shell hooks let the server owner run their own scripts around a built-in harness run: once at session start, before each tool call, and after each tool call. A hook is arbitrary code, so hooks are host configuration. Only the server owner sets them up, by hand, on the server’s machine. There is no setting in the app and no operation that writes them.
For an agent, the hooks live in its own folder under the server’s data directory:
<data dir>/_agent_hooks/<workspace id>/<agent slug>/hooks.json<agent slug> is the name of the agent’s folder in the workspace (agents/<slug>/). That folder sits outside every workspace’s storage, and every sandbox hides the data directory, so no member, run or terminal can write it.
hooks.json maps any of three keys to a script, by a path relative to the hook folder:
| Key | When it runs | What its exit code means |
|---|---|---|
sessionStart |
Once, when the run starts | Nothing; the hook only observes |
preTool |
Before every tool call | 0 allows the call; anything else denies it |
postTool |
After every tool call | Nothing; the hook only observes |
- Each script is started as its own executable, with no shell and no arguments, so it must be executable and start with a shebang line. It receives the event as JSON on stdin: the event name, and for the tool hooks the tool’s name with its arguments (
preTool) or its result (postTool). - A hook runs as one of the run’s tool processes, in the agent’s directory for the run. When the server sandboxes agents it runs inside the run’s sandbox. It gets a minimal environment and none of the run’s credentials: no forge or provider token and no gateway access.
- Each hook has 30 seconds. Its output is read and discarded.
preToolfails closed. A non-zero exit, a timeout or a script that cannot start denies the tool call.- A path that is absolute, missing, or that leaves the hook folder (links resolved) is refused, and the run’s log says which hook was refused and why. A refused or unreadable
preToolhook denies every tool call until it is fixed. - A
hooksblock in.agents/harness.json, whether in a repository or in the agent’s own folder, is ignored. A repository is often someone else’s code and the agent’s folder can be written by members and by runs. The run’s log says the block was ignored and where hooks are read from instead.
Shell hooks apply to the built-in harness only. A configured preTool or postTool hook makes the run call its tools one at a time.
AgentLiveState (derived)
Section titled “AgentLiveState (derived)”Not stored. Seven values. Declaration order is priority order (sortPriority, pinned by a test), which is the order the roster sorts by:
| State | sortPriority |
Condition |
|---|---|---|
running |
0 | Any run log has status running |
blocked |
1 | The latest run’s liveness is blocked, stalled, or looping |
failed |
2 | The latest run’s status is error, or its liveness is failed or dead |
queued |
3 | A run is dispatched but not executing — parked behind another run of the same agent, or written but not yet started |
succeeded |
4 | The run finished successfully |
idle |
5 | The agent has run before and has nothing in flight |
neverRun |
6 | No run logs exist |
queued and succeeded are per-run only. deriveAgentLiveState, which computes the roster state for an agent, never produces either — it returns neverRun, running, failed, blocked, or idle.