Agent 系统设计现状与架构指导

一、Agent 系统设计

当前 Agent 的设计已经不再只是“给大模型接几个工具”，也不是简单套用 ReAct、AutoGPT 或多 Agent 对话范式。真正可落地的 Agent 系统，本质上是一个由用户入口、系统编排、任务流程、模型运行时、工具接入、上下文管理、权限治理、产物管理和评测观测共同组成的业务执行系统。

早期很多 Agent Demo 的重点是展示模型能够自主规划、调用工具、完成任务。但在真实业务场景中，真正困难的部分往往不是让模型“看起来很智能”，而是让系统可控、可恢复、可审计、可评测、可持续迭代。例如，在企业资料驱动的工作台中，Agent 不仅要理解用户需求，还要知道该读取哪些资料、调用哪些工具、是否需要进入某个任务流程、是否有权限访问数据、是否能发布产物、失败后如何恢复、最终结果如何评价。

因此，本文讨论的 Agent 设计，不是狭义的 Agent 推理范式，也不是单纯的 prompt 设计，而是一个完整 Agent 系统如何从架构、模块、目录、实现边界和开发流程上进行设计。

本文的核心观点是：

一个完整 Agent 系统，应由 Entry 接收用户需求，由 System Orchestrator 识别意图并选择 workflow、agent、model、skill 和 tools，由 Context / Memory 构建任务上下文，由 Task Workflow 管理业务状态，由 Agent Runtime 执行 agent loop，由 Skill 提供任务方法，由 Tool / MCP 连接外部系统，由 Hook / Guardrail 进行生命周期拦截与校验，由 Artifact 层保存产物，由 UI 支持用户确认和修改，由 Observability / Eval 层持续评估效果。

这意味着，Agent 系统不是单一模块，而是多模块协同的工程体系。

---

二、Agent 设计现状：主流实践正在形成几个共识

2.1 从“万能 Agent”转向“任务型 Agent / Workflow”

早期 Agent 设计容易追求一个万能 Agent：用户提出任何需求，Agent 自己规划、自己调用工具、自己判断是否完成。但在实际业务中，这种方式很难保证稳定性。因为企业任务通常有明确流程、权限边界、产物格式和成功标准，不能完全依赖模型自由发挥。

当前更合理的设计方向是：将系统拆分为多个任务型 Agent 或任务型 Workflow。例如：

实验报表分析 Agent；
实验复盘生成 Workflow；
代码改动分析 Agent；
语雀文档写作 Skill；
论文调研 Workflow；
周报生成 Agent；
PRD 生成 Workflow；
发布语雀 Action。

这些能力可以被系统编排层统一调度，而不是全部塞进一个大 prompt 里。

2.2 从“LLM 自主决策”转向“代码控制全局，模型处理局部复杂性”

模型擅长处理模糊语义、复杂文本、总结分析、规划建议和局部工具选择，但不适合独立承担业务状态、权限审批、发布控制和失败恢复。

因此，合理架构应该是：

系统级编排由代码控制；
任务级 workflow 由状态机控制；
局部复杂决策交给 Agent loop；
外部动作通过 Tool / MCP 执行；
高风险操作通过 Hook / Guardrail / Permission 拦截；
最终产物通过 Artifact 层保存；
质量通过 Eval / Tracing 评估。

也就是说，Agent 不应该管理一切。Agent 负责局部智能，系统负责全局秩序。

2.3 从“工具调用”转向“工具环境设计”

在 Agent 系统中，工具不是简单的 API 包装。工具是 Agent 作用于外部世界的操作界面。工具设计的好坏会直接影响 Agent 的可靠性。

一个合格的工具需要有：

清晰的工具名；
准确的功能描述；
严格的输入 schema；
稳定的输出结构；
明确的读写权限；
合理的错误返回；
调用日志；
超时和重试机制；
敏感操作控制；
审计记录。

MCP 的出现，本质上是为了将外部工具、数据源、工作流标准化地暴露给 AI 应用。但即便采用 MCP，企业内部工具仍然需要自己封装，因为每个企业的数据、权限、流程和安全边界都不同。

2.4 从“聊天框”转向“工作台”

很多 Agent 产品失败的原因，不是模型能力不足，而是产品交互形态过于简单。单纯聊天框适合表达意图，但不适合承载复杂工作产出。

企业 Agent 工作台应该至少包含：

对话区；
任务面板；
资料选择区；
工具调用过程展示；
草稿编辑器；
引用来源展示；
确认发布按钮；
任务历史；
失败原因说明；
回滚或重新生成入口。

对于“生成实验复盘”“更新语雀文档”“创建 PRD”等任务，用户需要看到 Agent 做了什么、用了哪些资料、生成了什么草稿、是否可以修改、是否可以发布。这不是普通聊天机器人，而是人机协作工作台。

---

三、完整 Agent 系统的主链路

一个完整 Agent 系统的运行流程可以这样理解：

用户从 Web、CLI 或 API 输入一个需求后，系统首先进入 Entry / Command 层，将自然语言、按钮命令或显式 command 转换成标准请求；随后进入 System Orchestrator 层，由 router / orchestrator 判断任务类型、用户身份、上下文需求、风险等级，并决定是否创建任务 workflow、调用哪个 agent、使用哪个 model、加载哪些 skill、允许哪些 tools；接着由 Context / Memory 层构建当前任务所需的工作上下文，包括会话历史、用户偏好、项目资料、历史实验、知识库检索结果和当前任务状态；然后进入 Task Workflow 层，按照业务状态机推进任务；在某些节点中，workflow 会调用具体 agent，agent 根据自身 instructions、skill、model、tool 权限和上下文进入 agent loop，动态调用 MCP / tool 获取外部信息或执行动作；每次工具调用前后会经过 Hook / Guardrail / Permission 检查；最终结果会被写入 Artifact / Draft / Task State，并通过 UI 交给用户查看、编辑、确认或发布；全流程同时记录 tracing、tool call、成本、失败原因和评测指标。

这个流程可以抽象为：

用户输入
→ Entry / Command
→ System Orchestrator
→ Context / Memory
→ Task Workflow
→ Agent Runtime
→ Agent Loop
→ Tool / MCP
→ Hook / Guardrail
→ Artifact / UI
→ Observability / Eval

其中最关键的分工是：

System Orchestrator 负责系统级调度；
Task Workflow 负责业务状态流转；
Agent Runtime 负责模型和工具循环；
Agent Spec 定义具体执行者；
Skill 定义任务方法；
Tool / MCP 定义外部能力；
Context / Memory 定义 Agent 能看到什么；
Hook / Guardrail 定义边界与拦截；
Artifact 定义产物；
Observability / Eval 定义如何判断系统是否有效。

---

四、Agent 系统模块划分

模块	作用	典型实现	是否核心自建
Entry / Command 层	接收用户输入，包括聊天、按钮、命令、API	Web UI、CLI、API route、slash command	自建
System Orchestrator 层	识别意图，选择 workflow、agent、model、skill、tool scope	router、intent classifier、model policy、agent registry	核心自建
Task Workflow 层	管理具体业务任务的状态流转	workflow engine、state machine、task manager	核心自建
Agent Runtime 层	执行 agent loop，处理模型调用、tool calling、handoff	OpenAI Agents SDK、LangGraph、Pydantic AI	可复用
Agent Spec 层	定义每个 agent 的职责、模型、工具、输出、权限	YAML / Python config / DB config	自建配置
Skill / Procedure 层	定义某类任务的方法、模板、SOP、输出规范	skill.md、prompt template、examples	自建
Tool / MCP 层	封装外部系统能力	MCP server、API adapter、tool schema	标准可复用，企业工具自建
Context / Memory 层	决定 agent 当前能看到什么、记住什么	context builder、RAG、memory store、task state	核心自建
Hook / Guardrail 层	在生命周期节点做拦截、校验、补充、审计	pre_tool_use、post_tool_use、input/output guardrail	核心规则自建
Artifact 层	管理产物，如草稿、报告、PR、语雀文档	draft store、versioning、artifact DB	自建
Observability / Eval 层	记录、评测和改进系统	tracing、logs、eval、cost、latency	指标自建，工具可复用

这个划分不是为了制造复杂性，而是为了避免职责混乱。真实系统中，很多模块可以在 MVP 阶段合并实现，但概念边界必须清楚。

---

五、推荐工程目录结构

下面是一套适合企业资料工作台、实验复盘 Agent、语雀文档 Agent、代码分析 Agent 的后端目录结构。它不是唯一标准，但能较好地对应前面的系统模块。

agent-workbench/
  backend/
    app/

      entrypoints/
        chat_api.py              # 聊天入口：接收自然语言请求
        command_api.py           # 命令入口：接收按钮、slash command、显式动作
        task_api.py              # 任务入口：创建、查询、取消任务
        draft_api.py             # 草稿入口：读取、保存、修改、发布草稿

      orchestration/
        orchestrator.py          # 系统总编排：统一调度 intent、workflow、agent、context
        intent_router.py         # 意图识别：判断用户请求属于哪类任务
        model_policy.py          # 模型策略：根据任务难度、成本、风险选择模型
        agent_selector.py        # Agent 选择器：选择具体执行 Agent
        workflow_selector.py     # Workflow 选择器：判断是否进入任务流程

      workflows/
        base_workflow.py         # Workflow 基类：定义状态、节点、转移、失败处理
        experiment_report_workflow.py  # 今日实验报表分析流程
        experiment_review_workflow.py  # 实验复盘生成流程
        yuque_publish_workflow.py      # 语雀发布流程

      agents/
        agent_registry.py        # Agent 注册表：统一管理可用 Agent
        experiment_report_agent.py     # 实验报表分析 Agent
        experiment_review_agent.py     # 实验复盘生成 Agent
        code_analysis_agent.py         # 代码改动分析 Agent
        doc_writer_agent.py            # 文档写作 Agent

      skills/
        experiment_report_analysis/
          skill.md                # 实验报表分析方法说明
          output_template.md      # 输出模板
          examples.md             # 示例输入输出

        experiment_review/
          skill.md                # 实验复盘写作方法
          output_template.md      # 复盘文档模板
          checklist.md            # 复盘质量检查清单

        yuque_doc_writing/
          skill.md                # 语雀文档写作规范
          style_guide.md          # 团队文档风格指南

      context/
        context_builder.py        # 上下文构建器：决定本次 Agent 运行要看什么
        session_store.py          # 会话记忆：保存当前对话历史
        memory_store.py           # 长期记忆：保存用户偏好、项目背景、历史经验
        retrieval.py              # 检索模块：从文档库、向量库、知识库检索资料
        prompt_assembler.py       # Prompt 组装：将 instruction、skill、context、tool 信息组合

      tools/
        tool_registry.py          # 工具注册表：统一管理所有可调用工具
        permissions.py            # 工具权限：定义工具读写风险和可访问范围
        experiment_tools.py       # 实验平台工具：报表、指标、日志查询
        yuque_tools.py            # 语雀工具：搜索、读取、创建草稿、发布文档
        git_tools.py              # Git 工具：读取 diff、搜索代码、创建 PR

      mcp/
        experiment_mcp_server.py  # 实验平台 MCP Server
        yuque_mcp_server.py       # 语雀 MCP Server
        git_mcp_server.py         # Git MCP Server

      hooks/
        hook_manager.py           # Hook 管理器：注册和触发生命周期 hook
        pre_tool_use.py           # 工具调用前检查：权限、风险、参数
        post_tool_use.py          # 工具调用后处理：日志、结果校验、压缩
        before_agent_run.py       # Agent 运行前处理：补充上下文、检查状态
        after_agent_run.py        # Agent 运行后处理：保存结果、更新任务状态
        output_check.py           # 输出完成前检查：格式、引用、完整性

      guardrails/
        input_guardrails.py       # 输入校验：敏感请求、越权请求、注入风险
        output_guardrails.py      # 输出校验：格式、事实性、风险内容
        sensitive_data_check.py   # 敏感信息检查
        citation_check.py         # 引用和来源检查

      artifacts/
        draft_service.py          # 草稿服务：创建、保存、编辑草稿
        report_service.py         # 报告服务：管理实验分析报告和复盘报告
        version_service.py        # 版本服务：草稿版本、回滚、diff
        export_service.py         # 导出服务：导出 Markdown、Word、PDF 等

      domain/
        task_models.py            # 任务模型：Task、TaskRun、TaskState
        agent_models.py           # Agent 模型：AgentSpec、AgentRun
        tool_models.py            # 工具模型：ToolCall、ToolResult
        memory_models.py          # 记忆模型：Session、MemoryItem、ContextItem
        artifact_models.py        # 产物模型：Draft、Report、Document
        trace_models.py           # Trace 模型：Trace、Span、Cost、Latency

      observability/
        tracing.py                # Trace 记录：完整运行链路
        logging.py                # 日志记录：系统日志、错误日志
        evals.py                  # 评测：任务成功率、输出质量、工具使用质量
        cost_tracker.py           # 成本统计：token、模型调用、工具耗时

      infrastructure/
        database.py               # 数据库连接
        config.py                 # 配置管理
        auth.py                   # 用户身份和权限
        queue.py                  # 异步任务队列
        storage.py                # 文件和对象存储

---

六、目录设计的核心原则

6.1 entrypoints 只做入口，不做业务判断

entrypoints 负责接收用户请求，并将请求标准化。它不应该直接拼 prompt，不应该直接调用模型，也不应该决定调用哪个工具。

例如，用户输入：

“帮我查看今天的实验报表。”

chat_api.py 应该只做：

接收用户消息；
解析用户身份；
构造 Request 对象；
交给 orchestrator；
返回 orchestrator 的结果。

它不应该直接写：

调用 get_today_report；
调用 LLM；
生成分析结果。

这样做的原因是：入口层一旦承担业务逻辑，后续 Web、CLI、API、定时任务等入口就会重复实现逻辑，系统会很快失控。

6.2 orchestration 是系统级总控

orchestration 是最关键的系统调度层。它回答：

用户想做什么？
这个请求是简单问答还是复杂任务？
需要哪个 workflow？
需要哪个 agent？
用哪个模型？
加载哪个 skill？
允许哪些工具？
需要哪些上下文？
风险等级是什么？
是否需要人工确认？

它可以理解为系统的大脑外壳，但它不等同于 LLM。它可以由规则、分类模型、LLM、配置表共同实现。

例如：

{
  "intent": "view_today_experiment_report",
  "workflow": "experiment_report_workflow",
  "agent": "experiment_report_agent",
  "model": "cost_efficient_model",
  "skills": ["experiment_report_analysis"],
  "tools": ["get_today_report", "get_experiment_metrics", "compare_baseline"],
  "risk_level": "read_only"
}

这个决策结果会传给后续 workflow 和 agent runtime。

6.3 workflows 负责业务状态，不负责模型智能

workflow 管的是任务状态，而不是模型思考。

例如实验复盘生成可以定义为：

created；
collecting_context；
retrieving_metrics；
analyzing_logs；
analyzing_code_diff；
drafting；
waiting_review；
publishing；
completed；
failed。

每个状态都要定义：

输入是什么；
输出是什么；
调用哪个 agent 或 service；
成功条件是什么；
失败怎么办；
是否允许重试；
是否需要人工确认；
是否写审计记录。

workflow 可以调用 Agent，但不应该把状态藏进 prompt 里。任务是否进入 waiting_review，必须由数据库状态记录，而不是让模型说“我已经完成草稿，等待用户确认”。

6.4 agents 定义执行者，不定义完整业务流程

Agent 是一个执行者。每个 agent 应该有明确职责。

例如 experiment_report_agent：

职责：分析今日实验报表是否异常；
模型：中低成本模型；
工具：get_today_report、get_experiment_metrics、compare_baseline；
skill：experiment_report_analysis；
权限：read_only；
输出：结构化分析结论。

Agent 不应该拥有发布语雀的权限。因为“发布”是高风险动作，应由 workflow 和 permission 控制。

6.5 skills 是方法包，不是工具

Skill 可以理解为任务方法、SOP、模板、示例和约束的集合。它不是外部能力，也不是工具调用。

例如 experiment_review skill 可以定义：

如何说明实验背景；
如何对比 baseline；
如何解释 AUC、GAUC、loss、训练速度；
如何结合代码 diff 分析原因；
如何输出下一步计划；
什么情况必须标注风险；
最终文档结构是什么。

Skill 被加载到 Agent 的上下文中，指导 Agent 怎么完成任务。Agent 在执行过程中可以根据 skill 的方法调用 tools，但 skill 本身不直接执行外部动作。

6.6 tools 是外部能力，MCP 是标准化接入方式

Tool 是 Agent 能够调用的能力。

例如：

get_today_report；
get_experiment_metrics；
read_training_log；
search_yuque_doc；
create_yuque_draft；
publish_yuque_doc；
read_git_diff；
create_pull_request。

MCP 则是把这些工具标准化暴露给 Agent runtime 的协议或服务方式。

在 MVP 阶段，可以先写内部 tools，不一定一开始就 MCP 化。等工具稳定后，再将实验平台、语雀、Git、数据库等封装为 MCP server。

工具设计要特别重视权限分级：

read_only 工具：读取报表、读取文档、搜索代码；
write 工具：创建草稿、更新文档、创建 PR；
destructive 工具：删除、覆盖、发布、上线、通知大范围用户。

不同风险等级的工具，必须有不同的权限和 hook 检查。

6.7 context / memory 决定 Agent 能看到什么

Context / Memory 是 Agent 系统最容易被低估的部分。它不只是聊天记录。

应该拆成五类：

第一，Session Memory：当前对话历史。

第二，Task State Memory：当前任务状态，例如任务处于 drafting 还是 waiting_review。

第三，Working Context：本次任务临时需要的材料，例如今日实验报表、训练日志、代码 diff、语雀文档片段。

第四，Long-term Memory：长期保留的用户偏好、项目背景、历史经验，例如用户常关注 AUC、GAUC、训练速度和参数量。

第五，Artifact Memory：历史产物，例如曾经生成的复盘草稿、已发布文档、报告版本。

这五类 memory 不能混在一起。企业 Agent 如果把所有信息都直接塞进 prompt，会导致上下文污染、状态不可控、引用不可追踪、长期记忆难以更新。

context_builder.py 的职责就是：在每次 Agent 运行前，决定本轮应该向 Agent 提供哪些信息。

6.8 hooks 是生命周期拦截器，不是主流程

Hook 可以在 Agent 生命周期的关键节点触发：

Agent 运行前；
Agent 运行后；
工具调用前；
工具调用后；
输出完成前；
任务结束后。

Hook 的作用是：

检查权限；
阻断危险动作；
补充上下文；
记录日志；
校验工具返回；
检查输出格式；
触发审计。

但 Hook 不应该承载主流程。

判断标准是：

如果某逻辑是任务必经步骤，放进 workflow；
如果某逻辑是通用拦截、校验、审计、补充，放进 hook。

例如：

发布语雀前检查 workflow_state 是否为 approved，这是 hook；
实验复盘必须先读取指标再生成草稿，这是 workflow；
工具返回后记录 tool_call 日志，这是 hook；
草稿进入 waiting_review 状态，这是 workflow。

6.9 guardrails 是规则，hooks 是触发点

hook 和 guardrail 不完全一样。

Hook 负责“什么时候触发”；
Guardrail 负责“检查什么规则”。

例如：

pre_tool_use hook 触发后，可以调用 permission guardrail；
output_check hook 触发后，可以调用 citation guardrail；
before_agent_run hook 触发后，可以调用 input safety guardrail。

guardrails 目录中应该放具体规则，例如：

是否包含敏感信息；
是否引用了真实来源；
输出结构是否符合 schema；
是否存在 prompt injection 风险；
是否包含未授权数据。

6.10 artifacts 管理产物，不让产物散落在聊天记录里

Agent 的输出不能只保存在聊天消息里。

正式工作产物必须进入 Artifact 层，例如：

Draft；
Report；
YuqueDocument；
CodePatch；
PullRequest；
ExportedFile。

Artifact 层要支持：

保存；
编辑；
版本管理；
回滚；
导出；
发布；
审计。

这对于企业工作台非常重要。否则用户无法稳定编辑草稿，也无法追踪历史版本。

6.11 observability / eval 是系统能否持续优化的基础

Agent 系统必须从第一天设计观测和评测。

至少记录：

用户请求；
意图识别结果；
选择了哪个 workflow；
选择了哪个 agent；
使用了哪个模型；
加载了哪些 skill；
调用了哪些工具；
每次工具输入输出；
token 成本；
运行耗时；
失败原因；
用户是否采纳；
草稿是否被修改；
发布后是否回滚。

没有这些数据，就无法判断 Agent 到底哪里做得好、哪里做得差。

---

七、关键概念之间的关系

7.1 Agent 与 Workflow 的关系

Workflow 是业务流程，Agent 是执行者。

Workflow 规定任务怎么流转；
Agent 在某些节点中完成具体分析或生成任务。

例如：

实验复盘 workflow 中的 drafting 节点，可以调用 experiment_review_agent。

关系是：

workflow 控制全局；
agent 完成局部智能任务。

7.2 Agent Loop 与 Workflow 的关系

Agent loop 是 Agent 内部执行机制。

它解决的是：

下一步调用哪个工具；
工具参数是什么；
拿到结果后是否继续；
是否可以生成最终答案。

Workflow 解决的是：

任务现在处于什么状态；
下一阶段是什么；
是否需要用户确认；
是否可以发布；
失败后如何恢复。

ReAct 属于 Agent loop，不属于完整 workflow。

7.3 Skill 与 Prompt 的关系

Skill 可以粗略理解为 prompt 的工程化版本，但它比 prompt 更完整。

Skill 包括：

任务方法；
步骤；
模板；
示例；
检查清单；
风格规范；
约束条件。

所以 skill 不是一句提示词，而是一个可复用的任务方法包。

7.4 Command 与 Tool 的关系

Command 是用户入口，Tool 是外部能力。

例如：

用户点击“生成实验复盘”，这是 command；
系统调用 get_metrics，这是 tool；
用户点击“发布到语雀”，这是 command；
系统调用 publish_yuque_doc，这是 tool。

Command 不一定由 Agent 执行，很多 command 应该由后端 workflow 直接处理。

7.5 MCP 与 Tool 的关系

Tool 是单个能力；
MCP 是工具接入协议；
MCP Server 是一组工具的标准化服务。

例如：

Yuque MCP Server 可以提供 search_doc、read_doc、create_draft、publish_doc；
Experiment MCP Server 可以提供 get_today_report、get_metrics、read_training_log；
Git MCP Server 可以提供 read_diff、search_code、create_pr。

7.6 Hook 与 Workflow 的关系

Hook 可以影响流程，但不应该替代 workflow。

Hook 适合做拦截、校验、审计和补充；
Workflow 适合做主流程状态控制。

如果把主流程写在 hook 里，系统会变得难以理解和维护。

---

八、示例一：查看今天实验报表

用户输入：

“帮我查看今天的实验报表，看看有没有异常。”

8.1 Entry / Command

Web 聊天入口收到用户请求：

{
  "user_id": "u_001",
  "input": "帮我查看今天的实验报表，看看有没有异常",
  "channel": "web_chat"
}

entrypoints/chat_api.py 不做业务判断，只将请求交给 orchestrator。

8.2 System Orchestrator

orchestrator 判断：

任务类型：实验报表分析；
风险等级：只读；
是否需要 workflow：需要轻量 report workflow；
选择 Agent：experiment_report_agent；
选择模型：中低成本模型；
加载 Skill：experiment_report_analysis；
允许工具：get_today_report、get_experiment_metrics、compare_baseline、read_training_log。

内部决策可以表示为：

{
  "intent": "experiment_report_analysis",
  "workflow": "experiment_report_workflow",
  "agent": "experiment_report_agent",
  "model": "cost_efficient_model",
  "skills": ["experiment_report_analysis"],
  "tools": [
    "get_today_report",
    "get_experiment_metrics",
    "compare_baseline",
    "read_training_log"
  ],
  "risk_level": "read_only"
}

8.3 Context / Memory

context_builder 构建上下文：

当前日期；
用户所属项目；
默认实验空间；
最近关注的实验；
历史 baseline；
用户常关注指标；
当前会话上下文。

例如：

{
  "date": "today",
  "project": "recommendation_mixed_rank",
  "default_metrics": ["AUC", "GAUC", "loss", "step_time"],
  "recent_focus": ["hyformer-v2", "hyformer-v3"],
  "baseline": "jiejian_hunpai_base_new"
}

8.4 Task Workflow

experiment_report_workflow 可以是轻量状态机：

created
→ retrieving_report
→ analyzing
→ completed

每个阶段由 workflow 记录状态。

8.5 Agent Runtime 与 Agent Loop

workflow 调用 experiment_report_agent。

Agent 根据 skill 和上下文开始执行：

判断需要获取今日报表；
调用 get_today_report；
观察返回结果；
发现某个实验 GAUC 下降；
调用 compare_baseline；
必要时调用 read_training_log；
生成分析结论。

8.6 Tool / MCP

工具调用可能走内部 tools，也可能走 Experiment MCP Server。

例如：

get_today_report(date, project_id)；
compare_baseline(experiment_id, baseline_id)；
read_training_log(experiment_id)。

8.7 Hook / Guardrail

pre_tool_use 检查：

用户是否有权限读取该项目；
工具是否只读；
参数是否越权。

post_tool_use 检查：

返回是否为空；
指标字段是否完整；
是否记录 tool_call。

output_check 检查：

是否引用了真实指标；
是否说明异常原因；
是否给出下一步建议。

8.8 Artifact / UI

系统返回结果：

今日实验整体正常，但 hyformer-v3 的 GAUC 较 baseline 下降，训练 step time 增加。初步判断可能与新增序列模块导致 CPU 训练开销上升有关。建议继续查看对应训练日志和特征覆盖率。

同时保存：

TaskRun；
AgentRun；
ToolCall；
Trace；
AnalysisResult。

如果用户点击“生成复盘文档”，系统再进入 experiment_review_workflow。

---

九、示例二：生成实验复盘并发布语雀

用户输入：

“基于今天的实验结果，生成一篇实验复盘，确认后发布到语雀。”

这个任务比“查看报表”复杂，因为它涉及正式产物和发布动作。

9.1 System Orchestrator 决策

orchestrator 判断：

任务类型：实验复盘生成；
风险等级：中高；
需要完整 workflow；
需要多个工具；
需要草稿；
发布必须人工确认；
选择 experiment_review_agent；
加载 experiment_review skill 和 yuque_doc_writing skill。

9.2 Task Workflow

experiment_review_workflow 可以定义为：

created
→ collecting_context
→ retrieving_metrics
→ analyzing_logs
→ analyzing_code_diff
→ drafting
→ waiting_user_review
→ approved
→ publishing
→ published
→ archived

其中 waiting_user_review 是关键状态。Agent 生成草稿后不能直接发布。

9.3 Agent 设计

experiment_review_agent：

职责：生成实验复盘草稿；
模型：较强模型；
工具：get_metrics、read_training_log、read_git_diff、search_yuque_docs；
skill：experiment_review；
权限：只读 + create_draft；
禁止：publish_yuque_doc。

doc_writer_agent：

职责：将复盘内容整理成符合语雀风格的文档；
工具：search_yuque_docs、create_yuque_draft；
skill：yuque_doc_writing；
权限：可创建草稿，不可发布。

9.4 Skill 设计

experiment_review skill 应包含：

实验背景说明方法；
baseline 对比方法；
指标变化解释方法；
训练速度、参数量、资源消耗分析方法；
代码 diff 关联分析方法；
风险判断方法；
下一步实验计划写法；
输出模板。

yuque_doc_writing skill 应包含：

标题规范；
摘要规范；
小节结构；
表格格式；
语气风格；
引用规范；
结论写法。

9.5 Tool 设计

需要的工具包括：

get_experiment_metrics；
read_training_log；
read_git_diff；
search_yuque_docs；
create_yuque_draft；
publish_yuque_doc。

其中 publish_yuque_doc 是高风险工具，必须受 workflow state 和人工审批控制。

9.6 Hook 设计

pre_tool_use 对 publish_yuque_doc 检查：

workflow_state 是否为 approved；
当前用户是否有发布权限；
草稿是否存在；
草稿是否通过 citation_check；
是否记录审批人；
是否存在敏感信息。

如果任何条件不满足，直接拒绝工具调用。

post_tool_use 对 create_yuque_draft 检查：

是否成功创建草稿；
是否保存 draft_id；
是否写入 artifact；
是否更新 workflow 状态为 waiting_user_review。

9.7 Artifact 设计

Artifact 层保存：

复盘草稿；
草稿版本；
引用资料；
实验指标快照；
代码 diff 摘要；
发布记录；
语雀文档 URL。

用户在 UI 中可以编辑草稿，确认后点击“发布到语雀”。

9.8 Observability / Eval

系统记录：

整个 workflow 耗时；
模型成本；
工具调用次数；
草稿被用户修改比例；
发布是否成功；
是否发生权限阻断；
引用是否完整；
最终文档是否被采纳。

这些数据用于后续优化 Agent。

---

十、面向 AI / Codex 的实现指导方式

当前很多开发工作是通过和 AI 交互完成的。因此，不能只对 AI 说“帮我实现一个 Agent 系统”。这种需求过于宽泛，AI 很容易写出职责混乱的代码。

应该按模块给 AI 下达任务。

10.1 错误提示方式

不推荐这样说：

“帮我写一个可以查看实验报表、生成复盘、发布语雀的 Agent。”

这会导致 AI 把 workflow、agent、tool、prompt、权限、UI 全部混在一起。

10.2 正确提示方式

应该这样拆：

第一步，让 AI 实现 domain models：

“请先实现 Task、TaskRun、AgentRun、ToolCall、Draft、MemoryItem、Trace 等 Pydantic / SQLAlchemy 数据模型，不要写模型调用逻辑。”

第二步，让 AI 实现 tools：

“请实现 experiment_tools.py，包括 get_today_report、get_experiment_metrics、read_training_log。每个工具必须有输入 schema、输出 schema、错误返回和权限标记。”

第三步，让 AI 实现 context_builder：

“请实现 context_builder.py，输入 user_id、intent、task_id，输出 AgentRunContext。它需要组合 session memory、task state、retrieval results 和 user preferences。”

第四步，让 AI 实现 agent spec：

“请实现 experiment_report_agent.py，只定义 agent name、model、instructions、tools、skills、output_schema、permissions，不要写 workflow 状态机。”

第五步，让 AI 实现 workflow：

“请实现 experiment_report_workflow.py，状态包括 created、retrieving_report、analyzing、completed、failed。workflow 可以调用 experiment_report_agent，但状态必须由 workflow 显式更新。”

第六步，让 AI 实现 hook：

“请实现 pre_tool_use.py，用于检查工具权限、用户权限和 workflow state。不要在 hook 中写主业务流程。”

第七步，让 AI 实现 orchestrator：

“请实现 orchestrator.py，负责从用户输入识别 intent，选择 workflow、agent、model、skill 和 tool scope。不要在 orchestrator 中直接调用具体外部 API。”

10.3 给 AI 的总规则

每次让 AI 写代码时，都要强调：

不要把 workflow 写进 agent；
不要把工具实现写进 agent；
不要把权限判断只写在 prompt 中；
不要把状态只存在聊天上下文里；
不要让高风险动作由 LLM 自由决定；
不要让 hook 承担主流程；
不要把 skill 当成 tool；
不要把 command 当成 tool；
所有状态必须可持久化；
所有工具调用必须可追踪。

这样 AI 写出来的代码才会更接近真实系统。

---

十一、MVP 开发建议

对于你的场景，不建议一开始做完整企业 Agent 平台。建议从一个最小但正确的场景开始。

第一阶段：查看今天实验报表并分析异常。

实现内容：

Entry / chat_api；
orchestrator；
experiment_report_workflow；
experiment_report_agent；
experiment_report_analysis skill；
experiment tools；
context builder；
pre_tool_use hook；
basic tracing。

不做：

语雀发布；
复杂审批；
多 Agent 协作；
长期记忆；
完整 MCP；
复杂 UI。

第二阶段：生成实验复盘草稿。

新增：

experiment_review_workflow；
experiment_review_agent；
code_analysis_agent；
doc_writer_agent；
draft_service；
artifact versioning；
yuque_doc_writing skill。

第三阶段：发布语雀。

新增：

yuque_tools；
yuque_publish_workflow；
publish permission；
approval；
citation_check；
sensitive_data_check；
publish audit log。

第四阶段：平台化。

新增：

agent registry UI；
workflow registry；
tool registry；
MCP server；
eval dashboard；
cost dashboard；
多用户权限；
任务历史；
模板管理。

---

十二、核心设计原则总结

第一，先定义任务成功标准，再设计 Agent。

第二，能用 workflow 固定的流程，不要交给模型自由发挥。

第三，系统级编排、任务级 workflow、Agent loop 必须区分。

第四，Agent 是执行者，不是整个系统。

第五，Skill 是方法包，不是工具。

第六，Command 是入口，不是能力本身。

第七，Tool 是外部能力，MCP 是工具接入协议。

第八，Hook 是生命周期拦截器，不是主流程。

第九，Memory 必须拆分为 session、task state、working context、long-term memory 和 artifact history。

第十，高风险动作必须由权限、审批、状态机和 hook 共同控制。

第十一，正式产物必须进入 artifact 层，不能只留在聊天记录里。

第十二，观测和评测必须从第一天建设，否则 Agent 无法迭代。

---

十三、最终总结

一个完整 Agent 系统不是“一个大模型 + 一组工具”，而是一个可控的业务执行系统。

它的基本结构是：

Entry 接收请求；
Orchestrator 判断任务；
Context / Memory 构建上下文；
Workflow 管理状态；
Agent Runtime 执行循环；
Agent Spec 定义执行者；
Skill 提供方法；
Tool / MCP 连接外部系统；
Hook / Guardrail 管控风险；
Artifact 保存产物；
UI 支持人机协作；
Observability / Eval 评估效果。

其中，真正应该自建的是：

系统编排；
任务 workflow；
业务工具封装；
上下文策略；
权限审批；
产物管理；
评测指标；
产品交互。

可以优先复用的是：

模型 SDK；
Agent runtime；
tool calling 机制；
MCP 标准；
部分 tracing；
部分 session / memory 实现。

最终目标不是构建一个完全自治的万能 Agent，而是构建一个能稳定完成具体业务任务、可控、可观测、可评测、可迭代的 Agent 工作台。