Skip to content

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.

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.

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
Value Description
workspace The default; unknown and null stored values parse to it
private Private to the creating user
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

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.

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 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.
  • preTool fails 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 preTool hook denies every tool call until it is fixed.
  • A hooks block 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.

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.