Create and configure an agent

This guide shows you how to add an agent to a workspace and configure it until it can actually run.

Every workspace is seeded with five agents — a CEO plus qa, architect, engineer and librarian — so you usually have agents before you have configured any. The steps below apply equally to a seeded agent and a new one.

Before you start

You are inside a workspace. The whole surface lives at Settings → Workspace → Agents (/settings/workspace/agents).
The agent will need a backend. Either connect a provider for the built-in harness under Settings → Server → Model providers, or install the Claude Code CLI on the machine hosting cc_server.
If you want the agent to carry skills, install them first under Settings → Workspace → Skills. The agent form only lets you toggle skills that already exist in the workspace.

Add the agent

Open Settings → Workspace → Agents.
Click New agent.

There is no dialog and no role picker. An agent named “Unnamed agent” is created immediately and selected in the detail pane on the right.

You should now see “Unnamed agent” in the roster on the left, with the Settings tab of its detail pane open and a Name field containing “Unnamed agent”.

Name it

Name — the short identifier used in @-mentions, for example alice. Mention parsing matches @ followed by word characters, so a name containing a hyphen, a dot or a space can never be mentioned.
Title — the human-readable label, for example “Senior coder”.
System prompt — optional extra instructions, injected as an Agent instructions section; they do not replace the rest of the assembled prompt.

Click Save changes at the bottom of the form. Every field on this page is saved by that one button.

Give it an adapter and a model

The Adapter dropdown lists runners the server host actually has. The built-in adapter is always found (it is the server). Claude Code appears only when its CLI was detected on that host:

Adapter	Backend
Control Center (built-in)	The in-process agent loop — no external CLI
Claude Code	`claude -p --output-format stream-json`

Only the built-in adapter enforces modes, steering, pause/resume, completion contracts and subagents. Claude Code gives you none of those. Cursor, Codex and the other model providers attach to the built-in adapter, not as separate runners.

The Model dropdown is driven by the adapter you picked. For the built-in adapter the list comes live from the providers you have connected under Settings → Server → Model providers, so a provider with no stored credential contributes zero models.

Add skills

Skills is a chip picker over the skill bundles installed in this workspace. Tap a chip to toggle it; the check glyph marks the selected ones. If the workspace has no skills the field reads “No skills available. Create skills in Settings → Skills first.”

You do not pick a repo’s own skills here. A repo that ships them (in .agents/skills/, .claude/skills/ or .opencode/skills/) contributes them automatically to whichever agent is working in that repo, and they swap out when it moves to another — see Repo-scoped skills.

Set the reporting line and persona

Reports to — pick another agent by name. This builds the reporting tree shown by the Org chart button in the page header. It is not the roster a team leader uses when it delegates — that comes from the team’s members and their skills.
Persona — free text that shapes tone and behaviour, for example: “Prefers simple, readable solutions. Writes tests for all new code.”

Tune the run

Reasoning effort — the options come from the selected model’s own published levels: Low / Medium / High, plus Extra High on OpenAI-style models and Extra High + Max on Claude-style ones. The field is hidden entirely when the selected model declares no thinking levels and it defaults to the model’s own default.
Context window size — pre-filled from the model’s context window whenever you change model, with one-tap chips for the model default, 200k, 500k and 1M. A value you type after picking the model wins until the next model change.
Silence timeout (minutes) — terminate a run after this long with no output. Leave it empty to use the per-mode default.

Grant permissions

An agent has no permission toggles of its own. What it may push, open, merge or reach is set by the action rules at Settings → Workspace → Agent permissions, where a rule can be scoped to this agent. Out of the box a push, a pull request, a review or merge and a tracker write each ask you first, and network access is allowed.

The agent’s GitHub token is always read-only. A push goes through Control Center, which asks the Push to a remote rule before forwarding it. See Configure sandbox policies for how each rule reaches a run.

Verify it runs

Open Settings → Server → Model providers and confirm the adapter you chose reports an installed version rather than “Not found”. Click Refresh to re-probe — the probe runs on the machine hosting cc_server, not on the machine you are looking at.
Open a space with the agent and send it a message, or @-mention it in an existing space.
Come back to Settings → Workspace → Agents, select the agent and open its Logs tab. A run should appear with a status badge, a duration, a started time and the adapter it used. View opens that run’s event stream.

If no run appears at all, work through Run agent diagnostics.

Delete an agent

Select it in the roster. On the Settings tab, scroll to the Danger zone at the bottom of the form and click Delete.