Agent Lightning — 架构与原理

30 秒导读： Agent Lightning 是微软研究院的一个训练框架，一句话——让你「几乎不改代码」就能用强化学习（RL）去调优任何 AI agent。它的做法是在「跑 agent」和「训 agent」之间插一个中央数据库 LightningStore：agent 照常跑、框架在旁边把每一次 LLM 调用/工具调用/奖励都记成结构化事件（span），再把这些事件翻译成 RL 认识的 (提示, 回答, 奖励) 三元组，喂给训练算法；算法学完把新模型权重或新提示词写回 store，agent 下一轮就用上了。

本页是总入口：先讲清「这是什么」（零基础也能懂），再给一张顶层全景图和一条主线走查，最后是各章阅读地图。想深入某个机制，按地图跳对应章节。

1. 这是什么（零基础也能懂）

一句话定义

Agent Lightning 是一个agent 训练框架：它把你已经写好的 AI agent 当成一个「黑盒」照常运行，在旁边观测它、给它打分，然后用强化学习等算法反过来优化它背后的语言模型或提示词。

项目自称 “The absolute trainer to light up AI agents.”，版本 0.3.1（依据：agentlightning/__init__.py:3 __version__）。

它想解决什么问题

先说痛点。你想用 RL 训一个 agent，通常会遇到两难：

传统 RL 框架（要你把 agent 逻辑重写进它的训练循环里）——侵入性强，多智能体、复杂工具链几乎没法塞进去。
只调提示词——不动模型权重，天花板低。

Agent Lightning 的主张是：训练循环不该绑架你的 agent 代码。你的 agent 用什么框架写的（LangChain、OpenAI Agents SDK、AutoGen、CrewAI，或者干脆裸调 OpenAI）都行，甚至多个 agent 组成的系统里你只想训其中一个也行（依据：README.md:20-23 Core Features）。

给谁用

读者	用它来做什么
做 agent 的工程师	手上有个能跑的 agent，想让它「越用越准」，但不想为了训练重写一遍
RL / LLM 研究者	想在真实 agent 轨迹上跑 PPO/GRPO 等算法，验证新想法
提示词工程师	不碰模型权重，只想自动搜出更好的 system prompt（APO 算法）

用起来什么样

最小改动长这样——把你的 rollout 函数用 @agl.rollout 装饰，函数里正常调 LLM，结束时报个分：

# 示意，改编自 examples/calc_x/calc_agent.py
import agentlightning as agl

@agl.rollout                     # 这一行把普通函数变成可训练的 agent
async def calc_agent(task, llm): # task=一道数学题；llm=框架发给你的「可训练 LLM 端点」
    answer = await solve(task["question"], base_url=llm.endpoint, model=llm.model)
    reward = await evaluate(answer, task["result"])  # 算对了给 1，算错给 0
    agl.emit_reward(reward)       # 把分数报回框架（也可以直接 return reward）

然后交给 Trainer 去 fit：

# 示意，改编自 examples/calc_x/train_calc_agent.py
algorithm = agl.VERL(config)                        # 用 VERL 做 PPO/GRPO 训练
trainer = agl.Trainer(algorithm=algorithm, n_runners=10)
trainer.fit(calc_agent, train_dataset, val_dataset=val_dataset)

注意 calc_agent 内部没有一行 RL 代码——它不知道自己在被训练。这就是 “ZERO CODE CHANGE (almost)” 的意思。

一句话直觉

把它想成给 agent 装了个「行车记录仪 + 教练」：

行车记录仪（Tracer）——全程录下 agent 每一步（每次 LLM 调用、每次工具调用）。
教练（Algorithm）——回放录像、按结果打分、总结出「下次该怎么开」，再把新驾驶习惯（模型权重 / 提示词）塞回车里。
中间的调度台（LightningStore）——录像存这里、任务派这里、新习惯发这里，两边谁都不用直接认识谁。

2. 顶层全景（它大概怎么转）

怎么读这张图

从中间的 LightningStore 看起——它是唯一的中央枢纽，左边是「出题+学习」的算法侧，右边是「跑题+记录」的执行侧。两侧从不直接对话，全靠 store 转手。箭头是数据流向。

        算法侧（学）                     中央控制面                    执行侧（跑）
  ┌───────────────────┐          ┌──────────────────┐        ┌────────────────────┐
  │     Algorithm     │──① 发布资源──▶                  │        │     Runner ×N       │
  │  (VERL/APO/...)   │──② 排队任务──▶  LightningStore  │◀─③ 领任务─│  (LitAgentRunner)   │
  │                   │◀─⑥ 读 span───│  任务/尝试/span/  │──④ 发资源─▶│        │            │
  │  用 Adapter 转成   │           │      资源         │◀─⑤ 回 span─│        ▼            │
  │  triplet 喂 RL     │──⑦ 更新权重──▶                  │        │  你的 LitAgent      │
  └───────────────────┘          └──────────────────┘        │  (被 Tracer 录制)   │
                                                             └────────────────────┘

部件一句话职责

部件	干什么	在哪个文件
`LightningStore`	中央控制面：存任务/尝试/span/资源，驱动状态机，做算法↔runner 的唯一中介	`agentlightning/store/base.py`
`LitAgent`	你的 agent 的基类；实现 `rollout()`，或用 `@agl.rollout` 装饰一个函数	`agentlightning/litagent/litagent.py`
`Runner`（`LitAgentRunner`）	工作进程：轮询领任务 → 跑 agent → 把 span 落库 → 标记成败	`agentlightning/runner/agent.py`
`Tracer`	录制器：把 agent 运行期的每一步抓成 OpenTelemetry span	`agentlightning/tracer/base.py`
`Adapter`（`TracerTraceToTriplet`）	翻译器：把一堆 span 拼成轨迹，产出 (prompt,response,reward) 三元组	`agentlightning/adapter/triplet.py`
`Algorithm`	训练策略：读 triplet，学，把新资源写回 store	`agentlightning/algorithm/base.py`
`Trainer`	总装：把上面这些接线并交给执行策略跑起来	`agentlightning/trainer/trainer.py`
`ExecutionStrategy`	决定进程怎么起（共享内存 / HTTP 客户端-服务端）	`agentlightning/execution/base.py`
`LLMProxy`	OpenAI 兼容代理：给 LLM 调用注入路由信息，并回传 token id 供 RL 用	`agentlightning/llm_proxy.py`

主线走一遍（一次训练循环，高层不进代码）

跟着上图的编号 ①→⑦ 走一圈，就是 Agent Lightning 的心跳：

① 发布资源：算法把初始「可训练的东西」（一个 LLM 端点、一份提示词模板）写进 store，拿到一个版本号（resources_id）。
② 排队任务：算法把训练集里的样本一个个 enqueue_rollout 排进队列，状态 queuing。
③ 领任务：某个 Runner 空闲了，dequeue_rollout 领走队首任务，store 给它建一个「尝试」（attempt），状态转 preparing。
④ 发资源：Runner 按任务上的 resources_id 去 store 取当前该用的 LLM/提示词。
跑 + 录：Runner 进入 tracer 的追踪上下文，调用你的 agent；agent 正常干活，每次 LLM/工具调用被录成 span，结束 emit_reward 打分。
⑤ 回 span：Runner 把这一趟的所有 span 落进 store，把 attempt 标成 succeeded/failed。
⑥ 读 span + 转 triplet：算法从 store 把 span 读回来，用 adapter 拼成轨迹、匹配奖励，得到一批 (prompt, response, reward) 三元组。
⑦ 更新权重：算法拿 triplet 跑一步 RL（比如 VERL 的 PPO/GRPO），算出新模型权重，update_resources 发布成新版本——回到第 ①/② 步，进入下一轮。

关键心智模型：整个系统是「生产者-消费者 + 版本化资源」。Runner 是 span 的生产者，Algorithm 是消费者；反过来 Algorithm 是资源的生产者，Runner 是消费者。中间那本账本就是 LightningStore。想透这一层，后面各章就都是在补细节。

3. 阅读地图（建议顺序）

按「由浅入深」推荐这样读：

01 — 控制面与数据模型：先搞懂那本中央账本 LightningStore 记了什么、四种核心数据（rollout / attempt / span / resources）分别是什么、状态机怎么转。这是全项目的地基。
02 — Agent、Runner、Tracer：执行侧三件套。你的 agent 怎么写（@rollout 的「零改动」魔法从哪来）、Runner 的主循环、Tracer 怎么录、奖励怎么发。
03 — 从 span 到 triplet：最有含金量的一章。乱序 span 怎么拼成树、怎么在树里精确挑出「被训练那个 agent 的 LLM 调用」、怎么把奖励配给它们；以及「返回 token id」为什么是 agent RL 的关键。
04 — Trainer 与算法：学习侧。Trainer 的接线逻辑、三类算法（VERL/APO/Baseline）各自的路子、进程编排（共享内存 vs 客户端-服务端）。
05 — 深入、边界与代码地图：可借鉴的巧妙设计、它刻意不做什么/会在哪崩、和同书架兄弟项目的对比、以及一张给人和 agent 用的跳转表。

赶时间的话：只读 01 + 03 就能抓住这个项目 80% 的精华——账本 + 翻译器。

1. 这是什么（零基础也能懂）​

一句话定义​

它想解决什么问题​

给谁用​

用起来什么样​

一句话直觉​

2. 顶层全景（它大概怎么转）​

怎么读这张图​

部件一句话职责​

主线走一遍（一次训练循环，高层不进代码）​

3. 阅读地图（建议顺序）​