Chen's Notes
0%

我进入 AI 领域的方式，以及 Agent SDK 的设计

背景

这篇文章讨论的是怎么快速切入一个新领域。这里使用的方法是 实事求是，对应三个步骤：调查、实践、复盘迭代。本文选择的实际例子，是 AI 领域里的 agent 工程。

  • 调查：进入 AI 领域时面对什么问题，准备怎么切入，以及基于调查形成了哪些初步推断
  • 结论：经过调查和实践，当前形成了哪些核心判断
  • 实践展开：通过一个实际的 agent 工程，说明这些判断是如何被推导、设计和验证的

英文版本：How I Entered AI and Designed an Agent SDK

调查

探索和理解 AI 是什么

  • 理解 AI 的基本原理与能力边界
  • 理解 prompt、agent、context、mcp 等工程对象
  • 理解 AI 在真实落地中的有效范围和失控点

基于 AI 的特性，推导人与 AI 的协作方式

  • 判断哪些问题适合 AI，哪些问题必须由人主导
  • 重新分配工程师在需求识别、问题拆解、架构设计、执行控制中的重心
  • 形成一套人与 AI 协作完成工程工作的基本方法

在实践中验证这些判断，并沉淀成工具

  • 用实际项目验证前面的判断是否成立
  • 把有效的方法沉淀成流程、runtime 和工具
  • 让这些能力可复用、可扩展、可持续演进

AI 项目复盘结论

  • AI 技术角度：AI 更像一批能力很强但并不完全受控的执行体。关键不是盲目依赖它，而是先定义目标、路径和约束，再把高不确定问题逐步压缩成更具体、更确定的问题。
  • 个人能力重心角度：在 AI 时代，个人能力的重点会越来越落在需求识别、问题定义、问题拆解、方案设计、过程控制和结果验收这些更上游的位置。
  • 项目实践角度：几个不同方向的项目都在验证同一件事：AI 更适合进入那些已经被拆解、被约束、被文档和流程承接的系统，而不是无边界地替代完整工作过程。
项目名字 领域 主要目标 当前结论
agent_runtime infra 领域 为 agent 系统提供共享 runtime 基座，统一 session、orchestration、context、tooling、model、observability、storage 等基础能力 AI 工程要稳定落地，核心不只是模型调用，而是可控运行时
sdlc 软件工程交付领域 打通从需求、设计、实现到验证的阶段化交付链路，并支持基于已有产物持续更新 AI 更适合进入被拆解、被约束、被文档承接的工程流程，而不是直接替代完整交付过程
travel 方向项目 产品业务领域 在真实用户场景下验证 AI 对复杂需求识别、规划和持续承接的能力 AI 提升了信息处理和方案生成效率，但真正难的仍然是复杂场景里的需求识别和问题定义

实践展开

我为什么从 Agent SDK 切入

结论：先做 Agent SDK，因为它最适合承接 AI 工程里的共性问题。

  • 运行时承载
  • 接口边界
  • 编排控制
  • 上下文治理
  • 工具接入
  • 模型接入
  • 权限控制
  • 可观测性

它足够基础，足够通用，也最适合作为后续多个项目复用的共享底座。

SDK 设计

需求问题定义与拆解

从需求角度看，这套 Agent SDK 要解决的，不是某个单点功能问题，而是一组 agent 系统在真实工程里反复出现的共性需求。目标是把这些需求收敛成共享基础能力，让上层项目不再重复建设运行时底座，而是基于统一边界继续扩展。

  • 统一的运行时承载能力需求：agent 系统不能只停留在一次性模型调用。只要进入多轮对话、工具调用、状态承接和结果回写场景，就需要有一套统一能力来承接会话生命周期、执行过程和运行状态。否则每个项目都要各自处理这些基础问题，成本高，也难以保持一致。

  • 稳定的外部接口边界需求：上层项目需要的是稳定、清晰、可复用的接入方式，而不是直接面对内部实现细节。换句话说，外部首先需要的是边界稳定，而不是能力堆叠。只有先有一致的接入方式，后续能力扩展、运行时演进和多项目复用才有基础。

  • 可控的 agent 编排与执行控制需求：不同请求需要不同执行路径，执行过程也需要明确的停止条件、失败处理和状态更新机制。因此，系统需要统一的编排与执行控制能力，避免把执行决策散落在业务逻辑、临时规则和 prompt 里。否则系统一旦变复杂，行为就很难稳定。

  • 上下文治理需求：多轮 agent 系统天然依赖上下文，但上下文并不是一个简单的大输入。历史对话、阶段记忆、检索结果和上下文预算约束各不相同，如果混在一起处理，系统会快速失去可解释性和可维护性。因此，外部真正需要的不是“更多上下文”，而是可治理的上下文能力。

  • MCP / Tool 接入与执行需求：agent 不只是生成文本，还需要接入和调用外部能力。因此，工具注册、工具发现、调用分发和执行过程需要成为共享基础能力，而不是由每个项目各自重复建设。只有这样，外部能力接入才不会在不同项目里演变成一套套彼此割裂的私有实现。

  • 权限控制与安全边界需求：工具调用和外部能力接入天然带来权限和安全问题。系统不仅要“能执行”，还要能明确哪些操作允许执行、哪些操作必须被阻断。没有这一层边界，能力越强，风险越大。

  • 模型接入与抽象能力需求：模型能力是 agent 系统的重要输入，但上层项目不应该直接处理不同模型和不同接入方式的差异。外部真正需要的是统一的模型接入能力，让模型切换、调用方式差异和结果归一化都能被收敛到共享边界之后。

  • 过程跟踪与运行事实记录需求：AI 系统不能只看最终结果。执行过程、关键事件、工具调用、失败位置和资源消耗都需要被记录下来，系统才具备可追踪、可分析和可验证的基础。没有运行事实，结果好坏很难判断，问题也很难定位。

  • 后续能力演进需求：这套 SDK 不会停留在当前能力边界。后续还会继续扩展 retrieval、memory、checkpoint、compression、multi-agent 等能力，因此一开始就需要预留清晰的演进空间。否则每次能力扩展都会重新冲击现有结构，长期维护成本会持续升高。

SDK 设计

在需求问题被定义清楚以后，下一步是把这些问题落到一套可实现、可扩展的技术架构上。整体上，这套 SDK 采用分层 runtime 架构，各层分别承接接口、控制、编排、上下文、能力接入、模型集成、观测和数据持久化等职责。

整体架构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
+----------------------------+
|        Application         |
| terminal / external app    |
+----------------------------+
             |
             v
+----------------------------+
|         Interface          |
| session / agent api        |
+----------------------------+
             |
             v
+----------------------------+
|    Runtime Controller      |
| lifecycle / execution      |
+----------------------------+
             |
             v
+----------------------------+
|    Agent Orchestration     |
| chat / react / peo         |
+----------------------------+
     |            |            \
      v            v             v
+-------------+ +-------------+ +------------------+
|   Context   | | Capability  | |      Model       |
| Governance  | | and Tooling | |   Integration    |
+-------------+ +-------------+ +------------------+
       \                            /
        \                          /
         v                        v
     +-------------------------------+
     |         Observability         |
     |       trace / metrics         |
     +-------------------------------+
              |             \
              v              v
     +--------------------------------+
     |            Data Layer          |
     |      storage / persistence     |
     +--------------------------------+

Application Layer

职责：

  1. 承接终端入口或外部应用入口，解决 SDK 缺少可直接使用入口形态的问题
  2. 负责用户输入输出和运行时接入，解决交互层与内部运行时能力耦合的问题

包含模块：

  • TerminalSessionDemo：提供终端交互入口，负责读取输入、调用运行时接口并展示结果
  • External Application Integrations：承接外部应用或宿主系统接入 SDK 的入口形态

Interface Layer

职责：

  1. 对外暴露稳定的会话和执行接口，解决外部接入边界不稳定的问题
  2. 屏蔽内部运行时细节，避免上层项目直接耦合内部实现

包含模块：

  • Api：定义并暴露 SDK 对外接口边界
  • RuntimeApi：定义 session 创建、打开、关闭等稳定生命周期接口
  • ISession：定义会话读取、运行状态查询和执行入口
  • Agent / Session API Contracts：统一对外暴露的 contract，约束外部如何接入 SDK

Runtime Controller Layer

职责：

  1. 承接 session 生命周期，解决多轮系统缺少统一运行单元的问题
  2. 收口执行过程和运行状态，解决执行控制散落在外部的问题
  3. 统一结果归一化和运行时调度，解决运行过程缺少统一承接边界的问题

包含模块：

  • Runtime：负责运行时初始化、session 生命周期管理和统一入口调度
  • AgentSession：负责单个 session 的执行主链路、状态承接和结果归一化
  • RunCheckpoint：为 checkpoint、resume 和后台执行等后续能力预留恢复边界

Agent Orchestration Layer

职责：

  1. 负责 agent 路由和执行模式编排，解决不同请求需要不同执行路径的问题
  2. 为不同请求选择合适的执行路径，避免所有请求都被单一路径处理

包含模块：

  • AgentSelector：负责根据请求特点和运行状态选择执行模式
  • ChatAgent：承接直接对话类请求，适合不需要复杂迭代的场景
  • ReActAgent：承接带工具调用和观察反馈的迭代执行路径
  • PEOAgent：承接 plan-execute-observe 分阶段执行路径
  • MultiAgentProtocol：为多 agent 协作预留协议边界

Context Governance Layer

职责：

  1. 管理多轮系统中的上下文来源，解决多种上下文输入混杂的问题
  2. 控制上下文装配、预算和裁剪方式，解决上下文不可治理、不可维护的问题

包含模块：

  • SessionTranscript：承接会话历史，提供多轮上下文基础
  • RuntimeMemory：承接阶段记忆和摘要信息
  • RetrievalProvider：提供检索型上下文输入能力
  • ContextAssembler：统一装配不同来源的上下文
  • ContextBudgetPolicy：控制上下文预算、裁剪和边界约束

Capability and Tooling Layer

职责：

  1. 承接外部能力接入与调用，解决工具和外部能力无法统一纳入系统的问题
  2. 统一工具注册、分发和执行边界，避免不同项目各自重复建设工具接入能力
  3. 管理权限控制与执行环境，解决能力调用中的安全边界和环境隔离问题

包含模块：

  • McpGateway：统一承接工具调用请求并分发到具体执行路径
  • McpToolRegistry：管理工具注册、发现和查找
  • RuntimePermissionPolicy：在执行前完成权限判断和能力约束
  • ExecutionEnvironment：负责工具在本地、沙箱或远端环境中的执行边界

Model Integration Layer

职责：

  1. 统一模型接入方式，解决不同模型调用方式不一致的问题
  2. 屏蔽不同模型和 provider 差异，避免上层项目直接处理底层模型差异

包含模块：

  • ModelFactory：统一创建模型实例并选择接入方式
  • Provider Adapters：屏蔽不同模型服务和 provider 差异
  • StreamingEventAdapter：统一流式输出事件和结果归一化方式

Observability Layer

职责：

  1. 记录运行过程和关键事件，解决系统只能看到结果、看不到过程的问题
  2. 汇总可观测数据和运行指标，提供可追踪、可分析、可验证基础

包含模块：

  • Trace：记录关键执行事件和调用链路
  • Metrics：统计运行指标、资源消耗和调用情况
  • Diagnostics / Usage：补充运行诊断信息和使用事实

Data Layer

职责：

  1. 承接运行时数据持久化，解决运行事实无法稳定沉淀的问题
  2. 统一 transcript、memory、checkpoint、trace、metrics 等数据落盘边界，为后续能力演进提供稳定数据基础

包含模块：

  • Storage：定义统一的数据持久化接口
  • File / Remote Persistence Backends：承接文件型或远端型持久化实现

落地检验

当前实现状态可以概括为下表：

Layer 模块 当前状态 说明
Application Layer TerminalSessionDemo 基础实现 已提供终端交互入口，可用于手动运行和验证 session 流程
Interface Layer Api / RuntimeApi / ISession 基础实现 已形成 session-oriented 接口边界，但仍属于基础实现形态
Interface Layer AgentApi / IAgent 基础实现 已提供 direct-agent 入口，作为 session API 之外的补充能力
Runtime Controller Layer Runtime / AgentSession 基础实现 已承接 session 生命周期、执行主链路、状态更新和结果归一化，但复杂运行控制场景仍待扩展
Runtime Controller Layer RunCheckpoint 部分完成 已预留 checkpoint 边界，但恢复、重试、后台执行等能力仍待扩展
Agent Orchestration Layer AgentSelector / intent routing 部分完成 已具备路径选择能力，但策略和模式仍可继续扩展
Agent Orchestration Layer ChatAgent / ReActAgent / PEOAgent 基础实现 三类主要执行路径均已落地，但仍属于基础编排能力实现
Agent Orchestration Layer MultiAgentProtocol 预留扩展 已在架构中预留，但尚未进入当前主实现路径
Context Governance Layer SessionTranscript / RuntimeMemory / ContextAssembler / ContextBudgetPolicy 部分完成 已形成多轮历史、阶段记忆、上下文装配和预算控制的基础实现，但复杂场景下的细化治理仍待扩展
Context Governance Layer RetrievalProvider 部分完成 已有检索接入边界，但更完整、更严谨的 retrieval / RAG 场景实现仍待扩展
Capability and Tooling Layer McpGateway / McpToolRegistry / RuntimePermissionPolicy / ExecutionEnvironment 基础实现 工具接入、调用分发、权限控制和执行环境边界已经形成，但仍属于基础实现
Model Integration Layer ModelFactory / StreamingEventAdapter 基础实现 已具备统一模型接入和流式事件适配能力，但模型侧能力仍可继续扩展
Model Integration Layer Provider Adapters 部分完成 mock 与现有 provider 已接入，但 provider 覆盖面仍可继续扩展
Observability Layer Trace / Metrics 基础实现 关键运行事件和运行指标已进入主路径，但观测深度仍可继续增强
Observability Layer Diagnostics / Usage 部分完成 已有基础运行事实记录，但更完整诊断视图仍待扩展
Data Layer Storage / File Persistence 基础实现 已形成统一存储接口和文件型持久化实现，但数据层能力仍以基础落盘为主
Data Layer Remote Persistence Backends 预留扩展 架构边界已出现，但远端存储实现尚未展开

对 Agent SDK 的总结

这套 SDK 设计与实现的经验总结

  • 基础共享能力：Agent SDK 面对的不是单点问题，而是一组经常一起出现的问题，包括接口边界、执行控制、上下文治理、工具接入、模型调用、可观测性和数据持久化。框架的价值，在于把这些问题拆开治理，并沉淀成共享基础设施。
  • 能力控制：Agent SDK 不只是负责把外部能力接进来，还需要对能力使用过程进行控制，包括 MCP 接入边界、工具注册与分发、权限判断和执行环境约束。没有这一层控制，能力接入越多，系统越容易失控。
  • 记忆管理：多轮 agent 系统天然需要历史承接和阶段记忆，但这些信息不能无限堆积，也不能简单混在一起。Agent SDK 需要把 transcript、memory、retrieval 和 context budget 作为独立问题管理。
  • 场景承接：Agent SDK 的重点不在于单独提供模型接入能力，而在于承接真实场景里的多轮状态、工具执行、权限约束、记忆管理和结果回写，把这些能力组织成一套可以实际运行的系统。

与业界 Agent SDK 的框架和能力对比

相同点：

  • 处理同类问题：都在处理同一类底层工程问题，包括多轮运行时承载、工具调用组织、权限边界管理、运行过程记录，以及如何在不确定模型行为之上建立相对稳定的系统控制。
  • 具备相似架构骨架：都需要稳定接口边界、统一运行时承载、编排与路由能力、工具与模型接入能力、观测和持久化能力。

不同点：

  • 成熟度与能力深度不同：相比业界成熟 SDK，这套实现目前仍然是基础版本，在策略成熟度、能力覆盖面、复杂场景稳定性、多 agent、长期记忆、复杂权限治理等方面还有明显差距。
  • 目标侧重点不同：这套 SDK 当前的重点，是验证 agent 系统在工程层面应当具备怎样的架构边界、运行时分层和能力组织方式，而不是优先追求能力完善度。

与既有工程经验的对比

相同点：

  • 问题与需求分析：系统首先要回答解决什么问题、服务什么对象、边界在哪里，这和传统软件开发的起点是一致的。
  • 对外接口要稳定：外部怎么接入、内部怎么演进，这在传统 SDK、中间层、平台系统里本来就是核心问题。
  • 能力要被统一组织：哪些能力应该抽成共享能力，哪些能力应该留给上层业务，这和传统平台型系统的能力设计问题相通。
  • 模块要有清晰分层：接口层、控制层、能力层、数据层如何划分，依赖关系如何约束，这和传统架构设计问题本质一致。
  • 运行时系统问题相通：生命周期管理、能力边界、状态承接、可观测性和数据持久化，本质上都属于传统运行时系统长期面对的问题。

不同点：

  • LLM 不确定性：模型输出天然带有概率性，同样输入不一定产生完全一致的结果，这会直接影响控制、调试和验证方式。
  • 上下文动态性：上下文会随着会话历史、记忆、检索结果和预算约束不断变化，输入本身就是动态演化的。这里不仅是上下文变多的问题，更是记忆管理更复杂的问题，包括哪些历史需要保留、哪些内容需要压缩、哪些信息应该进入当前轮执行。
  • 执行路径动态性：是否调用工具、调用什么工具、是否继续执行、何时停止，很多时候都要在运行时动态决定。
  • 开放能力边界：agent 系统会主动接入外部工具、外部数据源和执行环境，这会显著放大权限控制和安全治理难度。
  • 验证要求更高：不能只验证结果，还要验证过程、状态和运行事实是否可信、可追溯。

总结

进入一个新方向，重点不是先追热点，而是通过 调查、实践、复盘迭代 持续校正判断。这里使用的方法是 实事求是。

  • 调查：先搞清楚它是什么、优势和劣势分别是什么、业界已经有哪些方案和经验。
  • 实践：基于调研形成判断，再通过具体工程去验证这些判断是否成立。
  • 复盘迭代：基于实践结果做总结和复盘，补充前面的调查，更新已有判断，再继续验证。

Agent SDK 作为这套方法论最早落地的一块工程基础设施，已经说明这条方向成立，工程架构完整，可以继续作为后续项目的共享底座演进。