F1 · 用户如何创建一个 Agent？ - Agent Creation
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：03 · Agent Platform 应该提供哪些产品功能？ - Product Architecture
文档类型：专题研究 / 产品架构 / 交互与工程参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 应如何让不同经验的用户从目标、模板或已有资产出发，创建具有稳定身份、明确归属、可编辑草稿和可验证初始配置的 Agent，并安全进入后续配置、测试与发布流程？
专题导读
本篇属 Product Architecture。Agent Creation 是用户进入 Agent 构建生命周期的第一步。它不仅是“新增一个 Agent”的按钮，更是将用户意图转化为平台可管理对象的产品流程。本篇以产品功能为主线，讨论创建入口、创建模式、信息收集、模板、AI 辅助创建、草稿、权限、异常恢复与成功判定，并映射至 Agent Registry、Agent Development Services 和平台治理能力。
研究范围限定在创建一个新的 Agent 定义及其初始草稿。对既有 Agent 的深度能力配置属于 F2，调试与测试属于 F3，发布与共享属于 F4，版本维护属于 F9。创建过程可以预填配置、进行轻量验证，但不应混同后续阶段的完整能力。本文的界面、数据结构、指标及验收标准均为参考设计与待验证假设，不代表已经完成用户测试或工程部署。
研究结论
- 创建成功的最小语义应是“获得稳定 Agent 身份和可恢复的初始草稿”，而不是“Agent 已经能够可靠完成任务”。
- 入口应同时服务初学者与专业构建者。 推荐至少提供空白创建、模板创建与复制已有 Agent；自然语言辅助生成可作为渐进增强，而非唯一入口。
- 首屏只收集最小必要信息。 名称、工作空间和创建方式足以启动多数场景；复杂模型、工具、知识与安全配置交给 F2/F3。
- 模板是受版本约束的可追溯输入。 复制模板时应明确哪些字段被复制、哪些凭证和权限不能继承。
- 创建与发布必须解耦。 创建草稿不授予运行权限，不自动部署，不产生公开共享链接。
- 前端校验改善体验，后端校验保证约束。 权限、租户归属、唯一性、配额和敏感资源引用必须由服务端最终裁决。
- AI 辅助创建的输出应视为建议性草稿。 需要用户核对目标、工具、数据范围、风险和可能的幻觉配置。
- 用户必须能恢复中断的创建流程。 对网络故障、重复提交、并发编辑和模板失效，应提供明确状态与可执行的恢复路径。
01 · 概念、职责与边界
1.1 Agent Creation 的产品定义
Agent Creation 是用户通过平台界面或受支持的开发入口，创建一个新的 Agent Definition，并生成初始 Draft 的过程。其可观察结果是：平台为 Agent 分配稳定标识，记录创建者和所属工作空间，保存可继续编辑的初始配置，并将用户引导至配置或预览步骤。
创建不等于配置完成，不等于构建通过，不等于发布，也不等于启动运行。 产品文案应避免使用“已上线”“已准备就绪”等暗示，除非满足对应阶段的明确条件。
1.2 与 F2 - F3 - F4、F9 的职责划分
| 专题 | 用户核心任务 | 与 F1 的交接 |
|---|---|---|
| F1 · Agent Creation | 创建身份与初始草稿 | 输出 agent_id、draft_id、创建来源 |
| F2 · Agent Configuration | 配置指令、模型、工具、知识与限制 | 接收草稿并持续编辑 |
| F3 · Agent Development & Testing | 预览、调试、测试、评价 | 消费草稿修订，生成测试结果 |
| F4 · Agent Publishing & Sharing | 校验、发布、共享、复用 | 只接受满足发布门槛的构建结果 |
| F9 · Agent Management | 维护既有 Agent、版本与生命周期 | 管理已创建对象，含归档与删除 |
1.3 技术组件映射
F1 是产品能力，不是一个独立的底层技术层。其典型依赖包括：P8 Platform API & SDK（创建接口）、P4 Agent Development Services（草稿生成和校验）、P3 Agent Registry（身份与版本边界）、P11 Multi-tenancy & Isolation（归属）、P12 Platform Governance（权限与配额）、P10 Platform Data & Assets（模板资产和附件引用）。
flowchart LR
U[用户 / Builder] --> UI[F1 创建向导]
UI --> API[Platform API]
API --> GOV[权限与配额检查]
API --> DEV[Development Services]
DEV --> REG[Agent Registry: Definition + Draft]
DEV --> TPL[Template Catalog]
REG --> UI
UI --> F2[F2 配置]
UI --> F3[F3 预览测试]02 · 用户类型、目标与使用情境
2.1 典型角色
| 用户类型 | 创建动机 | 主要障碍 | 产品支持重点 |
|---|---|---|---|
| 初次使用者 | 用 Agent 完成一个具体任务 | 不知道模型、工具、指令如何选 | 任务导向提问、模板、清晰默认值 |
| 业务构建者 | 将重复流程变成可复用能力 | 业务目标难转为配置 | 场景模板、示例输入输出、边界说明 |
| 专业开发者 | 精确控制 Agent 的定义 | 可视化表单表达能力不足 | 空白模式、导入 Manifest、API/SDK |
| 团队负责人 | 为团队创建标准 Agent | 归属、共享与版本难管理 | 工作空间、命名、所有权与治理提示 |
| 平台管理员 | 创建受控的组织模板 | 模板版本和安全默认值 | 模板审核、权限、政策与审计 |
角色不是固定的人群标签。同一用户可能在不同工作空间扮演不同角色，创建权限应由实际身份与资源上下文决定。
2.2 核心用户故事
- 作为新手，我希望描述任务目标并得到可修改的 Agent 草稿，以便不用理解全部底层术语也能开始。
- 作为构建者，我希望从可信模板创建 Agent，以便复用成熟结构，同时知道哪些设置需要重新授权。
- 作为开发者，我希望直接导入符合规范的 Manifest，以便保留精确配置并看到兼容性错误。
- 作为团队成员，我希望在正确的 Workspace 下创建 Agent，以便后续协作、权限和计费归属清楚。
- 作为管理员，我希望阻止无权用户创建 Agent 或越权继承模板权限，并保留审计证据。
2.3 Jobs-to-be-Done
当用户有一个值得自动化或委托的任务时，希望以尽可能少的步骤建立可迭代的 Agent 原型，并明确下一步如何验证它是否能完成任务。产品成功的关键不只是点击“创建”的转化率，还包括创建后能否理解对象、完成配置、启动第一次受控测试。
03 · 创建入口与信息架构
3.1 推荐入口
- 工作空间的 Agent 列表：
新建 Agent，强调归属明确。 - 项目页：
为当前项目创建 Agent，预填项目上下文但不隐式扩大访问权限。 - 模板库：
使用此模板，展示版本、来源、能力、所需权限和适用场景。 - 工作流编辑器：
新增 Agent 节点 → 创建 Agent，创建后返回工作流，并明确是否自动绑定。 - 开发者入口：API、SDK、CLI 或 Manifest 导入，与 UI 共用同一后端创建契约。
多入口应收敛到同一创建服务和统一对象语义；不要让不同入口生成无法相互管理的“临时 Agent”。
3.2 页面结构
建议使用三步式轻量向导：选择创建方式 → 提供基本信息 → 确认并创建。创建后进入 Agent 编辑工作台，页面展示未发布状态、下一步配置入口、预览测试入口及草稿保存状态。
| 页面区域 | 主要信息 | 设计约束 |
|---|---|---|
| 顶部上下文 | 工作空间、项目、返回路径 | 防止跨空间误创建 |
| 创建方式 | 空白、模板、复制、辅助生成、导入 | 可按用户权限隐藏或禁用 |
| 基础信息 | 名称、用途、描述（可选） | 避免首屏长表单 |
| 预览摘要 | 将创建的对象、来源、权限提示 | 不展示未获授权的敏感信息 |
| 主操作 | 创建草稿 | 提交中防重复点击 |
| 错误恢复 | 字段错误、权限问题、服务异常 | 明确保留已输入内容 |
3.3 首次创建与重复创建
首次创建可以显示简短示例与推荐模板；熟练用户可直接空白创建。应记录用户是否选择了“简化模式”，但不能用历史行为推断或放宽权限。避免强制用户先完成冗长的新手教程。
04 · 创建方式及适用边界
4.1 空白创建（Blank）
用户输入名称与可选用途，平台生成具有安全默认值的最小 Manifest。适用于专业用户、特殊场景和没有合适模板的任务。优点是可控，风险是用户不知道下一步需要配置哪些能力。
4.2 模板创建（From Template）
用户选择模板，查看功能说明、适用范围、维护者、版本、依赖和风险提示，然后生成独立的新 Agent 草稿。模板更新不应自动改写既有草稿；是否支持主动升级模板，需要单独定义迁移流程。
4.3 复制已有 Agent（Duplicate / Fork）
复制来源可以是本人或有权访问的团队 Agent。产品需清楚区分“创建副本”和“引用原 Agent”：前者产生新身份，后者沿用原身份或固定版本。复制时不得自动复制密钥明文、私有连接、运行历史、未授权数据和不可转移的权限授予。
4.4 自然语言辅助创建（AI-assisted）
用户描述目标、输入、期望输出、可用资源和约束，平台生成建议配置。生成结果需显示：已确定字段、推断字段、待确认字段、潜在权限需求和不支持的能力。模型生成内容不能直接当作已验证的工具定义、真实可用的连接或平台授权。
4.5 Manifest 导入（Import）
开发者可上传 JSON/YAML 定义或粘贴结构化内容。平台应先解析和校验，再生成草稿。未知字段、版本不兼容、不可解析依赖和跨租户引用应产生可定位错误，不应静默丢弃关键字段。
| 创建方式 | 适用人群 | 默认产物 | 主要风险 |
|---|---|---|---|
| 空白 | 专业用户 | 最小草稿 | 配置不完整 |
| 模板 | 初学者、业务构建者 | 模板派生草稿 | 依赖失效、错误继承 |
| 复制 | 团队协作 | 独立身份的副本 | 越权复制敏感资源 |
| AI 辅助 | 任务导向用户 | 待核对的建议草稿 | 虚构能力、过度授权 |
| 导入 | 开发者 | 结构化草稿 | Schema 不兼容、恶意内容 |
05 · 创建对象与信息模型
5.1 最小对象关系
erDiagram
TENANT ||--o{ WORKSPACE : contains
WORKSPACE ||--o{ AGENT_DEFINITION : owns
AGENT_DEFINITION ||--o{ AGENT_DRAFT : has
AGENT_DRAFT }o--o| TEMPLATE_VERSION : derived_from
AGENT_DEFINITION ||--o{ AGENT_VERSION : publishes
AGENT_DEFINITION {
uuid agent_id PK
uuid tenant_id
uuid workspace_id
string display_name
string lifecycle_status
datetime created_at
}
AGENT_DRAFT {
uuid draft_id PK
uuid agent_id FK
int revision
json manifest
string validation_status
}Agent Definition 的身份稳定，Draft 的内容可修改且有修订号，已发布 Agent Version 不可变。名称是展示字段，不宜用作全局主键；若产品提供 slug，应单独定义唯一性作用域和变更规则。
5.2 创建时最小字段
| 字段 | 必需 | 说明 |
|---|---|---|
workspace_id | 是 | 明确归属，由服务端授权 |
display_name | 是 | 面向用户的名称，长度与字符规则由产品定义 |
description | 否 | 任务目标和适用边界 |
creation_mode | 是 | blank/template/duplicate/assisted/import |
source_ref | 条件必需 | 模板、源 Agent 版本或导入来源 |
idempotency_key | 建议 | 防止网络重试重复创建 |
project_id | 否 | 可关联项目，但不能绕过 Workspace 归属 |
5.3 参考创建请求
{
"workspace_id": "ws_research",
"project_id": "prj_report_01",
"display_name": "选题 Agent",
"description": "为研究报告生成候选选题和选题理由",
"creation_mode": "template",
"source_ref": {
"template_id": "tpl_topic_research",
"template_version": "1.2.0"
}
}响应可返回 agent_id、draft_id、draft_revision、status: draft、next_actions。以上 ID 均为示例，字段并非外部通用标准。
5.4 安全默认 Manifest
schema_version: "1.0"
agent:
name: "选题 Agent"
purpose: "生成研究选题候选与理由"
instructions: "请补充任务范围、输入要求与质量标准"
model:
reference: null # 由 F2 配置；不隐式指定可用供应商
resources:
tools: []
knowledge: []
permissions:
requested_scopes: []
limits:
external_side_effects: false
lifecycle:
status: draft草稿中的“未配置”应被显式表示；不能为了让创建看起来成功而虚构可调用模型或自动开启高风险工具。external_side_effects: false 是示意性的产品策略字段，真正安全性取决于运行时执行点的授权。
06 · 创建流程与交互状态机
6.1 主路径
flowchart TD
A[选择 Workspace / Project] --> B[选择创建方式]
B --> C[填写最小信息]
C --> D[查看来源、权限与创建摘要]
D --> E[提交创建]
E --> F{服务端校验}
F -->|通过| G[原子创建 Definition + Draft]
F -->|不通过| H[定位错误并保留输入]
H --> C
G --> I[进入 Agent 编辑工作台]
I --> J[F2 配置]
I --> K[F3 预览测试]6.2 前端状态
| 状态 | 可见反馈 | 允许操作 |
|---|---|---|
idle | 未开始 | 选择方式 |
editing | 已填写内容 | 编辑、返回、取消 |
validating | 本地或服务端预校验 | 等待、取消 |
submitting | 正在创建 | 禁止重复提交 |
created | 草稿创建成功 | 进入编辑、复制链接 |
failed_recoverable | 可恢复错误 | 修改后重试 |
failed_terminal | 无权限或资源已撤销 | 返回、联系管理员 |
状态仅用于 UI 交互，不应与后端 Agent 生命周期状态混用。页面关闭不应触发已成功创建对象的隐式删除。
6.3 创建成功后的页面
应明确展示：Agent 名称、工作空间、草稿 / 未发布 徽标、创建来源、最后保存时间、需要配置的项目、下一步操作。推荐的主 CTA 是“继续配置”或“预览测试”，而不是“立即上线”。
07 · 模板产品体系
7.1 模板分类
可按任务场景（研究、客服、营销、数据分析）、能力结构（单 Agent、工具增强、知识增强）、角色（初学者、开发者）和组织来源（官方、团队、个人）组织。分类是发现机制，不是权限模型。
7.2 模板卡片最小信息
展示名称、解决的问题、典型输入与输出、维护者、版本、最近更新、所需资源、风险等级和适用限制。对“官方”“已验证”等标签应有真实审核依据，不能由发布者自行填写后直接获得平台背书。
7.3 模板版本与派生关系
创建时固定 template_id + template_version，记录派生来源；复制得到独立 Draft。若模板依赖某个工具版本已被撤销，平台应阻止自动启用该依赖，允许用户移除或替换后继续。已发布模板的版本不可变，但模板的发现标签和展示说明可以有独立的管理策略。
7.4 模板可信度
可设置分级：未经审核、结构校验通过、功能测试通过、组织审核通过。每一级应对应可核查的证据和有效期；“功能测试通过”也不保证在任意输入或外部环境下正确。
08 · AI 辅助创建的产品设计
8.1 建议的交互步骤
用户输入任务目标 → 系统追问缺失条件 → 生成草稿建议 → 展示结构化预览与不确定项 → 用户确认 → 保存草稿 → 进入 F2/F3。
建议至少询问：目标用户、典型输入、期望输出、允许使用的资料、是否需要外部工具、不能执行的动作。对于无需工具的简单任务，可以跳过高级问题。
8.2 生成结果的可解释性
将配置标记为三类：用户明确提供、系统建议、尚未确定。用户应能够逐字段接受、编辑或删除建议，特别是涉及模型成本、外部数据传输、工具权限和自动执行的字段。
8.3 提示注入与不可信输入
用户上传的模板、网页、附件及其他外部文本都可能包含指令性内容。AI 辅助创建时应将它们作为数据处理，不得让外部文本覆盖平台安全策略、自动添加高权限工具或触发未获授权的动作。生成 Manifest 仍需结构、语义和授权校验。
8.4 生成失败与回退
当模型不可用、超时或生成不合格结构时，应保留用户原始描述，允许重试、手动创建或改用模板。不能把模型生成失败等同于 Agent 创建失败，也不应无限重试产生不可控成本。
09 · 草稿、自动保存与协作
9.1 创建前暂存与创建后草稿
用户尚未提交创建时，浏览器本地暂存可以改善体验，但涉及敏感输入时应审慎使用；一旦提交成功，应以服务端 Agent Draft 为权威数据源。自动保存应显示明确状态（保存中、已保存、失败），避免让用户误以为数据已经持久化。
9.2 并发编辑
Draft 采用修订号或 ETag 乐观并发控制。若两个用户编辑同一草稿，后提交者应收到冲突提示，并可比较差异或刷新；不能静默覆盖。创建向导本身通常只涉及单用户，但进入协作编辑后需要此能力。
9.3 草稿与正式版本
草稿可多次修改，正式发布版本应在 P3 Registry 中冻结。草稿自动保存不等于自动发布。若用户退出编辑器，平台应提供草稿列表和恢复入口。
10 · 权限、治理与安全约束
10.1 创建权限
创建请求至少检查：主体是否具有工作空间创建权限、工作空间是否可用、租户是否处于允许创建状态、是否达到对象数量或其他配额。仅隐藏“新建”按钮不足以保证安全。
10.2 资源引用与权限继承
模板或副本可能引用私有知识库、模型连接、外部 API 和工具。创建新 Agent 时应区分“声明需要该资源”和“实际获授权使用该资源”；默认不继承原所有者的凭证和权限。对缺失授权的依赖显示 需要连接/授权。
10.3 内容安全与名称规范
名称和描述需限制长度、字符与渲染方式，防止 XSS、日志污染及界面溢出。对导入文件实施大小限制、解析超时、Schema 校验和文件类型检查。应避免在审计日志中记录完整密钥、私有提示词或敏感附件内容。
10.4 审计
建议记录 agent.created、draft.initialized、template.instantiated、agent.creation_failed 等事件，并关联主体、租户、工作空间、时间、请求 ID 与创建来源。审计事件应避免泄露敏感配置。
11 · 后端契约与数据一致性
11.1 参考 API
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /v1/workspaces/{id}/agents | 创建 Agent Definition 与初始 Draft |
GET | /v1/agent-templates | 搜索可用模板 |
GET | /v1/agent-templates/{id}/versions/{version} | 获取模板版本详情 |
POST | /v1/agent-drafts/validate | 创建前结构/语义校验（可选） |
GET | /v1/agents/{id} | 获取新建 Agent |
GET | /v1/agents/{id}/drafts/current | 获取当前草稿 |
上述接口为参考设计，不是任何现有框架的官方 API。模板校验不能代替正式创建时的服务端再次校验。
11.2 创建操作的原子性
Definition 与初始 Draft 应在一个数据库事务中建立，确保不会出现只有 Agent 身份、没有可编辑草稿的半成品。若模板展开涉及对象存储，需设计先写暂存工件、数据库提交、后续清理的补偿流程；不要假设数据库与对象存储天然支持分布式原子事务。
-- 简化示意，实际应补充外键、RLS、审计与索引
CREATE TABLE agent_definitions (
agent_id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
workspace_id UUID NOT NULL,
display_name TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'draft',
created_by UUID NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE agent_drafts (
draft_id UUID PRIMARY KEY,
agent_id UUID NOT NULL REFERENCES agent_definitions(agent_id),
revision BIGINT NOT NULL DEFAULT 1,
manifest JSONB NOT NULL,
source_template_id UUID,
source_template_version TEXT,
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);11.3 幂等与重复创建
网络超时可能发生在服务端已提交事务之后。推荐在创建接口支持 Idempotency-Key，按主体、工作空间、请求摘要和时间窗口去重；同一键对应不同请求体时返回冲突。服务端应保存最终结果，使客户端安全重试后得到同一个 agent_id。
11.4 错误契约
{
"error": {
"code": "TEMPLATE_DEPENDENCY_UNAVAILABLE",
"message": "模板依赖的资源当前不可用",
"field": "source_ref.template_version",
"retryable": false,
"request_id": "req_example"
}
}建议覆盖 FORBIDDEN、WORKSPACE_NOT_FOUND、QUOTA_EXCEEDED、VALIDATION_FAILED、SOURCE_ACCESS_REVOKED、VERSION_UNSUPPORTED、CONFLICT 和 SERVICE_UNAVAILABLE。对跨租户对象是否返回 403 或 404，应采用一致的防枚举策略。
12 · 关键异常路径与恢复设计
| 异常 | 可能原因 | 用户应看到的反馈 | 平台应保证 |
|---|---|---|---|
| 点击创建后超时 | 网络中断 | “创建结果待确认”，可安全重试 | 幂等不重复创建 |
| 模板失效 | 版本撤销 | 说明不可用依赖与替代方案 | 不隐式降级到其他版本 |
| 工作空间权限变化 | 成员被移除 | 提示无权创建 | 服务端最终授权 |
| 创建配额耗尽 | 数量限制 | 显示配额与处理方式 | 不越过配额 |
| 名称重复 | 命名策略冲突 | 建议修改名称 | 明确唯一性作用域 |
| 导入 Schema 不兼容 | 旧版定义 | 字段级错误与迁移建议 | 不静默丢字段 |
| AI 生成虚构工具 | 模型幻觉 | 标记工具不可用 | 不创建有效授权 |
| 重复提交 | 双击或重试 | 返回同一创建结果 | 幂等或唯一性约束 |
| 浏览器意外关闭 | 会话中断 | 恢复暂存或已保存草稿 | 明确持久化状态 |
| 来源 Agent 被删除 | 复制时失效 | 请求重新选择来源 | 不读取已撤销内容 |
| 依赖需要凭证 | 模板含私有连接 | 显示“待授权” | 不复制原凭证明文 |
| 数据库写入部分失败 | 事务错误 | 创建失败可重试 | 不遗留孤儿草稿 |
13 · Studio 贯穿案例：创建“选题 Agent”
13.1 业务场景
研究报告 Studio 的用户创建一个项目，计划通过“选题 → 选题审核 → 深度调研 → 分析 → 报告写作 → 人工确认”完成研究。用户需要创建负责生成候选研究题目的“选题 Agent”。
13.2 参考用户流程
- 在研究项目页面选择“添加 Agent → 创建新 Agent”。系统预填当前 Workspace 和 Project。
- 选择“从研究模板创建”，查看模板
Topic Research Agent的适用范围、输入输出与依赖要求。 - 输入名称“选题 Agent”，用途“针对指定研究领域提出有依据、可评估的候选题目”。
- 系统展示模板将带入的指令框架与输出结构；搜索工具标记为“需要授权”，不复制其他用户的连接。
- 用户确认创建，平台生成新的 Agent Definition 和 Draft，记录模板来源与版本。
- 进入 Agent 工作台，顶部显示“草稿·未发布”，并提示完善研究范围、候选数量、证据标准、输出 Schema 和模型选择。
- 用户在 F2 完善配置，在 F3 用测试课题运行 Preview，在 F4 经过校验后发布。
- Workflow 编辑器引用明确的 Agent Version，而不是不稳定的草稿。若用户选择继续编辑，已发布版本不被覆盖。
13.3 Studio 最小界面草图（信息层次）
研究项目 / Agent / 新建 Agent
────────────────────────────────────────────
工作空间：研究团队 项目：2026 文创研究
创建方式： [空白] [模板 ✓] [复制] [AI 辅助]
模板：研究选题助手 v1.2
用途：提出可研究、可比较的候选选题
依赖：搜索服务（需要后续授权）
名称：选题 Agent
描述：针对研究领域生成候选题目与理由
将创建：新的 Agent + 可编辑草稿
不会执行：发布、部署、外部工具调用
[取消] [创建并继续配置]
────────────────────────────────────────────13.4 与 Studio 现有功能的优先级
若 Studio 已具备模拟工作流的界面，F1 的首要价值是将“界面中的 Agent 卡片”变为真实、持久化、可配置的 Agent 对象。优先完成 Agent 列表、空白创建、模板创建、草稿保存和进入编辑页；不要在此阶段优先投入复杂 AI Builder、公共 Marketplace 或跨租户模板交易。
14 · 产品指标、验证方法与验收标准
14.1 指标体系
| 指标 | 定义 | 解释限制 |
|---|---|---|
| 创建完成率 | 开始创建会话中成功得到 Draft 的比例 | 需区分用户主动取消 |
| 首次创建耗时 | 从进入创建页到生成草稿的时长 | 速度快不代表配置质量高 |
| 首次测试转化率 | 创建后进入 F3 并完成至少一次 Preview 的比例 | 依赖 F2/F3 质量 |
| 模板创建占比 | 从模板派生的创建比例 | 不应机械追求越高越好 |
| 创建错误率 | 按错误类型分类的失败比例 | 应区分权限拒绝与系统故障 |
| 重复创建率 | 短时间同一用户产生近似重复 Agent 的比例 | 仅作诊断，避免误判正常复制 |
| 草稿恢复成功率 | 中断后恢复到正确草稿的比例 | 需要实际用户测试 |
| 错误理解率 | 用户能否准确解释创建失败原因 | 可通过任务访谈测量 |
指标应按新手/熟练用户、创建方式、工作空间类型分组观察，但不得将统计分组直接当作访问权限依据。初期不应凭空设定“行业标准”转化率。
14.2 参考可用性任务
邀请目标用户在不接受实时指导的情况下完成：空白创建、模板创建、复制 Agent、识别未发布状态、找回草稿、处理模板依赖失效。观察误解、误操作、停顿与回退。测试时应使用模拟凭证与隔离环境。
14.3 验收矩阵（待执行）
| ID | 测试场景 | 期望结果 |
|---|---|---|
| AC-01 | 有权限用户空白创建 | 生成 Definition + Draft |
| AC-02 | 无权限用户调用创建 API | 拒绝且不产生对象 |
| AC-03 | 跨租户工作空间 ID | 不泄露其他租户信息 |
| AC-04 | 工作空间创建配额耗尽 | 返回明确错误，无新对象 |
| AC-05 | 创建请求重复提交同一幂等键 | 返回同一 Agent ID |
| AC-06 | 相同幂等键不同请求体 | 返回冲突 |
| AC-07 | 模板版本被撤销 | 创建失败或进入明确受限流程 |
| AC-08 | 模板包含私有连接 | 不复制原用户凭证 |
| AC-09 | 模板依赖缺失 | 标记未满足依赖，不虚构连接 |
| AC-10 | 复制其他用户私有 Agent | 无授权则拒绝 |
| AC-11 | 复制已授权 Agent | 新 Agent ID，保留合法来源追踪 |
| AC-12 | 导入未知关键字段 | 返回可定位错误 |
| AC-13 | 导入超大文件 | 安全拒绝并限制资源消耗 |
| AC-14 | 名称包含 HTML/脚本 | 安全存储和转义显示 |
| AC-15 | AI 辅助生成不存在的工具 | 标记不可用，不自动授权 |
| AC-16 | AI 辅助创建超时 | 保留用户输入并允许回退 |
| AC-17 | 数据库事务中途失败 | 不出现孤儿 Definition/Draft |
| AC-18 | 创建成功但响应丢失 | 重试返回原结果 |
| AC-19 | 创建后刷新页面 | 草稿仍可恢复 |
| AC-20 | 两人并发编辑初始草稿 | 检测修订冲突 |
| AC-21 | 创建后查看状态 | 显示 Draft/未发布 |
| AC-22 | 创建后直接请求执行 | 未满足发布/运行条件则拒绝 |
| AC-23 | 关联 Project 不属于 Workspace | 拒绝不一致归属 |
| AC-24 | 创建审计事件 | 包含主体、对象、时间和请求 ID |
| AC-25 | 模板更新后查看既有草稿 | 既有草稿不被静默覆盖 |
| AC-26 | 草稿中引用失效模型 | 提示待配置，不假定可运行 |
| AC-27 | 用户取消创建 | 不误删已存在 Agent |
| AC-28 | 后端服务暂时不可用 | 可恢复错误，不产生重复对象 |
上述均为建议测试用例，未实际执行。实际验收应补充自动化接口测试、权限测试、可用性测试与数据一致性测试的记录。
15 · 分阶段建设路线
| 阶段 | 范围 | 退出标准 |
|---|---|---|
| M0 · 可用骨架 | Agent 列表、空白创建、初始草稿、工作空间归属 | 可持久化创建并继续编辑 |
| M1 · 模板与恢复 | 模板派生、草稿恢复、创建错误与幂等 | 可稳定完成主要创建路径 |
| M2 · 专业创建 | 复制、Manifest 导入、依赖校验 | 专业用户可保留结构化配置 |
| M3 · 智能辅助 | 自然语言生成、字段来源标注、风险提示 | AI 建议可核对、可修改、可回退 |
| M4 · 团队生态 | 组织模板、审批、跨工作空间分发 | 权限、版本与治理机制可验证 |
阶段顺序是针对早期 Studio 的参考规划，不代表所有 Agent Platform 都应按同一顺序实施。对于 API-first 平台，可以将 Manifest 导入提前；对于面向非技术用户的平台，可以将模板和 AI 辅助创建提前，但不能跳过安全与版本边界。
16 · 局限、开放问题与后续专题
本篇尚未基于真实用户样本验证创建流程的理解成本，也未对模板质量、AI 辅助创建准确率或不同信息架构做 A/B 测试。未实现任何接口或数据库迁移，SQL 与 API 均为概念性参考。Agent Manifest 的字段命名是内部示例，不构成行业统一规范。
需要后续决策的问题包括：是否允许同一 Agent 存在多个并行 Draft；Agent 是否必须绑定 Project；模板是否可跨组织共享；复制时哪些非敏感依赖可保留；是否支持草稿协作编辑；是否将 AI 辅助创建作为默认入口；何时引入公共模板市场。上述选择应由产品目标、用户研究、安全要求和平台成熟度共同决定。
与后续专题衔接： F2 研究创建后的能力配置与修改；F3 研究开发调试测试；F4 研究发布共享；F5 研究工作空间与项目；F9 研究 Agent 生命周期与版本维护。
附录 A：参考文献与原始资料
以下资料用于支持文中的 API 契约、数据建模、安全设计和用户交互原则；它们不直接定义统一的 Agent Creation 行业标准。产品方案与对象字段属于本文综合推导。
- OpenAPI Initiative. OpenAPI Specification. spec.openapis.org/oas/latest.html - - 参考 HTTP API 契约描述。
- JSON Schema. JSON Schema Specification. json-schema.org/specification - - 参考 Manifest 结构校验。
- PostgreSQL Global Development Group. PostgreSQL Documentation: Transactions. www.postgresql.org/docs/current/tutorial-transactions.html - - 参考原子创建与事务语义。
- PostgreSQL Global Development Group. PostgreSQL Documentation: Row Security Policies. www.postgresql.org/docs/current/ddl-rowsecurity.html - - 参考多租户数据库访问边界。
- OWASP. Top 10 for Large Language Model Applications. owasp.org/www-project-top-10-for-large-language-model-applications - - 参考 LLM 应用风险、提示注入与敏感信息保护。
- NIST. Secure Software Development Framework (SSDF), SP 800-218. csrc.nist.gov/pubs/sp/800/218/final - - 参考安全开发和供应链流程。
- W3C. Web Content Accessibility Guidelines (WCAG) 2.2. www.w3.org/TR/WCAG22 - - 参考表单、错误提示和可访问性。
- Nielsen Norman Group. 10 Usability Heuristics for User Interface Design. www.nngroup.com/articles/ten-usability-heuristics - - 参考系统状态可见性、错误预防与恢复。
- OpenAI. Agents SDK Documentation. openai.github.io/openai-agents-python - - 作为代码优先 Agent 定义的产品与开发实践参考。
- LangChain. LangGraph Documentation. docs.langchain.com/oss/python/langgraph/overview - - 作为图式 Agent 工作流与开发流程的参考。
- Dify. Documentation. docs.dify.ai - - 作为可视化 AI 应用构建与模板体验的对照案例。
- Git. Git Documentation. git-scm.com/docs - - 参考版本、复制与来源追踪概念，注意 Git 语义不直接等同于 Agent Registry。
附录 B：研究证据、验证声明与适用边界
已知规范性依据： OpenAPI、JSON Schema、PostgreSQL 事务/RLS、WCAG 等官方文档描述了相应技术规范或实现能力；它们只能支持对应层面的结论，不代表认可本文完整产品方案。
设计推论： 创建模式组合、三步向导、对象关系、API 字段、状态机、Studio 示例、指标体系和建设阶段均是结合 Agent Platform 需求推导出的参考设计，必须根据目标用户与现有系统调整。
未验证内容： 本文未实际运行创建 API、数据库事务、模板导入、AI 辅助生成、用户访谈或可用性测试。AC-01 - AC-28 均为拟议测试，不应被视为测试通过记录。外部文档地址用于后续核验，未在本篇中声称已逐条实时检查其最新版本。
适用边界： 本篇面向具有 Agent Definition、Draft、Version、Workspace 概念的平台型产品。对单用户脚本或完全代码化框架，部分创建 UI、模板治理和组织流程可以简化；但身份、版本、权限、可恢复性与来源追踪仍值得按风险水平评估。