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

FieldTypeDescription
idstringUnique id, prefixed agt_.
objectstringAlways "agent".
namestringLowercase name used in workflows, mentions (@builder) and run logs. Unique in the workspace.
rolestringOne line on what it does.
built_inbooleantrue for the five built-in agents.
runtimeenumclaude-code, codex-cli, gemini-cli or opencode.
modelstringA model the runtime supports, e.g. opus-5.5, gpt-6-codex, gemini-3-pro.
effortenumReasoning effort: default, low, medium, high or max.
permission_modeenumask_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_promptstringIts instructions. Mention skills with #skill and other agents with @name.
skillsstring[]Skill names it loads when they match the task.
toolsobjectBooleans for read_repo, edit_files, run_commands, open_prs and network.
integrationsstring[]Integration ids it may call, e.g. linear, sentry. API keys are injected as environment variables, never shown to the model.
limitsobjectbudget_per_run_usd and timeout_min, each null when unset. At 80% of the budget the run pauses and asks.
audienceenumWho can use it: me, project or workspace.
created_atstringWhen 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.

Agent
{
  "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

runtimeModels
claude-codeopus-5.5, sonnet-5.5, haiku-5.5
codex-cligpt-6-codex, gpt-6, gpt-6-mini
gemini-cligemini-3-pro, gemini-3-flash
opencodesonnet-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

GET https://api.duun.ai/v1/agents

Returns the built-in agents first, then custom agents by name. Needs agents:read.

Query parameters

built_in boolean Optional

true for only built-ins, false for only custom agents.

runtime enum Optional

Only agents on this runtime.

One of claude-code codex-cli gemini-cli opencode

limit integer Optional

1–100.

Default 20

cursor string Optional

next_cursor from 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)
Response
{
  "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

POST 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

name string Required

Lowercase letters, digits and dashes, unique in the workspace, e.g. sentinel.

role string Required

One line on what it does.

runtime enum Required

The CLI runtime it wraps.

One of claude-code codex-cli gemini-cli opencode

model string Required

A model the runtime supports.

effort enum Optional

Reasoning effort.

Default default

One of default low medium high max

permission_mode enum Optional

How often it must ask.

Default ask_writes

One of ask_everything ask_writes autonomous_sandbox

system_prompt string Optional

Its instructions. Defaults to a prompt built from name and role.

skills string[] Optional

Workspace skill names. Unknown names return 400.

tools object Optional

Booleans for read_repo, edit_files, run_commands, open_prs, network. Defaults: everything on except network.

integrations string[] Optional

Connected integration ids it may call.

limits object Optional

budget_per_run_usd, timeout_min.

audience enum Optional

Who can use it.

Default workspace

One of me project workspace

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},
)
Response
{
  "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

GET 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_id string 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

PATCH 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_id string Required

The agent's id or name.

Body parameters

role string Optional

One line on what it does.

runtime enum Optional

Changing the runtime requires a model it supports.

One of claude-code codex-cli gemini-cli opencode

model string Optional

A model the runtime supports.

effort enum Optional

Reasoning effort.

One of default low medium high max

permission_mode enum Optional

How often it must ask.

One of ask_everything ask_writes autonomous_sandbox

system_prompt string Optional

Its instructions.

skills string[] Optional

Replaces the list.

tools object Optional

Merged into the current tools.

integrations string[] Optional

Replaces the list.

limits object Optional

Merged. Set a field to null to clear it.

audience enum Optional

Who can use it.

One of me project workspace

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")
Response
{
  "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

DELETE 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_id string 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")
Response
{ "id": "agt_sentinel2f", "object": "agent", "deleted": true }

Errors worth handling:

  • 403 permission_denied with code built_in_agent: built-in agents can’t be deleted.
  • 409 conflict with code agent_in_use: one or more workflow steps are owned by this agent. The message names the workflows; reassign those steps and apply new versions first.

    Type to search the docs, help center and blog.