AgentKit Studio
任务指南

创建与编辑 Agent

用三步表单创建第一个 Agent,并理解保存为什么会产生新的修订版本,以及运行时为什么不可改。

这一页走完「创建一个能跑的 Agent」。创建和编辑共用同一张表单,区别只在保存语义:新建产生修订版本 r1,编辑产生 r{n+1}。

前置条件

开始之前需要同时满足三条,缺任何一条都会在「绑定能力」步骤卡住:

  1. 已经配置至少一个模型凭证,并且状态显示已配置。见配置模型与凭证。
  2. Host 已连接——智能体面板能列出已有的 Agent,而不是显示「Host 尚未连接」。
  3. 你想好了 Agent 的用途描述。系统会在系统 Prompt 为空时用它兜底(src/client/pages/agent-form.mjs:160)。

操作步骤

打开手动配置表单

在智能体面板,有两个入口:

  • 点右上角对话创建,通过多轮对话完善提示词与资源绑定,确认草稿后创建。
  • 点更多创建方式(右侧下拉箭头)→ 手动配置,直接进入三步表单。

本页走手动配置。两种入口最终进入同一个表单组件,字段完全一致。

界面位置

智能体面板右上角的「对话创建」按钮与「更多创建方式 → 手动配置」菜单。

第一步:基本信息

字段说明默认 / 校验
提示词模板(可选)折叠区,提供通用助手与研究助手两个起点选模板会填充名称、描述、系统 Prompt
Agent ID稳定标识占位符 local-agent,保存时转小写
名称展示名必填
运行时执行循环默认 DSH Native Harness,创建后不可更改
用途描述一句话说明留空时保存为「由 AgentKit Studio 本地创建」
角色与系统 Prompt身份、边界、回答方式留空时按「描述 → 模板」顺序兜底
任务说明(可选)固定任务背景云端 Agent 不显示此字段

三种运行时的区别(src/client/theme.mjs:28-33):

运行时界面显示适合什么
dsh-nativeDSH Native Harness本地原生循环,按需使用工具与资源
harnessStar Harness多角色协作与可配置的工具循环
codexCodex Agent面向代码与工程任务

运行时是不可逆选择

运行时的单选在编辑态被禁用,要换运行时只能新建 Agent。 新建时 Star Harness 会显示在选项里,但带「未开放」徽章且不可选中;编辑一个已经使用 Star Harness 的既有 Agent 时才可选(src/client/pages/agent-form.mjs:61、:265-267)。

「下一步」什么时候可点:Agent ID 与名称都非空。其他字段都不阻塞(src/client/pages/agent-form.mjs:137-138)。

第二步:绑定能力

模型(必填)

  • 默认模型:新会话使用的模型,来自本地模型配置与模型网关合并后的目录。
  • 可用模型:对话中可切换到的模型集合。默认模型始终在集合里——切换下拉时会自动把它加进列表(src/client/pages/agent-form.mjs:289)。

目录读取失败时页面只显示已配置的模型档案,并给出 MODEL_CATALOG_UNAVAILABLE 警告;一条模型都读不到时才真正阻塞。

工具,按运行时显示不同内容:

运行时界面行为
DSH Native Harness只显示「使用 DSH Native 工具循环」,无需绑定工具
Star Harness「按能力组调整」快捷选择 + 「高级:调整工具范围」逐项勾选
Codex Agent直接列出工具选择器

MCP 服务与技能:多选,留空表示不绑定。创建前先把 MCP Server 探测通过,否则目录里它是不可选状态,见绑定 MCP Server。

平台资源:知识库、记忆库、Skill Center 各一个下拉。三项来自云端目录,没连上云端时下拉里只有「请先连接云端」。

界面位置

「绑定能力」步骤的模型、工具、MCP 服务、技能与平台资源五个区块。

第三步:策略与确认

权限——内容随运行时变化:

运行时显示默认
Star Harness「Agent 工具约束」三选项strict
DSH Native / Codex「权限:由当前运行端和 Host 管理」不可改

三个选项的含义:

选项行为
严格写入和未知副作用需审批
遵循会话与 Host 权限完全交给会话与 Host 决定
自定义默认拒绝未知副作用,按逐工具规则覆盖

选自定义时会出现逐工具规则输入框,格式是工具名到决策的 JSON 对象,决策只能是 inherit、ask、deny:

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

未列出的只读工具遵循 Host,其他工具拒绝。规则随 Agent 版本固定,会话权限与 Host 审批仍可进一步拒绝。

两种「策略」不要混淆

Agent 工具约束(本步骤)挂在修订版本上,只规定工具级别的 inherit / ask / deny。 执行策略(execution policy)是部署到云端时的权限上限,取值为 read-only / workspace-write / danger-full-access, 默认 workspace-write,并且只能向下收窄已部署运行时的上限(src/execution-policy.mjs:10,29)。它不在这个表单里。

记忆——「跨会话记忆」开关默认关闭。打开后出现记忆设置面板,详见绑定知识库与 Memory。

子任务角色——仅 Star Harness 显示,用于声明多角色协作。

确认配置——只读摘要,逐项核对 Agent ID、名称、运行时、默认模型、可用模型数量、N Tool · N MCP · N Skill、平台资源数量、记忆来源与模板来源。

界面位置

「策略与确认」步骤确认配置摘要的完整行项目。

保存

  • 新建时按钮是创建 Agent,保存中显示保存中…。
  • 编辑时按钮是保存 Agent,保存后创建新的配置版本,当前版本号在提示里(例如「当前 r3」)。

保存会写成的 spec 里有三个固定值,理解它们可以少走弯路:

  • security.toolPolicy 恒为 deny-by-default。
  • Star Harness 额外获得 process:host-user;绑定了 MCP 时再追加 network:mcp。
  • DSH Native 与 Codex 不追加任何权限,保持默认拒绝集。

编辑不会影响正在跑的会话

保存产生新的修订版本,已有会话和构建不会被自动切换。云端 Agent 的已有会话继续使用旧快照,新运行才使用更新后的组件绑定。

成功后的样子

保存成功后,智能体列表顶部出现一条状态提示:

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

编辑时提示以已保存开头,并带上新版本号。同时满足以下四条才算真的成功:

  • 列表里能看到该 Agent,状态不是失败。
  • 运行时标签与你在第一步选择的一致。
  • 打开编辑页,绑定能力步骤里默认模型已选中、可用模型数量与创建时一致。
  • 发一条消息能拿到完整回答,而不是错误摘要。

常见错误

错误码原因处理
AGENT_EXPECTED_REVISION_CONFLICT另一个窗口已经保存了更新的版本点读取最新版本,把未保存内容与最新版本逐项核对后重新保存
AGENT_NOT_FOUNDAgent 已被删除,或不在当前工作区返回智能体列表刷新后重试
AGENT_DEFINITION_REQUIRED提交的 spec 为空表单未加载完成就点了保存;等目录读完再操作
AGENT_MUTATION_BUSY同一 Agent 有并发写操作等待当前操作结束后重试
STUDIO_NATIVE_AGENT_POLICY_INVALID逐工具规则不是合法 JSON,或决策值不在 inherit / ask / deny 里修正 JSON;工具名需匹配 ^[A-Za-z][A-Za-z0-9_.:/-]{0,127}$
MODEL_CATALOG_UNAVAILABLE模型网关目录读取失败只显示已配置档案;到设置页检查凭证后重进表单
AGENT_UPDATE_AUTHORITY_LOST编辑期间 Agent 所有权发生变化重新打开编辑页
创建 Agent 失败兜底文案,真实原因在 message 里把 message 全文与错误码一起带进排障

按错误码定位的完整流程见排障。

相关参考

你想知道去哪里
修订版本与构建分别冻结什么Agent · Revision · Build · Run
三种运行时的完整能力对照三种运行时
资源绑定的数据形状与互斥规则资源与绑定
原生 Agent 权限策略契约src/native-agent-policy.mjs(agentkit.native-agent-policy/v1)
创建表单源码src/client/pages/agent-form.mjs、src/client/pages/agent-edit.mjs
运行时默认值src/authoring-defaults.mjs:4、src/client/theme.mjs:26-33

本页导航