AgentKit Studio
Guides

Create and edit an agent

Build your first agent with the three-step form, and see why saving creates a revision.

This page gets a runnable agent created. Creating and editing share one form; only the save semantics differ — creating produces revision r1, editing produces r{n+1}.

Prerequisites

Three things must be true before you start. Missing any one of them blocks the Bind capabilities step:

  1. At least one model credential is configured and shows Configured. See Configure models and credentials.
  2. The Host is connected — the Agents panel lists existing agents instead of showing "Host not connected".
  3. You know what the agent is for. The system prompt falls back to the purpose description when it is empty (src/client/pages/agent-form.mjs:160).

Steps

Open the manual configuration form

In the Agents panel there are two entry points:

  • Click Chat to create in the top-right corner to refine prompts and resource bindings over several turns, then confirm the draft.
  • Click More ways to create (the chevron on the right) → Manual configuration to go straight to the three-step form.

This page covers manual configuration. Both entries render the same form component with identical fields.

Where to look

The Chat to create button and the More ways to create → Manual configuration menu in the Agents panel.

Step 1: Basic information

FieldPurposeDefault / validation
Prompt template (optional)Collapsed section offering General assistant and Research assistant starting pointsSelecting one fills in name, description, and system prompt
Agent IDStable identifierPlaceholder local-agent; lowercased on save
NameDisplay nameRequired
RuntimeExecution loopDefaults to DSH Native Harness; immutable after creation
PurposeOne-line descriptionSaved as "created locally by AgentKit Studio" when empty
Role and system promptIdentity, boundaries, answer styleFalls back to purpose, then template
Task description (optional)Fixed task backgroundHidden for cloud agents

How the three runtimes differ (src/client/theme.mjs:28-33):

RuntimeUI labelBest for
dsh-nativeDSH Native HarnessA local native loop that uses tools and resources on demand
harnessStar HarnessMulti-role collaboration with a configurable tool loop
codexCodex AgentCode and engineering tasks

The runtime choice is irreversible

The runtime radio group is disabled in edit mode, so switching runtimes means creating a new agent. Star Harness is visible for new agents but carries an "unavailable" badge and cannot be selected; it becomes selectable only when editing an existing Star Harness agent (src/client/pages/agent-form.mjs:61, :265-267).

When Next becomes clickable: both Agent ID and name are non-empty. No other field blocks it (src/client/pages/agent-form.mjs:137-138).

Step 2: Bind capabilities

Models (required)

  • Default model: used by new sessions, drawn from the merged local profile and model gateway catalog.
  • Available models: the set a conversation can switch to. The default model is always included — switching the dropdown adds it to the list automatically (src/client/pages/agent-form.mjs:289).

If the catalog read fails, the page shows only configured profiles and warns with MODEL_CATALOG_UNAVAILABLE. It blocks only when not a single model is readable.

Tools, varying by runtime:

RuntimeUI behavior
DSH Native HarnessOnly shows "Uses the DSH Native tool loop"; nothing to bind
Star HarnessAdjust by capability group shortcuts plus Advanced: adjust tool scope for per-item selection
Codex AgentA plain tool picker

MCP servers and Skills: multi-select; leaving them empty means unbound. Probe an MCP server before creating an agent, otherwise it stays unselectable in the catalog — see Bind an MCP server.

Platform resources: one dropdown each for knowledge base, memory instance, and Skill Center. All three come from the cloud catalog; without a cloud connection the dropdowns only offer "connect to the cloud first".

Where to look

The five blocks of the Bind capabilities step — models, tools, MCP servers, skills, and platform resources.

Step 3: Policy and confirmation

Permissions — content depends on the runtime:

RuntimeWhat is shownDefault
Star HarnessAgent tool policy with three optionsstrict
DSH Native / Codex"Permissions: managed by the current runtime and Host"Not editable

What the three options mean:

OptionBehavior
StrictWrites and unknown side effects require approval
Follow session and Host permissionsDelegated entirely to the session and Host
CustomUnknown side effects denied by default, overridden per tool

Choosing Custom reveals a per-tool rule box: a JSON object mapping tool names to decisions, where decisions are only inherit, ask, or deny:

{
  "read_workspace_file": "inherit",
  "save_crm": "ask"
}

Unlisted read-only tools follow the Host; every other tool is denied. Rules are fixed to the agent revision, and session permissions plus Host approval can still refuse further.

Two different policies — do not confuse them

The agent tool policy (this step) lives on the revision and only assigns per-tool inherit / ask / deny. The execution policy is the permission ceiling when deployed to the cloud: read-only / workspace-write / danger-full-access, defaulting to workspace-write, and it can only narrow the deployed runtime's ceiling (src/execution-policy.mjs:10,29). It is not part of this form.

Memory — the Cross-session memory switch is off by default. Turning it on reveals the memory settings panel; see Bind knowledge bases and Memory.

Sub-task roles — Star Harness only, used to declare multi-role collaboration.

Confirm configuration — a read-only summary: Agent ID, name, runtime, default model, available-model count, N Tool · N MCP · N Skill, platform resource count, memory source, and template source.

Where to look

The full row list of the Confirm configuration summary in step 3.

Save

  • On create the button reads Create agent, showing Saving… while in flight.
  • On edit it reads Save agent; saving creates a new configuration revision, and the notice names the current one (for example "currently r3").

Three values are fixed in the saved spec, and knowing them saves a detour:

  • security.toolPolicy is always deny-by-default.
  • Star Harness additionally receives process:host-user, plus network:mcp when any MCP server is bound.
  • DSH Native and Codex receive no extra permission and keep the deny-by-default set.

Editing does not affect running sessions

Saving produces a new revision; existing sessions and builds are not switched automatically. For a cloud agent, existing sessions keep the old snapshot and only new runs use the updated component bindings.

What success looks like

A notice appears at the top of the Agents list:

已创建 我的第一个 Agent(r1),可在运行中心构建。

On edit the notice starts with saved and includes the new revision number. Four conditions must hold:

  • The agent appears in the list and its status is not failed.
  • The runtime badge matches what you picked in step 1.
  • Reopening the editor shows the default model selected in Bind capabilities and the same available-model count.
  • Sending a message returns a complete answer rather than an error summary.

Common errors

Error codeCauseFix
AGENT_EXPECTED_REVISION_CONFLICTAnother window already saved a newer revisionClick Load latest version, compare your unsaved content item by item, then save again
AGENT_NOT_FOUNDThe agent was deleted or is outside this workspaceRefresh the Agents list and retry
AGENT_DEFINITION_REQUIREDThe submitted spec is emptyYou saved before the form finished loading; wait for the catalog
AGENT_MUTATION_BUSYConcurrent writes to the same agentWait for the in-flight operation, then retry
STUDIO_NATIVE_AGENT_POLICY_INVALIDPer-tool rules are not valid JSON, or a decision is outside inherit / ask / denyFix the JSON; tool names must match ^[A-Za-z][A-Za-z0-9_.:/-]{0,127}$
MODEL_CATALOG_UNAVAILABLEThe model gateway catalog failed to loadOnly configured profiles are shown; check credentials in Settings and reopen the form
AGENT_UPDATE_AUTHORITY_LOSTOwnership changed during editingReopen the editor
创建 Agent 失败Generic fallback; the real cause is in messageTake the full message and error code to troubleshooting

For the full by-code workflow, see Troubleshooting.

What you want to knowWhere to go
What a revision and a build freezeAgent · Revision · Build · Run
The full capability comparison of the three runtimesThe three runtimes
The shape of a resource binding and its exclusivity rulesResources and bindings
The native agent policy contractsrc/native-agent-policy.mjs (agentkit.native-agent-policy/v1)
Creation form sourcesrc/client/pages/agent-form.mjs, src/client/pages/agent-edit.mjs
Runtime defaultssrc/authoring-defaults.mjs:4, src/client/theme.mjs:26-33

On this page