Agent 架构设计原则（v1）

核心结论：Agent 负责业务决策，Runtime 负责统一运行时，Business Script 负责确定性执行。

这套职责划分适合 Router Agent + Skill + Runtime 架构。无论外层使用 VS Code Copilot、Claude、ChatGPT、自研 Agent 服务还是其他 LLM 平台，核心运行时模型都可以保持稳定，只需要替换最外层的 Agent 调用方式。

1. 总体架构

User
  │
  ▼
Router Agent（LLM）
  │
  ▼
Runtime
  │
  ├── Job Manager
  ├── Workflow Manager
  ├── Checkpoint Manager
  ├── Trace Manager
  ├── Evidence Manager
  ├── Environment Manager
  └── Script Executor
  │
  ▼
Business Script

职责划分：

组件	核心职责
Router Agent	业务决策和流程编排
Runtime	所有运行时能力
Business Script	确定性业务执行

一句话：

Agent（业务决策）
        ↓
Runtime（统一运行时）
        ↓
Business Script（确定性执行）

2. 为什么需要这套架构

在很多 Agent 项目中，最容易出现的问题是：Agent、Skill、脚本和运行时职责混在一起。

典型表现包括：

• Agent 一边做业务判断，一边直接调用脚本；
• 每个 Skill 都自己处理 Python、Java、Node 等环境；
• 每个脚本都自己创建目录、写日志、写结果；
• Workflow 状态散落在终端输出、临时文件和 Agent 上下文里；
• 任务失败后不知道从哪里恢复；
• 异步任务完成后，Agent 无法可靠判断下一步；
• 证据文件、执行日志、错误信息没有统一引用。

这些问题短期看不明显，但当 Skill 数量增加、脚本变多、任务变长、执行环境变复杂后，会导致系统不可维护。

因此这套架构的核心目标是：

1. 职责清晰：Agent、Runtime、Script 各做各的事；
2. 可恢复：任何长任务都能从 Workflow / Checkpoint 恢复；
3. 可追踪：业务决策和运行时行为都有 Trace；
4. 可审计：结果、日志、证据都有稳定引用；
5. 可迁移：换 LLM 平台时，不推倒 Runtime 和 Script；
6. 可扩展：新增 Skill 时，不重复造运行时能力。

3. 典型反模式

3.1 Agent 直接执行脚本

反模式：

Agent
  ↓
python script.py

问题：

• Agent 要关心环境、路径、日志、失败处理；
• 每个 Skill 的执行方式都可能不同；
• 任务中断后难以恢复；
• stdout 成为事实来源，后续流程不稳定。

正确方式：

Agent
  ↓
Runtime
  ↓
Business Script

3.2 Script 写运行时状态

反模式：

script.py
  ├── 创建 run 目录
  ├── 写 workflow.json
  ├── 写 checkpoint.json
  ├── 写 trace.jsonl
  └── 写业务结果

问题：

• 每个脚本都要重复实现运行时能力；
• 状态格式容易不统一；
• 脚本越写越重，难以测试；
• 运行时能力无法集中升级。

正确方式：

Runtime
  ├── 管理目录、状态、日志、证据
  └── 调用只关心业务的 Script

3.3 Workflow 依赖终端输出

反模式：

读取 stdout 最后一行
↓
猜测任务是否完成
↓
决定下一步

正确方式：

workflow.json
  ↓
current_step / status / result_ref
  ↓
result.json
  ↓
决定下一步

终端输出是给人看的，Workflow 才是系统真相。

4. Agent 职责：只做业务

Agent 负责：

• 用户参数门禁；
• 业务参数校验；
• 路由选择；
• Skill 调度；
• 判断新 Workflow 或 Resume；
• 根据 result.json 判断下一步；
• 输出业务 Trace / Event。

Agent 不负责：

• 执行脚本；
• 检查 Python / Java；
• 管理 Job；
• 写 Workflow；
• 写 Checkpoint；
• 写 Trace；
• 写 Evidence；
• 写 stdout / stderr。

原则：

Agent 负责“想”，不负责“执行”。

5. Runtime 职责：统一运行时

Runtime 是整个系统的唯一运行入口。

Runtime 统一负责：

• Environment Discovery；
• Job 生命周期；
• 同步 / 异步执行；
• Workflow 更新；
• Checkpoint；
• Trace；
• Evidence；
• stdout / stderr；
• Result；
• Metrics。

所有业务脚本都必须经过 Runtime。

禁止：

Skill
  ↓
script.py

统一：

Skill
  ↓
Runtime
  ↓
script.py

6. Skill 职责

Skill 不执行脚本。

Skill 只负责定义：

• 业务逻辑；
• 脚本路径；
• 输入参数；
• 输出 Schema；
• timeout；
• 业务规则。

示例：

skill: sql_execute
script: scripts/oracle/sql_execute.py
runtime:
  mode: auto
  timeout: 60
input:
  sql_ref: ...
output:
  result_schema: ...

7. Business Script 职责

业务脚本只做：

• 读取输入；
• 执行业务；
• 输出 Result。

业务脚本不要做：

• 找 Python；
• 写 Workflow；
• 写 Trace；
• 写 Checkpoint；
• 写日志；
• 创建目录。

原则：

Script 只关心业务。

8. Runtime 生命周期

8.1 before_start

Runtime 负责：

• 生成 run_id；
• 生成 job_id；
• 创建目录；
• 写 input.json；
• 写 status=running；
• 写 workflow；
• 写 checkpoint；
• 写 trace(start)。

8.2 running

Runtime 负责：

• 启动 Script；
• stdout → Terminal；
• stdout → stdout.log；
• stderr → stderr.log。

8.3 finished

Runtime 负责：

• 读取 Script Result；
• 校验 Schema；
• 写 result.json；
• 写 metrics；
• 写 trace(end)；
• 更新 workflow；
• 更新 checkpoint；
• 保存 evidence。

8.4 failed

Runtime 负责：

• 写 error.json；
• 写 trace(failed)；
• 写 workflow(failed)；
• 写 checkpoint。

9. 同步 / 异步执行

同步或异步统一由 Runtime 决定。

Skill 不需要知道：

• 当前是同步执行；
• 还是异步执行。

Runtime 自动处理：

模式	Runtime 返回
同步	立即返回 result
异步	立即返回 accepted

10. 异步协议

Runtime 立即返回：

{
  "status": "accepted",
  "mode": "async",
  "job_id": "...",
  "result_ref": "..."
}

Agent 行为：

• 立即结束当前轮；
• 提示用户脚本完成后输入：继续。

业务脚本可以持续输出：

正在执行...
完成
请输入：继续

用户输入：

继续

Agent 恢复流程：

workflow.json
  ↓
result_ref
  ↓
result.json
  ↓
继续 Workflow

11. Workflow

Workflow 永远是真相。

Agent 恢复流程时，永远读取：

workflow.json
  ↓
current_step
  ↓
status
  ↓
result_ref

不要依赖：

终端输出

12. Checkpoint

Checkpoint 由 Runtime 自动写。

不要让 Agent 写 Checkpoint。

Checkpoint 记录：

• 当前 Step；
• 状态；
• 结果引用；
• 恢复位置。

13. Trace

Trace 分两类：

13.1 Business Trace

由 Agent 记录。

记录内容：

• 为什么进入这个 Skill；
• 为什么走这个 Route；
• 当前业务判断依据。

示例：

Schema 已准备完成。
进入 SQL Execute。

13.2 Runtime Trace

由 Runtime 记录。

记录内容：

• PID；
• ExitCode；
• Elapsed；
• stdout；
• stderr；
• started_at；
• finished_at。

14. Evidence

Agent 只声明需要保存什么 Evidence。

示例：

需要保存：query_result

Runtime 负责：

• 保存文件；
• 计算 hash；
• 记录路径；
• 返回引用。

15. Environment Discovery

Environment Discovery 统一由 Runtime 负责。

不要让每个脚本自己做：

where python
where java

Runtime 第一次扫描：

• Python；
• Java；
• Maven；
• Git；
• Node；
• Docker。

然后写入：

environment.json

后续统一读取：

environment.json

16. 目录建议

16.1 系统目录

.agent/
│
├── runtime/
│   ├── runtime.py
│   ├── runtime.ps1
│   ├── core/
│   ├── providers/
│   └── schemas/
│
├── skills/
│
├── scripts/
│
└── prompts/

16.2 运行数据目录

.idempotency/
│
├── environment/
│   └── environment.json
│
└── runs/
    └── <run_id>/
        │
        ├── workflow.json
        ├── checkpoint.json
        ├── trace.jsonl
        │
        ├── jobs/
        │   └── <job_id>/
        │       ├── input.json
        │       ├── status.json
        │       ├── result.json
        │       ├── stdout.log
        │       ├── stderr.log
        │       └── metrics.json
        │
        └── evidence/
            ├── schema/
            ├── sql/
            ├── query_result/
            └── logs/

17. 核心设计原则

17.1 Agent：做什么，下一步去哪

Agent 负责业务决策：

• 判断用户意图；
• 检查业务参数；
• 选择 Skill；
• 判断 Workflow 新建或恢复；
• 根据结果决定下一步。

17.2 Runtime：怎么执行，怎么恢复，怎么记录

Runtime 负责运行时能力：

• 执行；
• 恢复；
• 记录；
• 证据；
• 环境；
• 指标；
• 错误处理。

17.3 Script：把事情做完

Script 负责确定性业务逻辑：

• 输入；
• 执行；
• 输出。

18. 设计检查清单

设计 Skill、脚本或 Runtime 能力时，可以用下面清单自检。

18.1 Agent 检查

• [ ] Agent 是否只做业务判断？
• [ ] Agent 是否没有直接执行脚本？
• [ ] Agent 是否没有写 Workflow / Checkpoint / Evidence？
• [ ] Agent 是否通过 result.json 判断下一步？

18.2 Runtime 检查

• [ ] Runtime 是否是脚本执行唯一入口？
• [ ] Runtime 是否统一处理 stdout / stderr？
• [ ] Runtime 是否写入 workflow / checkpoint / trace / result / metrics？
• [ ] Runtime 是否支持同步和异步？
• [ ] Runtime 是否支持环境发现和复用？

18.3 Script 检查

• [ ] Script 是否只读取输入、执行业务、输出结果？
• [ ] Script 是否没有自行创建运行目录？
• [ ] Script 是否没有自行写 Workflow / Checkpoint / Trace？
• [ ] Script 输出是否符合 Result Schema？

19. 最小落地闭环示例

以 SQL 查询 Skill 为例，一个最小可落地闭环可以这样设计。

19.1 Skill 定义

skill: sql_execute
description: Execute approved SQL and save query result as evidence.
script: scripts/oracle/sql_execute.py
runtime:
  mode: auto
  timeout: 60
input:
  sql_ref: evidence/sql/query.sql
  datasource_ref: environment/datasource/oracle.json
output:
  result_schema: schemas/sql_execute.result.schema.json
rules:
  - only_allow_select: true
  - require_limit: true
  - save_result_as_evidence: query_result

19.2 Runtime 输入

{
  "run_id": "run_20260627_001",
  "job_id": "job_sql_001",
  "skill": "sql_execute",
  "script": "scripts/oracle/sql_execute.py",
  "timeout": 60,
  "input": {
    "sql_ref": ".idempotency/runs/run_20260627_001/evidence/sql/query.sql",
    "datasource_ref": ".idempotency/environment/datasource/oracle.json"
  }
}

19.3 Script 输出

业务脚本只输出业务结果，不关心 Workflow、Trace 和 Evidence。

{
  "status": "success",
  "row_count": 120,
  "columns": ["id", "name", "created_at"],
  "result_file": "query_result.csv"
}

19.4 Runtime 包装后的 result.json

{
  "status": "success",
  "run_id": "run_20260627_001",
  "job_id": "job_sql_001",
  "skill": "sql_execute",
  "started_at": "2026-06-27T10:00:00+08:00",
  "finished_at": "2026-06-27T10:00:05+08:00",
  "elapsed_ms": 5000,
  "output": {
    "row_count": 120,
    "columns": ["id", "name", "created_at"]
  },
  "evidence": [
    {
      "type": "query_result",
      "path": ".idempotency/runs/run_20260627_001/evidence/query_result/query_result.csv",
      "sha256": "..."
    }
  ]
}

20. 异步执行时序

User
  │
  │  发起长任务
  ▼
Agent
  │
  │  选择 Skill，提交 Runtime
  ▼
Runtime
  │
  │  创建 run/job/workflow/checkpoint
  │  启动脚本
  │
  ├──────────────► Business Script
  │                    │
  │                    │ stdout/stderr
  │                    ▼
  │              stdout.log / stderr.log
  │
  │  立即返回 accepted
  ▼
Agent
  │
  │  告诉用户：完成后输入“继续”
  ▼
User

用户输入“继续”后：

User
  │
  ▼
Agent
  │
  │  读取 workflow.json
  │  读取 result_ref
  │  读取 result.json
  ▼
继续下一步业务决策

21. 适用边界与演进路线

21.1 适合的场景

这套架构适合：

• 多 Skill 的 Agent 系统；
• 需要执行脚本的自动化系统；
• 有长任务、异步任务、可恢复任务的场景；
• 需要保存证据和审计记录的场景；
• 未来可能迁移 LLM 平台的系统。

21.2 不适合过度设计的场景

如果系统只是一次性 Prompt 工具、没有脚本执行、没有 Workflow，也不需要恢复和审计，那么完整 Runtime 可能过重。

可以先只落地最小子集：

• run_id / job_id；
• input.json；
• result.json；
• stdout.log / stderr.log；
• trace.jsonl。

21.3 演进路线

建议分阶段落地：

1. 阶段一：统一脚本入口
   所有 Skill 必须通过 Runtime 调用脚本。

2. 阶段二：统一结果协议
   所有脚本输出 Result Schema，Runtime 校验后写 result.json。

3. 阶段三：引入 Workflow / Checkpoint
   支持长流程和恢复。

4. 阶段四：引入 Evidence / Metrics / Trace
   支持审计、诊断和回放。

5. 阶段五：多 Runtime Provider
   支持本地、远程、容器、队列等不同执行后端。

22. 后续延伸

后续可以继续围绕 Runtime 的具体实现、Result Schema 设计、Workflow 状态机和 Evidence 存储规范展开。