F3 · 用户如何开发、调试和测试 Agent？ - Agent Development & Testing
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：03 · Agent Platform 应该提供哪些产品功能？ - Product Architecture
文档类型：专题研究 / 产品架构 / 交互与工程参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 应如何提供统一的开发、预览、调试、测试和评估体验，让用户能够定位 Agent 行为问题、比较配置变化、验证质量与风险，并将可追溯的测试证据交给发布流程？
专题导读
本篇属 Product Architecture。F1 研究 Agent 的创建，F2 研究 Agent 能力配置，F3 研究如何证明这些配置在具体任务中能够产生符合预期的行为。Agent 具有概率性输出、动态工具调用、外部依赖和多轮状态，开发体验不能只提供“聊天框试一下”；必须将开发草稿、预览执行、执行轨迹、测试用例、评估结果、回归比较与发布门禁组织为可持续的反馈闭环。
本篇从用户产品功能出发，说明开发者与业务构建者在界面中如何操作、看见什么、如何理解失败，以及这些产品行为如何映射到 P4 · Agent Development Services、P2 · Execution Plane、P3 · Agent Registry、P7 · Resource & Integration、P10 · Platform Data & Assets 和 P12 · Platform Governance。本文的架构、接口、数据结构、阈值及 Studio 示例均为参考设计；未执行真实部署、用户测试或性能实验。
研究结论
- F3 的最小闭环是选择 Draft Revision → 输入测试场景 → 启动隔离 Preview Run → 查看输出与 Trace → 标注问题 → 修改配置 → 重新测试。
- 预览、测试、评估、发布属于不同语义：预览观察行为；测试验证断言；评估衡量质量；发布由 F4 和治理策略最终决定。
- 调试对象应包含输出、决策过程的可观测事件、模型调用、工具调用、上下文引用、状态变化、成本与时延，但不应假设可以取得模型不可见的内部推理。
- 采用**测试用例（Test Case） - 测试集（Dataset） - 测试运行（Test Run） - 评估结果（Evaluation Result）**的可追溯模型；每次测试固定 Agent 草稿修订、评估器版本和输入数据版本。
- Agent 质量不是单一“准确率”：需分别验证任务完成、事实性、格式、工具正确性、安全性、稳定性、成本和延迟；不同指标不可简单互相替代。
- 模型评审（LLM-as-a-judge）可辅助评价开放式输出，但必须关注评审偏差、评审模型漂移、标注一致性与人工抽检。
- 对真实外部系统的写入操作应优先使用模拟器、沙箱或显式授权的测试连接；“Preview”标签本身不构成安全隔离。
- 发布门禁应使用可解释的规则和证据：关键安全测试失败、权限异常或必要评估缺失时，应阻止自动晋级，而非用平均得分掩盖高风险失败。
- 对研究报告 Studio，优先实现单案例预览、节点 Trace、结构化输出断言、引用核查、审核返工用例、回归比较，再建设复杂的自动化评测平台。
01 · 概念、职责与边界
1.1 什么是 Agent Development & Testing？
Agent Development & Testing 是面向平台用户的开发工作台与质量验证能力集合。它将 Agent 的配置变更转化为可观察、可比较、可复现条件尽可能明确的实验，并帮助用户判断是否适合进入发布环节。
| 概念 | 核心问题 | 典型产物 | 不等同于 |
|---|---|---|---|
| Development | 如何修改和完善 Agent？ | Draft Revision、配置差异 | 正式发布 |
| Preview | 当前配置执行起来是什么样？ | Preview Run、输出、Trace | 自动质量证明 |
| Debugging | 哪个环节出了问题？ | 时间线、输入输出、工具错误、标注 | 获取模型隐藏推理 |
| Testing | 是否满足明确的预期约束？ | 断言结果、测试报告 | 开放式质量评价的全部 |
| Evaluation | 效果在多大程度上符合目标？ | 指标、评分、人工复核 | 单次运行成功 |
| Regression | 新版本相较基线是否退化？ | 差异报告、门禁决策 | 确定性重放全部外部世界 |
1.2 与相邻专题的边界
- F1 · Agent Creation：建立 Agent 身份和初始草稿；F3 使用该草稿，不负责创建入口的主要体验。
- F2 · Agent Configuration：编辑角色、模型、工具、知识与运行约束；F3 对配置进行验证并给出修正反馈。
- F4 · Agent Publishing & Sharing：处理发布、共享、审批和可见性；F3 提供测试证据及建议，不代替发布授权。
- F6 · Agent Execution：面向正式任务的启动与操作；F3 主要面向受控开发环境和测试执行。
- F8 · Agent Monitoring：面向生产运行的持续监控；F3 面向开发期调试、诊断和比较。两者可以复用 Trace 基础设施。
- P4 · Agent Development Services：提供 Draft、Build、Test 的后端能力；F3 决定用户如何使用这些能力。
1.3 成功标准
产品不能以“有一个 Playground 页面”作为完成标准。最小成功应同时满足：用户能够指定被测试的草稿修订、运行至少一个真实或模拟案例、获得可解释的执行结果、定位失败位置、保存问题反馈，并在配置修改后比较两次结果。
02 · 用户角色、任务与使用场景
| 用户角色 | 典型目标 | 需要的能力 | 容易发生的误解 |
|---|---|---|---|
| 业务构建者 | 验证 Agent 是否按业务要求输出 | 预览对话、模板化测试、结果解释 | 单次回答正确代表长期可靠 |
| Agent 开发者 | 定位 Prompt、工具或状态问题 | 节点 Trace、输入快照、重放、版本差异 | 同一输入一定得到同一输出 |
| 工作流设计者 | 验证多 Agent 协作 | 节点级预览、故障注入、依赖追踪 | 子节点成功代表工作流成功 |
| 质量负责人 | 判断版本是否可发布 | 数据集、评估、回归、审批证据 | 一个综合分数足以判断风险 |
| 安全管理员 | 验证权限与数据边界 | 测试凭证、沙箱、红队案例、审计 | 测试环境天然无副作用 |
| 运营人员 | 发现用户任务中的失败模式 | 失败案例回收、脱敏、回归集 | 可以直接复制生产敏感数据 |
关键场景包括：首次创建后的试运行；修改 Prompt 后检查输出格式；替换模型后比较成本与质量；新增工具后检查调用权限；知识库更新后检查引用质量；工作流增加审核节点后验证返工；上线前执行回归；生产失败经脱敏后进入测试集。
03 · 产品能力架构与信息架构
3.1 功能模块
建议将 F3 组织为六个相互关联的区域：Playground、Trace Explorer、Test Cases、Datasets、Evaluations、Regression & Release Readiness。不要求初期全部成为独立页面，可先在一个开发工作台内用标签页实现。
flowchart LR
U[Agent Builder / Developer] --> W[Development Workbench]
W --> C[Draft Revision Selector]
W --> P[Playground]
W --> T[Test Cases & Datasets]
W --> E[Evaluation & Regression]
P --> PR[Preview Run]
T --> TR[Test Run]
PR --> EX[Execution Plane / Sandbox]
TR --> EX
EX --> O[Output + Trace + Metrics]
O --> D[Trace Explorer]
O --> E
E --> R[Release Readiness Evidence]
R -.-> F4[F4 Publishing]3.2 页面布局参考
左侧为 Agent 与 Draft Revision、测试案例和测试集导航；中间为输入与输出的双栏预览；右侧为 Trace 时间线、工具调用详情、结构化断言和问题标注；顶部显示运行模式、环境、模型与工具依赖、预算及权限提示。复杂指标和回归报告可以单独展开，避免初学者首次进入即面对大量调试字段。
3.3 用户应始终看见的上下文
每一次预览和测试必须清晰展示：Agent ID、Draft Revision、环境（mock/sandbox/live-test）、输入案例、开始时间、运行状态、模型配置、工具连接范围、成本估算或实际计量，以及是否产生外部副作用。界面不应把“本次运行成功”渲染成“全部测试通过”。
04 · 核心产品对象与关系
4.1 对象定义
| 对象 | 说明 | 版本或身份要求 |
|---|---|---|
| Agent Draft Revision | 某次可编辑配置的固定快照 | revision_id + content_digest |
| Test Case | 单一输入、前置条件和预期断言 | case_id + version |
| Test Dataset | 有组织的案例集合 | dataset_id + immutable snapshot |
| Preview Run | 人工交互式试运行 | preview_run_id |
| Test Run | 一次批量或单案例正式测试 | test_run_id + frozen context |
| Test Case Result | 某案例的一次执行及断言结果 | case_result_id + attempt |
| Trace | 执行事件及关联关系 | trace_id / span_id |
| Evaluator | 评分或判定方法 | evaluator_id + version |
| Evaluation Result | 指标值、理由、证据和不确定性 | evaluation_result_id |
| Baseline | 用于比较的既有版本/运行集合 | baseline_id |
| Test Report | 测试汇总与发布建议 | report_id + digest |
| Feedback | 人工标注、缺陷与修复关联 | feedback_id |
4.2 对象关系
erDiagram
AGENT_DRAFT_REVISION ||--o{ PREVIEW_RUN : executes
AGENT_DRAFT_REVISION ||--o{ TEST_RUN : tested_by
TEST_DATASET ||--o{ TEST_DATASET_ITEM : contains
TEST_CASE ||--o{ TEST_DATASET_ITEM : referenced_by
TEST_RUN ||--o{ TEST_CASE_RESULT : yields
TEST_CASE ||--o{ TEST_CASE_RESULT : executed_as
TEST_CASE_RESULT ||--o{ EVALUATION_RESULT : scored_by
EVALUATOR ||--o{ EVALUATION_RESULT : produces
PREVIEW_RUN ||--o{ TRACE_SPAN : emits
TEST_CASE_RESULT ||--o{ TRACE_SPAN : emits
TEST_RUN ||--o| TEST_REPORT : summarizes
TEST_CASE_RESULT ||--o{ FEEDBACK : annotated_with4.3 重要身份边界
测试用例的逻辑 ID 不等于其内容版本；测试集名称不等于某次测试使用的固定数据快照；草稿的当前修订不等于预览启动时的修订；Trace 是执行证据，不等于完整的内部模型状态。所有报告必须保存上述引用，以免事后无法解释分数变化。
05 · Playground：交互式预览
5.1 基本交互流程
用户选择 Agent 草稿修订和运行模式，输入任务或上传受控样例，确认资源授权与预算，启动 Preview Run，观察流式输出及执行事件，完成后查看 Trace 并可保存为测试用例。
sequenceDiagram
actor User
participant UI as Playground UI
participant DS as Development Service
participant CP as Control Plane
participant EP as Preview Worker
participant AS as Trace & Asset Service
User->>UI: 选择 Draft Revision / 输入案例
UI->>DS: 创建 Preview Run
DS->>CP: 校验授权、配额、环境、依赖
CP->>EP: 分配受控执行任务
EP-->>AS: 写入事件、Trace、产物
EP-->>UI: SSE/轮询输出进度
EP-->>DS: 完成 / 失败 / 取消
DS-->>UI: 汇总状态与指标
User->>UI: 保存为 Test Case / 标注问题5.2 三种运行模式
| 模式 | 用途 | 主要风险 | 推荐默认 |
|---|---|---|---|
| Mock | 验证逻辑、输出格式、工具调用计划 | 与真实服务行为存在差距 | 高风险工具的默认 |
| Sandbox | 使用隔离的真实或仿真服务 | 沙箱配置不完整、隔离失效 | 普通开发预览 |
| Live-test | 在明确许可下访问真实服务 | 写入副作用、费用和敏感数据 | 默认关闭，显式开启 |
对于发送邮件、修改 CRM、转账或删除数据等副作用工具，平台应在启动前明确显示目标系统和操作范围，使用测试身份、模拟器或审批机制；禁止仅依赖 Prompt 中的“不要真的执行”。
5.3 多轮会话与状态
预览需要支持清空会话、复制会话、从指定检查点继续（仅当底层引擎支持）、查看输入上下文摘要。新建会话必须避免意外继承前一轮测试的记忆；跨会话记忆若被启用，应明确提示作用域与清理方式。
5.4 流式体验与异常反馈
流式输出应区分模型文本、工具启动、工具结束、审批等待、错误与最终结果。网络断线时界面显示“连接中断，运行状态待确认”，而非直接认定任务失败。恢复时按事件游标拉取缺失事件，并去重展示。
06 · Trace Explorer：定位行为问题
6.1 最小可观测信息
Trace 至少应包含运行标识、节点/步骤标识、时间戳、耗时、输入输出摘要、模型与工具调用元数据、状态转移、错误类别、Token 与费用计量（若可获得）、关联资产引用。敏感数据须根据权限进行脱敏，Trace 不应默认展示全部原始 Prompt、访问令牌或个人数据。
6.2 建议的 Trace 结构
Preview Run
├── Agent Turn 1
│ ├── Context Assembly
│ ├── Model Call #1
│ ├── Tool Decision / Invocation
│ │ ├── Authorization Check
│ │ ├── Tool Request
│ │ └── Tool Response
│ ├── Model Call #2
│ └── Structured Output Validation
└── Final Result / Artifact注意：这里的“Tool Decision”是平台能够记录的工具调用选择与外显事件，不代表获取模型隐藏的逐 token 推理或内部思维链。平台应以可观测输入、输出和决策结果进行分析。
6.3 调试问题分类
| 问题类型 | 用户可见症状 | 优先排查的证据 |
|---|---|---|
| 指令冲突 | 输出风格、任务目标不一致 | 生效 Prompt 版本、优先级、配置差异 |
| 上下文缺失 | 忘记约束或历史信息 | Context Assembly、检索结果、截断提示 |
| 工具错误 | 调用失败或返回异常 | 参数、权限判定、响应码、超时 |
| 工具误用 | 调用不必要工具或越权请求 | 工具选择事件、权限策略、案例预期 |
| 知识错误 | 引用错误、事实不实 | 检索片段、证据引用、来源时间 |
| 输出格式错误 | JSON 解析失败、缺字段 | Schema、原始输出、校验器报告 |
| 状态问题 | 重复执行、错误恢复 | 检查点、状态转移、Attempt 链 |
| 性能问题 | 高延迟、高成本 | Span 耗时、模型调用次数、Token、队列等待 |
6.4 重放的边界
支持“以相同输入和固定配置重新运行”，不等于保证字节级一致。模型服务版本、采样随机性、检索索引、外部网页、时间、工具状态均可能改变。对可控组件可采用录制的工具响应进行确定性模拟；报告应标注哪些依赖被冻结、哪些依赖仍为动态。
07 · Test Case：将临时试运行转化为可验证案例
7.1 测试用例结构
测试用例至少包含输入、前置条件、运行模式、期望结果、断言规则、标签、风险等级和数据使用权限。开放式任务不应只写一个“标准答案”，还应定义不可违反的约束和可接受的质量范围。
schema_version: "1.0"
case_id: "topic-selection-001"
version: 3
name: "研究选题必须包含来源与可行性说明"
input:
task: "围绕非遗数字化提出三个研究选题"
context_asset_ref: "asset://test-fixtures/heritage-brief@sha256:example"
environment:
mode: "sandbox"
tool_policy: "read-only"
assertions:
- type: "json_schema"
schema_ref: "schema://topic-proposals/v2"
severity: "blocking"
- type: "array_length"
path: "$.proposals"
min: 3
max: 3
severity: "blocking"
- type: "human_rubric"
rubric_ref: "rubric://research-feasibility/v1"
severity: "advisory"
tags: ["topic", "format", "citation"]
risk_level: "medium"asset://、schema://、rubric:// 为本文自定义示例 URI，并非通用标准；摘要 example 仅作占位，不可用于真实校验。
7.2 断言类型
- 确定性断言：JSON Schema、必填字段、枚举值、长度、禁止词、权限拒绝、工具调用次数上限、资源预算。
- 语义断言：任务覆盖、事实一致性、证据充分性、引用支持度、回答相关性。
- 行为断言：是否在需要时调用工具、是否请求审批、是否避免未授权操作。
- 人工判定：研究价值、设计质量、语气、创新性、复杂推理的合理性。
应将“必须满足”的硬约束与“越高越好”的软指标分开。语义评估器不应被用来替代明确的权限或 Schema 校验。
7.3 用例来源与管理
用例可来自手工编写、模板、生产失败脱敏回收、专家标注及受控合成。合成数据需保留生成方法、筛选过程和局限，避免测试集仅覆盖模型自己擅长的样本。生产数据进入测试集前必须检查授权、隐私、保留期限和跨租户边界。
08 · Dataset：测试集设计与质量控制
8.1 数据集维度
建议按任务类别、输入长度、语言、难度、资源依赖、风险等级、失败模式、用户群体和边界条件进行分层抽样。Studio 的研究任务至少覆盖短问题、长需求、多文档输入、冲突资料、过时资料、缺乏证据、跨语言引用和需要人工审批的情形。
8.2 数据集分层
| 数据集 | 目的 | 更新策略 |
|---|---|---|
| Smoke | 快速验证关键路径是否可运行 | 每次关键配置变更 |
| Functional | 覆盖核心业务功能 | 随需求变更 |
| Regression | 防止历史缺陷重现 | 缺陷修复后追加 |
| Safety | 验证越权、注入和敏感信息保护 | 随威胁模型更新 |
| Benchmark | 用稳定样本比较版本表现 | 严格版本化，谨慎变更 |
| Exploratory | 发现未知失败模式 | 持续扩充，不直接混入基准 |
8.3 数据泄漏与过拟合
如果开发者反复针对公开测试题优化 Prompt，评估分数可能提高但真实泛化能力不变。应分离开发集与保留评估集，对保留集限制访问和运行频率；对于外部发布的 Benchmark 也需考虑训练数据污染风险。测试报告必须显示数据集版本、样本量、覆盖范围及排除条件。
09 · Evaluation：评估体系与指标
9.1 多维质量模型
| 维度 | 可操作指标 | 证据或测量方式 | 注意事项 |
|---|---|---|---|
| 任务完成 | 成功率、关键步骤完成率 | 人工标签、规则断言 | 成功定义应与业务一致 |
| 事实性 | 有依据陈述比例、事实错误率 | 来源核对、专家复核 | 来源存在不代表支持结论 |
| 引用质量 | 引用可访问率、主张支持率 | 引用解析与逐条核验 | 不可只检查链接格式 |
| 格式遵循 | Schema 通过率 | 确定性校验器 | 不反映内容质量 |
| 工具行为 | 合法调用率、参数正确率 | Trace 与策略日志 | 应区分未调用和错误调用 |
| 安全 | 高风险越权次数、敏感泄露次数 | 对抗案例与审计 | 关键失败不能平均抵消 |
| 稳定性 | 多次运行的通过率与方差 | 重复采样 | 需记录运行条件 |
| 效率 | P50/P95 时延、Token、成本 | 平台计量 | 需按任务难度分层 |
| 用户体验 | 可理解性、可修复性、完成时间 | 可用性研究 | 不能仅从日志推断 |
9.2 评估方法的选择
确定性指标优先使用程序校验；事实性和研究价值使用专家标注与证据核验；大规模开放式输出可采用经过校准的模型评审。对关键结论采用多方法交叉验证，避免单一评估器既生成结果又决定结果是否合格。
9.3 LLM-as-a-judge 的适用边界
模型评审适用于可明确描述评分准则的文本任务，但可能受回答长度、顺序、风格、模型偏好、语言和提示设计影响。平台应保存评分 Rubric、评审模型标识、评审 Prompt 版本、原始评分与理由，并对代表性样本进行人工复核。对于不可观察的真实世界正确性，不能仅凭模型自评作为事实核验。
9.4 统计解释
对于样本量为 n、通过数为 k 的二项指标，可报告 k/n 和适当置信区间；当样本很少时不要把 100% 通过解释为真实失败概率为零。比较两个版本时应尽量采用相同测试集、相同运行环境和配对设计，报告差值、波动及可能的混杂因素。时延与成本常有长尾，应同时观察分位数而非只看平均值。
10 · Regression：版本对比与发布门禁
10.1 比较对象
回归比较应至少固定：基线版本、候选 Draft Revision、数据集快照、评估器版本、工具模式、运行环境和时间窗口。若模型或检索资源为动态依赖，报告应显式标记不可完全控制的变化。
10.2 差异报告
对每个案例展示基线与候选的输出差异、断言结果、评估分数、工具行为、时延、成本和错误信息；汇总时区分新增通过、新增失败、持续失败与无法比较。为用户提供“跳转到失败 Trace”“复制案例”“提交缺陷”“重新运行”的直接操作。
10.3 参考发布门禁
release_readiness:
candidate_revision: "draft-rev-42"
dataset_snapshot: "dataset-snapshot-2026-11-01"
blocking_rules:
- "critical_safety_failures == 0"
- "schema_pass_rate >= 0.99"
- "required_cases_passed == true"
- "unauthorized_tool_invocations == 0"
advisory_rules:
- "quality_score_delta >= -0.02"
- "p95_latency_delta <= 0.20"
manual_approval_required: true上述数值仅用于演示策略表达方式，不是行业通用阈值。真实门槛须结合任务风险、数据规模、成本目标和历史基线制定。发布门禁应支持带理由、身份和有效期的受控豁免，但关键安全规则是否允许豁免应由治理策略明确规定。
10.4 测试通过仍不代表生产安全
预览环境与生产环境的凭证、流量、数据分布、外部服务可用性可能不同。F3 输出的是有条件的验证证据；F4 还需要进行发布权限、审批、版本冻结和环境准入检查。
11 · 多 Agent 与 Workflow 的测试
11.1 测试层级
| 层级 | 验证对象 | 示例 |
|---|---|---|
| 单 Agent | 选题 Agent 的结构化输出 | 三个选题均有研究问题 |
| 工具契约 | Search Tool 的请求/响应 | 超时、无结果、权限拒绝 |
| 节点集成 | 调研 Agent + 检索 | 引用与检索证据一致 |
| 协作协议 | 调研 → 审核 | 不通过时携带返工原因 |
| 工作流端到端 | 选题 → 调研 → 分析 → 审核 → 交付 | 审批后生成最终报告 |
| 故障恢复 | Worker 中断、重复事件 | 无重复交付、状态可恢复 |
11.2 状态与分支覆盖
工作流测试不只覆盖“所有节点一次成功”，还应包含审核拒绝、人工超时、工具不可用、取消、重试、循环次数上限、预算耗尽和部分产物生成。为每个分支定义预期状态转移及可见反馈。
11.3 人工审批模拟
测试可提供预设的 approve/reject/timeout 决策，确保状态机与恢复逻辑可重复验证。模拟审批不代表实际取得生产授权；真实执行仍须通过独立的身份与策略校验。
12 · 安全、权限与数据治理
12.1 测试环境隔离
开发预览需要明确的环境边界：独立的凭证作用域、网络访问控制、文件系统隔离、工具允许列表、计算与成本限制，以及对外部写操作的显式控制。沙箱强度取决于实际实现，不能把逻辑标记当作隔离机制。
12.2 Prompt Injection 与工具滥用测试
应测试恶意网页、文档、工具返回内容是否能诱导 Agent 忽略上级指令、泄露敏感信息或执行未授权工具。安全结论应基于实际权限执行结果，而不是 Agent 是否口头承诺遵守规则。攻击样本应仅在授权测试环境中使用。
12.3 敏感数据处理
Trace、测试输入、模型响应和导出报告可能包含个人信息、商业秘密与凭证。建议默认脱敏、按租户和项目授权、设置保留期限，并提供访问审计。导入生产失败案例时应先进行合法性、最小化和去标识化检查。
12.4 测试预算与资源治理
批量评估可产生显著模型成本，需提供运行前估算、最大调用数、并发上限、可取消执行和实际费用报告。预算耗尽时标记为“未完成/资源限制”，不能自动统计为业务失败或通过。
13 · 技术架构映射与数据流
13.1 产品到技术的映射
| F3 产品能力 | 主要后端依赖 | 关键契约 |
|---|---|---|
| Draft 选择与差异 | P3 Registry / P4 Development Services | revision_id、digest |
| Playground | P4 / P1 Control Plane / P2 Execution Plane | preview_run_id、environment |
| 工具模拟与沙箱 | P7 Resource & Integration / P12 Governance | tool policy、credential scope |
| Trace Explorer | P2 / P10 Data & Assets | trace_id、span_id、脱敏策略 |
| Test Dataset | P10 Data & Assets | dataset snapshot、ACL |
| Evaluation | P4 / 评估 Worker | evaluator version、metric schema |
| Regression | P4 / P3 / P10 | baseline、candidate、dataset digest |
| 发布证据 | P3 / F4 Publishing / P12 | report digest、policy decision |
13.2 推荐的初期技术结构
flowchart TB
UI[Agent Development Workbench]
API[Development API]
DB[(PostgreSQL: Test Metadata)]
OBJ[(Object Storage: Dataset / Trace / Report)]
Q[Durable Queue]
PW[Preview Worker]
EW[Evaluation Worker]
GOV[Governance & Resource Gateway]
UI --> API
API --> DB
API --> OBJ
API --> Q
Q --> PW
Q --> EW
PW --> GOV
PW --> OBJ
EW --> OBJ
EW --> DB
API --> UI初期可采用模块化单体承载 Development API、数据管理与评估编排，将 Preview Worker 独立运行以隔离执行风险；评估任务可先使用相同队列但独立任务类型。随着数据量和团队规模增长，再拆分评估服务与 Trace 查询服务。
14 · 接口与数据契约参考设计
14.1 创建 Preview Run
POST /v1/agents/{agent_id}/preview-runs
Idempotency-Key: 2db7b2f0-6f6c-4b5b-96cc-example
Content-Type: application/json
{
"draft_revision_id": "draft-rev-42",
"environment": "sandbox",
"input": {"message": "提出三个可研究的非遗数字化选题"},
"tool_mode": "read_only",
"max_cost_usd": 1.50
}{
"preview_run_id": "prv_01",
"status": "queued",
"draft_revision_id": "draft-rev-42",
"events_url": "/v1/preview-runs/prv_01/events"
}服务端必须从已授权的 Draft Revision 解析实际配置，并重新验证工具权限、资源配额和执行环境。请求中的 tool_mode 只是用户意图，不能覆盖服务端策略。
14.2 测试运行 API
POST /v1/test-cases
GET /v1/test-cases/{case_id}
POST /v1/test-datasets
POST /v1/test-runs
GET /v1/test-runs/{test_run_id}
GET /v1/test-runs/{test_run_id}/results
POST /v1/test-runs/{test_run_id}:cancel
GET /v1/preview-runs/{preview_run_id}/trace
POST /v1/test-runs/{test_run_id}/feedback
GET /v1/agents/{agent_id}/regression-comparisons以上路径为本文提出的参考接口，并非任何现有产品的实际 API。建议使用标准化错误响应、游标分页、幂等键、请求追踪 ID 和对象级授权；批量运行异步返回任务 ID，不应长期占用 HTTP 请求。
14.3 测试运行请求示例
{
"agent_id": "agent_topic",
"draft_revision_id": "draft-rev-42",
"dataset_snapshot_id": "ds_snap_08",
"environment": "sandbox",
"evaluator_versions": ["schema-validator@2", "research-rubric@1"],
"baseline_test_run_id": "tr_baseline_03",
"max_parallelism": 4,
"max_cost_usd": 25
}14.4 结果契约
{
"test_run_id": "tr_104",
"status": "completed_with_failures",
"agent_revision_id": "draft-rev-42",
"dataset_snapshot_id": "ds_snap_08",
"summary": {
"total": 20,
"passed": 16,
"failed": 3,
"inconclusive": 1
},
"report_asset_id": "asset_report_104",
"release_readiness": {
"decision": "blocked",
"blocking_reasons": ["critical_case_failed"]
}
}inconclusive 应包含环境不可用、评估器错误、证据不足等情况，不能直接并入“通过”。业务断言失败与基础设施失败应分开计数。
14.5 关系型数据模型（简化）
CREATE TABLE test_cases (
tenant_id UUID NOT NULL,
case_id UUID NOT NULL,
case_version INTEGER NOT NULL CHECK (case_version > 0),
name TEXT NOT NULL,
definition_json JSONB NOT NULL,
content_digest TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (tenant_id, case_id, case_version)
);
CREATE TABLE test_runs (
tenant_id UUID NOT NULL,
test_run_id UUID NOT NULL,
agent_id UUID NOT NULL,
draft_revision_id TEXT NOT NULL,
dataset_snapshot_id TEXT NOT NULL,
evaluator_lock_json JSONB NOT NULL,
status TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (tenant_id, test_run_id)
);
CREATE TABLE test_case_results (
tenant_id UUID NOT NULL,
result_id UUID NOT NULL,
test_run_id UUID NOT NULL,
case_id UUID NOT NULL,
case_version INTEGER NOT NULL,
attempt INTEGER NOT NULL DEFAULT 1,
status TEXT NOT NULL,
trace_ref TEXT,
metrics_json JSONB,
PRIMARY KEY (tenant_id, result_id),
FOREIGN KEY (tenant_id, test_run_id)
REFERENCES test_runs (tenant_id, test_run_id),
FOREIGN KEY (tenant_id, case_id, case_version)
REFERENCES test_cases (tenant_id, case_id, case_version)
);此 SQL 是说明关系的最小片段，未包含完整权限表、RLS 策略、数据集快照表、评估器表、索引、保留策略和分区方案。生产实现必须补齐这些约束，并评估大规模 Trace 的存储成本。
15 · Studio 贯穿案例：研究报告 Agent 的开发闭环
15.1 业务背景
Studio 采用多 Agent 研究报告流程：选题 Agent 提出候选方向，审核 Agent 检查研究价值和可行性，调研 Agent 收集资料，分析 Agent 形成论证，写作 Agent 输出报告，人工用户在关键节点确认。F3 需要让构建者独立调试每个 Agent，并验证跨节点交接与审核返工。
15.2 案例一：选题 Agent 的单案例预览
用户打开选题 Agent 的 Draft Revision，输入“为非遗数字化提出三个可执行研究选题”，选择只读检索沙箱并启动预览。界面展示模型输出、检索调用、引用和 Token 成本。系统检查输出是否符合 TopicProposal[] Schema、是否包含研究问题与可行性说明；用户对选题创新性进行人工评分，并将失败案例保存为回归用例。
15.3 案例二：审核 Agent 的返工逻辑
测试集包含“证据不足”“研究问题过宽”“资料时间过旧”“主题与需求不符”四类案例。预期行为是审核 Agent 输出结构化的 approve/revise/reject 决策和明确理由；当决策为 revise 时，Workflow 必须将修订意见传回对应 Agent，并限制最大返工次数，避免无限循环。
15.4 案例三：调研 Agent 的引用质量
对于检索返回的文档，测试应区分“引用链接存在”“引用页面可访问”“引用内容支持主张”三个层次。自动校验可以验证结构和部分可访问性，但对复杂研究主张仍需逐条核验和人工抽样。若来源不可访问，应标记为未验证，不应自动当作真实证据。
15.5 案例四：模型替换的回归比较
候选版本将模型 A 替换为模型 B，保持同一测试集、相同工具模式和尽可能一致的上下文条件。报告分别展示任务完成率、格式通过率、引用支持度、P95 时延和成本；若新模型更便宜但在关键引用核验案例中失败，不能仅因综合分数提高而自动发布。
15.6 案例五：外部副作用测试
未来 Studio 可能具有邮件分发、文件上传或发布能力。开发环境默认使用模拟发送服务；测试确认“未经审批不发送”“审批参数不匹配不发送”“重复回调不重复发送”。真实生产连接只允许在明确授权的专门测试环境中使用。
15.7 推荐的 Studio 页面结构
Studio / Agent / Development
├── Draft Revision Selector
├── Playground
│ ├── Input & Fixtures
│ ├── Output & Artifacts
│ └── Trace / Tool Calls / Cost
├── Test Cases
├── Test Datasets
├── Evaluation Runs
├── Regression Comparison
└── Release ReadinessStudio 初期不必实现完整的评估市场或复杂模型排行榜。最有价值的第一阶段是让开发者能解释“为什么选题 Agent 没有按预期工作”，并确保修复后不会重现同类错误。
16 · 开发路线与产品验收
16.1 分阶段实施
| 阶段 | 目标 | 核心交付 | 不应提前复杂化的内容 |
|---|---|---|---|
| M0 | 单案例可观察预览 | Draft 固定、Preview Run、输出、基础 Trace | 复杂评估器市场 |
| M1 | 基础测试闭环 | 保存用例、确定性断言、失败定位 | 大规模分布式调度 |
| M2 | 回归与质量门禁 | 测试集快照、批量运行、基线比较 | 全自动替代人工审核 |
| M3 | 多 Agent 工作流测试 | 节点测试、审批模拟、故障恢复 | 过早建设通用编排 DSL |
| M4 | 团队质量平台 | 权限、评估版本、审核记录、质量趋势 | 未验证的跨团队统一评分 |
16.2 产品验收标准
M0 应能够在不改变已发布版本的情况下预览指定草稿；记录每次预览的实际配置修订、运行环境和 Trace；工具异常能定位到具体调用；用户可从失败结果返回 F2 修改配置。M1 应允许将预览转为测试用例并重跑，报告通过/失败/未确定状态。M2 应提供稳定的数据集快照和候选/基线比较，并保留可核查的门禁依据。
16.3 核心产品指标
建议跟踪首次成功预览所需时间、从失败到定位的中位时间、问题修复后回归通过率、预览运行失败率、测试数据集覆盖度、评估成本、用户对错误解释的理解程度，以及生产缺陷被回归集覆盖的比例。指标定义需明确分母和采样口径，避免用“总运行次数”替代实际质量。
17 · 失败模式、权衡与局限
| 风险或失败模式 | 典型表现 | 缓解措施 | 剩余局限 |
|---|---|---|---|
| 单次预览误导 | 一次成功即发布 | 引导保存案例并批量测试 | 无法穷尽输入空间 |
| 模型输出不确定 | 重跑结果不同 | 重复采样、记录条件 | 仍难完全复现 |
| 评估器偏差 | 偏爱长答案或特定风格 | 人工校准、多评估器 | 评审仍有主观性 |
| 数据集污染 | 针对测试集过拟合 | 保留集、版本控制 | 不能完全识别污染 |
| 生产数据泄露 | Trace 保存敏感内容 | 脱敏、最小权限、保留策略 | 脱敏可能不完全 |
| 测试工具误写 | 预览修改真实系统 | 沙箱、只读默认、审批 | 依赖真实隔离配置 |
| 评估成本失控 | 大规模批量运行 | 预算预留、并发限制 | 外部服务价格会变化 |
| 依赖漂移 | 同一案例结果变动 | 锁版本、录制依赖、标注动态项 | 外部世界不可完全冻结 |
| 追踪信息过载 | 用户无法定位根因 | 分层 Trace、错误聚合 | 自动归因可能出错 |
| 门禁误判 | 重要安全失败被平均分掩盖 | 阻断规则与软指标分离 | 阈值需持续校准 |
| 取消与重试竞态 | 状态不一致、重复工具调用 | 幂等、状态机、执行租约 | 外部副作用无法总是撤销 |
| 版本错配 | 测试的不是发布版本 | 固定 Revision、发布时校验 Digest | 环境差异仍存在 |
18 · 工程验证矩阵（待执行）
下表是参考验收测试设计，并非已经完成的测试结果。测试应在实际实现后记录环境、步骤、证据、结论、缺陷与复测日期。
| ID | 测试主题 | 输入/故障注入 | 预期结果 |
|---|---|---|---|
| T01 | Draft 固定 | 预览启动后修改草稿 | 本次运行继续使用原 Revision |
| T02 | 未授权草稿 | 访问其他租户 Revision | 返回拒绝且不泄露配置 |
| T03 | 幂等创建 | 同一键重复提交 Preview | 不创建重复逻辑运行 |
| T04 | 沙箱只读 | Agent 尝试写外部资源 | 写操作被阻断并留痕 |
| T05 | 测试凭证 | 预览调用工具 | 仅使用允许的测试凭证 |
| T06 | 预算耗尽 | 超过运行预算 | 终止或拒绝后续调用，状态明确 |
| T07 | Trace 完整 | 多轮模型与工具调用 | 可关联 Run、Span、事件 |
| T08 | Trace 脱敏 | 工具返回敏感字段 | 非授权用户不可见敏感值 |
| T09 | SSE 重连 | 中途断网再连接 | 事件可恢复且不重复展示 |
| T10 | 工具超时 | 注入超时 | 显示超时类别及失败位置 |
| T11 | JSON Schema | 缺少必填字段 | 确定性断言失败 |
| T12 | 语义评分 | 输入评分 Rubric | 记录评估器版本和评分证据 |
| T13 | 评估器故障 | 评估器返回错误 | 标记 inconclusive，不算通过 |
| T14 | 测试集快照 | 运行中编辑数据集 | 当前运行继续使用原快照 |
| T15 | 数据集权限 | 跨租户引用测试数据 | 阻断访问 |
| T16 | 基线比较 | 两版本同集测试 | 输出逐案例差异及汇总 |
| T17 | 动态依赖 | 外部搜索内容变化 | 报告标记不可完全复现 |
| T18 | 多次采样 | 同一案例运行多次 | 保留各次结果与波动统计 |
| T19 | 审核返工 | 审核返回 revise | 正确路由返工并记录次数 |
| T20 | 循环上限 | 审核持续拒绝 | 达到上限后停止并报告 |
| T21 | 人工审批 | 模拟 approve/reject/timeout | 状态转移符合工作流契约 |
| T22 | Worker 故障 | 执行中终止 Worker | 任务可恢复或明确失败，不重复副作用 |
| T23 | 取消竞态 | 取消与完成同时发生 | 状态满足定义的终态规则 |
| T24 | Prompt Injection | 文档含恶意工具指令 | 未授权操作被执行层拒绝 |
| T25 | 引用核验 | 引用不支持主张 | 标记引用质量失败或待人工核验 |
| T26 | 版本漂移 | 评估器更新 | 旧报告仍可追溯旧评估器 |
| T27 | 发布门禁 | 关键安全案例失败 | 自动晋级被阻止 |
| T28 | 门禁豁免 | 非关键规则申请豁免 | 记录授权人、原因和期限 |
| T29 | 成本计量 | 多模型、多工具调用 | 成本按 Run 与案例归因 |
| T30 | 大样本分页 | 上千案例结果 | 分页查询稳定、可筛选 |
| T31 | 故障反馈 | 预览失败保存为 Case | 用例保留输入与脱敏 Trace 引用 |
| T32 | 发布一致性 | 测试后修改 Draft | 原报告不能作为新 Revision 的直接证据 |
| T33 | 生产失败回收 | 导入含敏感信息日志 | 未经脱敏与授权不得进入共享测试集 |
| T34 | 权限撤销 | 运行中撤销工具授权 | 后续工具调用重新授权并被拒绝 |
| T35 | 模拟/真实区分 | 切换 Live-test | 明确提示副作用、重新校验授权 |
| T36 | 质量与状态分离 | Run 成功但评估不通过 | 展示执行成功、质量失败两个状态 |
附录 A：参考文献与原始资料
以下资料优先选择标准、官方文档和原始研究。它们分别支持可观测性、评估、测试和安全的通用机制；并不意味着存在一个统一规定 Agent Development & Testing 产品界面的行业标准。本文的页面设计、对象组合和开发阶段是基于这些机制提出的工程推论。
- OpenTelemetry, Trace Semantic Conventions / Traces. opentelemetry.io/docs/concepts/signals/traces （用于理解 Span、Trace、上下文关联；Agent 专属字段需另行设计或参考现行语义约定。）
- OpenTelemetry, Semantic Conventions for Generative AI Systems. opentelemetry.io/docs/specs/semconv/gen-ai （用于生成式 AI 调用观测字段，注意规范版本与稳定性。）
- JSON Schema, Specification. json-schema.org/specification （用于结构化输出的确定性验证。）
- OpenAPI Initiative, OpenAPI Specification. spec.openapis.org/oas/latest.html （用于 API 契约与接口描述。）
- NIST, AI Risk Management Framework (AI RMF 1.0). nvlpubs.nist.gov/nistpubs/ai/nist.ai.100-1.pdf （用于风险管理、验证与治理原则。）
- NIST, AI RMF Generative AI Profile. nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf （用于生成式 AI 的风险识别与管理。）
- OWASP, Top 10 for Large Language Model Applications. genai.owasp.org/llm-top-10 （用于 Prompt Injection、敏感信息与工具风险测试分类。）
- LangChain, LangSmith Evaluation Documentation. docs.smith.langchain.com/evaluation （用于评估数据集、运行和反馈产品机制的实例研究。）
- LangChain, LangGraph Documentation. docs.langchain.com/oss/python/langgraph/overview （用于状态化 Agent/Workflow、持久化和恢复的实例研究。）
- OpenAI, Agents SDK Documentation. openai.github.io/openai-agents-python （用于 Agent 执行、Tracing、工具调用的实现案例；具体接口以实际版本为准。）
- OpenAI, Evals Repository. github.com/openai/evals （用于评估任务与基准构建的开源案例。）
- Temporal, Documentation. docs.temporal.io （用于持久化工作流、重试与故障恢复的工程参照。）
- PostgreSQL, Row Security Policies. www.postgresql.org/docs/current/ddl-rowsecurity.html （用于多租户测试数据的数据库隔离机制。）
- RFC 9110, HTTP Semantics. www.rfc-editor.org/rfc/rfc9110 （用于 API 状态与幂等语义。）
- RFC 9457, Problem Details for HTTP APIs. www.rfc-editor.org/rfc/rfc9457 （用于统一错误响应的标准参考。）
- Anthropic, Building Effective Agents. www.anthropic.com/engineering/building-effective-agents （用于 Agent 工作流模式的工程案例，非规范性标准。）
- Zheng et al., Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena (2023). arxiv.org/abs/2306.05685 （用于模型评审能力及偏差讨论。）
- Liu et al., G-Eval: NLG Evaluation using GPT-4 with Better Human Alignment (2023). arxiv.org/abs/2303.16634 （用于开放式文本模型评估的研究实例。）
- ISO/IEC/IEEE 29119 series, Software Testing. www.iso.org/standard/81290.html （测试概念与过程参考；具体标准范围和获取权限需另行核对。）
附录 B：研究证据、验证声明与适用边界
B.1 证据分级
- 标准与官方机制：JSON Schema、OpenAPI、HTTP、OpenTelemetry、PostgreSQL RLS 等可作为通用技术机制依据，但本文未对各标准最新修订逐条核验。
- 官方产品实现案例：LangSmith、LangGraph、OpenAI Agents SDK、Temporal 等用于说明已有实现路径，不应推导为所有 Agent Platform 必须采用同一产品结构。
- 研究论文：LLM-as-a-judge 相关论文用于说明评估方法及局限；不构成本文 Studio 指标阈值的实验依据。
- 本文参考设计：六区工作台、对象模型、接口路径、SQL 示例、门禁阈值、开发阶段和 Studio 案例均为设计建议，未经工程实测。
B.2 已核验、推论与未测试
可据通用机制说明：结构化断言可由 Schema 验证；执行 Trace 可由事件与 Span 组织；测试集版本化可改善比较条件；权限检查必须在服务端执行。工程推论：建议采用固定 Draft Revision、隔离 Preview Worker、批量评估队列与发布门禁。未测试设想：本文的 API、状态模型、数据结构、性能、成本、界面布局和验收测试，均未在 Studio 实际部署中验证。
B.3 研究局限
- 尚未对 Studio 当前代码库、技术栈和实际用户操作流程进行审计，因此阶段路线不是对现有系统的验收结论。
- 未进行基于真实数据集的模型对比、统计显著性测试、可用性测试或安全渗透测试。
- 外部文档与模型接口可能更新；实施前应核对对应版本、服务条款、成本与数据处理规则。
- 测试覆盖永远有限，不能把“测试通过”解释为 Agent 在所有输入与环境下安全、正确。
- 高风险领域的实际部署需要额外的领域专家评审、合规评估与独立安全验证。
B.4 与下一专题的衔接
F3 输出可追溯的测试报告与发布准备证据；F4 · 用户如何发布、共享和复用 Agent？ - Agent Publishing & Sharing 将进一步研究发布入口、版本冻结、可见性、审批、共享权限、复用和发布后的治理。F4 应使用 F3 的报告作为可选或必需的准入证据，但不应将“测试报告存在”直接等同于“允许发布”。