AgentKit Studio
任务指南

任务指南

按目标组织的 14 篇操作指南,从创建 Agent 到部署上线,每步都能直接复制执行。

任务指南按「你要完成什么」组织。每一页给出前置条件、可复制的操作步骤、成功验证方式和错误码对照,不解释内部实现——原理在核心概念里。

这一章有什么

阶段页面你要达成的结果前置条件
起点创建与编辑 Agent得到一个可运行的 Agent 与第一个修订版本至少配置一个模型
模型配置模型与凭证会话能选中并真实调用模型一个 OpenAI 兼容端点与 API Key
能力绑定 MCP ServerAgent 能调用外部系统的工具MCP 服务地址或启动命令
能力绑定 SkillAgent 复用已有的操作说明与脚本目录里有 SKILL.md
能力绑定知识库与 MemoryAgent 能检索企业知识并跨会话记忆已连接云端控制面
运行运行与调试会话看懂工具调用、文件变更与本轮用量有一个可用 Agent
治理审批与权限策略写入和未知副作用受策略约束有一个可用 Agent
交付部署到云端Agent 7×24 常驻可用云端凭证与镜像仓库
交付托管运行时更新与回滚更新可控、失败可回滚已部署的托管运行时
自动化自动化与调度按时间或事件触发运行已部署的 Agent
接入渠道(Channels)从外部消息入口触发 Agent已部署的 Agent
观测可观测性(OTel)用 OpenTelemetry 采集运行轨迹已部署的 Agent
运行时安装、升级与绑定 Star Harnessharness 从「未启用」变成可创建Node.js 与 npm 可用

创建表单的三步

创建和编辑 Agent 共用同一张表单,左侧步骤条固定为三步(src/client/pages/agent-form.mjs:79):

步骤你要决定什么必填可以留到之后改吗
基本信息Agent ID、名称、运行时、用途描述、系统 Prompt、任务说明Agent ID 与名称除运行时外都能改
绑定能力默认模型、可用模型、工具、MCP 服务、技能、平台资源默认模型能改,保存后生成新版本
策略与确认Agent 工具约束、跨会话记忆、确认配置摘要无能改

运行时在创建后不可更改——表单里的运行时单选在编辑态是禁用的(src/client/pages/agent-form.mjs:266)。要换运行时只能新建一个 Agent。

五类可绑定资源

资源库和创建表单读取同一份目录契约(src/resource-catalog.mjs:74):

kind来源绑定后 Agent 得到什么每类可绑几个
model本地模型配置 + 模型网关一段可切换的模型列表多个,其中一个为默认
mcp本地 MCP store + 云端该 Server 发现的全部工具多个
skill已安装 Skill + 云端 Skill Space操作说明与随附脚本多个
knowledge-baseAgentEngine agentengine-server只读检索能力一个
memory-instanceAgentEngine agentengine-server跨会话召回与写入一个

本地 Skill 与云端 Skill Space 分开管理,两者可以同时绑定(src/client/pages/platform-resource-picker.mjs:12)。

默认值速查

这些默认值来自代码,不由界面文案决定。改配置前先确认你要覆盖的是哪一层:

项默认值证据
新建 Agent 的运行时dsh-native(界面显示 DSH Native Harness)src/authoring-defaults.mjs:4
可选运行时集合dsh-native / harness / codexsrc/client/theme.mjs:26
运行时显示名DSH Native Harness / Star Harness / Codex Agentsrc/client/theme.mjs:28-33
Agent 工具约束strictsrc/client/pages/agent-form.mjs:54
执行策略workspace-writesrc/execution-policy.mjs:10
记忆写入方式新建 explicit_only,编辑 candidatesrc/client/state/agent-memory-config.mjs:76
记忆写入开关shadow(只评估不写入)src/client/state/agent-memory-config.mjs:33
默认模型凭证名AGENTKIT_MODEL_API_KEYsrc/client/dsh/model-bridge.mjs:17

Star Harness 要先安装并绑定工作区

三种运行时里只有 Star Harness 是可插拔的:插件页装好、启用、并绑定一个工作区之后, 创建 Agent 时才会提供它(creatableRuntime,src/client/pages/agent-form.mjs:78)。 见安装、升级与绑定 Star Harness。

每页的结构约定

所有任务指南按同一骨架组织,方便你直接跳到需要的小节:

  1. 前置条件 —— 开始之前必须已经具备的东西,缺一项就会在中间某步失败。
  2. 操作步骤 —— 编号步骤,命令、路径、字段名都是完整值,没有省略号。
  3. 成功后的样子 —— 怎么判断这一步真的成了,而不是「看起来没报错」。
  4. 常见错误 —— 错误码 → 原因 → 处理,错误码可以全文搜索。
  5. 相关参考 —— 对应的契约页面与源码入口。

跨页通用错误

错误码出现位置原因处理
AGENT_EXPECTED_REVISION_CONFLICT保存 Agent另一个窗口已经保存了更新的版本点「读取最新版本」,核对后重新保存
AGENT_NOT_FOUND编辑、绑定Agent 已被删除或不在当前工作区回到智能体列表刷新
AGENT_DEFINITION_REQUIRED保存 Agent提交的 spec 为空检查是否在表单未加载完成时就点了保存
MODEL_CATALOG_UNAVAILABLE绑定能力第一步模型网关目录读取失败只显示已配置的模型资源;到设置页检查凭证
MANAGED_RESOURCE_INVALID绑定平台资源资源引用不符合 agentengine.resources/v1重新选择资源,不要手写 ID
RESOURCE_CATALOG_UNAVAILABLE资源库某类目录整体读取失败其余类仍可用;点「刷新」重试

完整的 188 个错误码见错误码参考。

建议的阅读顺序

先跑通一条最短路径

从快速开始走完安装 → 配模型 → 建 Agent → 发消息。四步都成功再回来看指南。

再按需要加能力

一次只加一类资源,加完立刻发一条会用到它的消息。同时加 MCP、Skill 和知识库,出问题时无法判断是哪一层。

每加一类资源都会产生新的修订版本,运行与调试会话里可以对照每一轮的差异。

最后才考虑上线

本地能跑通不代表云端资源可用。部署、托管运行时、知识库、记忆库都依赖 AgentEngine 控制面与凭证, 见产品与云端的关系。

相关参考

你想知道去哪里
修订版本、构建、运行分别冻结了什么Agent · Revision · Build · Run
三种运行时的能力差异三种运行时
资源绑定的数据形状资源与绑定
134 个控制协议 operation控制协议
环境变量与配置项配置参考
按错误码排障排障

本页导航