Agents
List the built-in agents, and create, update and delete custom agents: runtime, model, permission mode, tools, skills and limits.
On this page
An agent wraps a CLI runtime (Claude Code, Codex CLI, Gemini CLI or OpenCode) and a model, with a system prompt, the skills it loads, the tools it may use and how often it must ask. Workflow steps name an agent as their owner. See Agents for the concepts.
Every workspace has five built-in agents: builder, tester, operator, writer and reviewer. You can change a built-in agent’s model, skills and permission mode, but you can’t delete or rename it. Custom agents can be changed in every way.
The agent object
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed agt_. |
object | string | Always "agent". |
name | string | Lowercase name used in workflows, mentions (@builder) and run logs. Unique in the workspace. |
role | string | One line on what it does. |
built_in | boolean | true for the five built-in agents. |
runtime | enum | claude-code, codex-cli, gemini-cli or opencode. |
model | string | A model the runtime supports, e.g. opus-5.5, gpt-6-codex, gemini-3-pro. |
effort | enum | Reasoning effort: default, low, medium, high or max. |
permission_mode | enum | ask_everything (every write and command is an ask), ask_writes (reads and allow-listed commands run freely) or autonomous_sandbox (no asks inside a disposable, offline sandbox). |
system_prompt | string | Its instructions. Mention skills with #skill and other agents with @name. |
skills | string[] | Skill names it loads when they match the task. |
tools | object | Booleans for read_repo, edit_files, run_commands, open_prs and network. |
integrations | string[] | Integration ids it may call, e.g. linear, sentry. API keys are injected as environment variables, never shown to the model. |
limits | object | budget_per_run_usd and timeout_min, each null when unset. At 80% of the budget the run pauses and asks. |
audience | enum | Who can use it: me, project or workspace. |
created_at | string | When the agent was created. |
An agent never gets more access than the factory or the person who started the run. The lowest applicable limit always wins.
{
"id": "agt_builder",
"object": "agent",
"name": "builder",
"role": "Plans and implements changes end-to-end",
"built_in": true,
"runtime": "claude-code",
"model": "opus-5.5",
"effort": "high",
"permission_mode": "ask_writes",
"system_prompt": "You are builder. Plans and implements changes end-to-end. Follow the repo's CONTRIBUTING.md and the factory's guardrails. Ask when unsure; never guess at money movement.",
"skills": ["payments", "ledger", "react", "postgres", "expo"],
"tools": {
"read_repo": true,
"edit_files": true,
"run_commands": true,
"open_prs": true,
"network": false
},
"integrations": ["linear", "github", "sentry"],
"limits": { "budget_per_run_usd": null, "timeout_min": null },
"audience": "workspace",
"created_at": "2026-09-02T14:11:40Z"
}Runtimes and models
runtime | Models |
|---|---|
claude-code | opus-5.5, sonnet-5.5, haiku-5.5 |
codex-cli | gpt-6-codex, gpt-6, gpt-6-mini |
gemini-cli | gemini-3-pro, gemini-3-flash |
opencode | sonnet-5.5, opus-5.5, gpt-6, gemini-3-pro |
A model the runtime doesn’t support returns 422 validation_error with param: "model". Which provider serves a model, and whether calls bill to Duun credits or your own key, is set in Models and BYOK.
Endpoints
List agents
https://api.duun.ai/v1/agents Returns the built-in agents first, then custom agents by name. Needs agents:read.
Query parameters
-
built_inboolean Optional -
truefor only built-ins,falsefor only custom agents. -
runtimeenum Optional -
Only agents on this runtime.
-
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom the previous page.
curl https://api.duun.ai/v1/agents \
-H "Authorization: Bearer $DUUN_API_KEY"import Duun from "@duun/sdk";
const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });
for await (const agent of duun.agents.list()) {
console.log(agent.name, agent.runtime, agent.model, agent.permission_mode);
}from duun import Duun
client = Duun()
for agent in client.agents.list():
print(agent.name, agent.runtime, agent.model, agent.permission_mode){
"object": "list",
"data": [
{ "id": "agt_builder", "object": "agent", "name": "builder", "built_in": true, "runtime": "claude-code", "model": "opus-5.5", "permission_mode": "ask_writes" },
{ "id": "agt_tester", "object": "agent", "name": "tester", "built_in": true, "runtime": "codex-cli", "model": "gpt-6-codex", "permission_mode": "autonomous_sandbox" },
{ "id": "agt_operator", "object": "agent", "name": "operator", "built_in": true, "runtime": "claude-code", "model": "opus-5.5", "permission_mode": "ask_everything" },
{ "id": "agt_writer", "object": "agent", "name": "writer", "built_in": true, "runtime": "gemini-cli", "model": "gemini-3-pro", "permission_mode": "ask_writes" },
{ "id": "agt_reviewer", "object": "agent", "name": "reviewer", "built_in": true, "runtime": "opencode", "model": "sonnet-5.5", "permission_mode": "ask_everything" },
{ "id": "agt_sentinel2f", "object": "agent", "name": "sentinel", "built_in": false, "runtime": "claude-code", "model": "sonnet-5.5", "permission_mode": "ask_everything" }
],
"has_more": false,
"next_cursor": null
}List items are full agent objects; the example is trimmed.
Create an agent
https://api.duun.ai/v1/agents Creates a custom agent. Fields you leave out get the same defaults as New agent in the app. Needs agents:write.
Body parameters
-
namestring Required -
Lowercase letters, digits and dashes, unique in the workspace, e.g.
sentinel. -
rolestring Required -
One line on what it does.
-
runtimeenum Required -
The CLI runtime it wraps.
-
modelstring Required -
A model the runtime supports.
-
effortenum Optional -
Reasoning effort.
-
permission_modeenum Optional -
How often it must ask.
-
system_promptstring Optional -
Its instructions. Defaults to a prompt built from
nameandrole. -
skillsstring[] Optional -
Workspace skill names. Unknown names return 400.
-
toolsobject Optional -
Booleans for
read_repo,edit_files,run_commands,open_prs,network. Defaults: everything on exceptnetwork. -
integrationsstring[] Optional -
Connected integration ids it may call.
-
limitsobject Optional -
budget_per_run_usd,timeout_min. -
audienceenum Optional -
Who can use it.
curl https://api.duun.ai/v1/agents \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "sentinel",
"role": "Reviews diffs for auth, secrets and injection risks before humans do.",
"runtime": "claude-code",
"model": "sonnet-5.5",
"effort": "high",
"permission_mode": "ask_everything",
"skills": ["security"],
"tools": { "read_repo": true, "edit_files": false, "run_commands": false, "open_prs": false, "network": false },
"limits": { "budget_per_run_usd": 2 }
}'const sentinel = await duun.agents.create({
name: "sentinel",
role: "Reviews diffs for auth, secrets and injection risks before humans do.",
runtime: "claude-code",
model: "sonnet-5.5",
effort: "high",
permission_mode: "ask_everything",
skills: ["security"],
tools: { read_repo: true, edit_files: false, run_commands: false, open_prs: false, network: false },
limits: { budget_per_run_usd: 2 },
});sentinel = client.agents.create(
name="sentinel",
role="Reviews diffs for auth, secrets and injection risks before humans do.",
runtime="claude-code",
model="sonnet-5.5",
effort="high",
permission_mode="ask_everything",
skills=["security"],
tools={"read_repo": True, "edit_files": False, "run_commands": False, "open_prs": False, "network": False},
limits={"budget_per_run_usd": 2},
){
"id": "agt_sentinel2f",
"object": "agent",
"name": "sentinel",
"role": "Reviews diffs for auth, secrets and injection risks before humans do.",
"built_in": false,
"runtime": "claude-code",
"model": "sonnet-5.5",
"effort": "high",
"permission_mode": "ask_everything",
"system_prompt": "You are sentinel. Reviews diffs for auth, secrets and injection risks before humans do. Follow the repo's CONTRIBUTING.md and the factory's guardrails. Ask when unsure; never guess at money movement.",
"skills": ["security"],
"tools": { "read_repo": true, "edit_files": false, "run_commands": false, "open_prs": false, "network": false },
"integrations": [],
"limits": { "budget_per_run_usd": 2, "timeout_min": null },
"audience": "workspace",
"created_at": "2026-11-15T11:20:00Z"
}A name that’s taken returns 409 conflict with code name_taken.
Retrieve an agent
https://api.duun.ai/v1/agents/{agent_id} Returns one agent. You can pass its id or its name. Needs agents:read.
Path parameters
-
agent_idstring Required -
The agent's id (
agt_builder) or name (builder).
curl https://api.duun.ai/v1/agents/builder \
-H "Authorization: Bearer $DUUN_API_KEY"const builder = await duun.agents.retrieve("builder");builder = client.agents.retrieve("builder")The response is an agent object.
Update an agent
https://api.duun.ai/v1/agents/{agent_id} Changes an agent. Send only the fields you want to change; tools and limits are merged. Changes apply from each run’s next step. Needs agents:write.
For built-in agents you can change model, effort, permission_mode, skills, system_prompt, integrations and limits. Changing name, runtime or tools on a built-in agent returns 403 permission_denied with code built_in_agent.
Path parameters
-
agent_idstring Required -
The agent's id or name.
Body parameters
-
rolestring Optional -
One line on what it does.
-
runtimeenum Optional -
Changing the runtime requires a
modelit supports. -
modelstring Optional -
A model the runtime supports.
-
effortenum Optional -
Reasoning effort.
-
permission_modeenum Optional -
How often it must ask.
-
system_promptstring Optional -
Its instructions.
-
skillsstring[] Optional -
Replaces the list.
-
toolsobject Optional -
Merged into the current tools.
-
integrationsstring[] Optional -
Replaces the list.
-
limitsobject Optional -
Merged. Set a field to
nullto clear it. -
audienceenum Optional -
Who can use it.
curl -X PATCH https://api.duun.ai/v1/agents/builder \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "model": "sonnet-5.5", "effort": "medium" }'const builder = await duun.agents.update("builder", { model: "sonnet-5.5", effort: "medium" });builder = client.agents.update("builder", model="sonnet-5.5", effort="medium"){
"id": "agt_builder",
"object": "agent",
"name": "builder",
"built_in": true,
"runtime": "claude-code",
"model": "sonnet-5.5",
"effort": "medium",
"permission_mode": "ask_writes"
}The response is the full agent object; the example is trimmed.
Delete an agent
https://api.duun.ai/v1/agents/{agent_id} Deletes a custom agent. Workflow steps owned by it must be reassigned first. Runs it already worked on keep their history. Needs agents:write.
Path parameters
-
agent_idstring Required -
The agent's id or name.
curl -X DELETE https://api.duun.ai/v1/agents/sentinel \
-H "Authorization: Bearer $DUUN_API_KEY"await duun.agents.delete("sentinel");client.agents.delete("sentinel"){ "id": "agt_sentinel2f", "object": "agent", "deleted": true }Errors worth handling:
403 permission_deniedwith codebuilt_in_agent: built-in agents can’t be deleted.409 conflictwith codeagent_in_use: one or more workflow steps are owned by this agent. Themessagenames the workflows; reassign those steps and apply new versions first.
Related
- Agents, Runtimes and Permissions and approvals
- Skills API for what agents load