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 behavioral 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 |
monthlyBudgetCents |
int |
No | Monthly spending cap in cents (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 monthlyBudgetCents 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
monthlyBudgetCents 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'}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.