Chapter 06–07 · Framework Internals
别先学框架 API，先看懂框架替你封装了什么
LangGraph、AutoGen、AgentScope 看起来差异很大，但拆到最后都会落回几个核心抽象：LLM、Message、Tool、State、Agent、Runtime。真正学会这些，你以后换任何框架都不会从零开始。
LLM做决策
Reason / Choose / Respond
Reason / Choose / Respond
State存当前进度
任务状态机
任务状态机
Tool连接外部能力
执行真实动作
执行真实动作
Runtime负责真正运行
Loop / Error / Retry
Loop / Error / Retry
1. Agent Framework 到底在封装什么？
Agent Framework ≈ LLM + Message + Tool + State + Agent Loop + Runtime
核心思想：框架不是让模型“突然更聪明”，而是把大量通用工程能力标准化：状态管理、工具调用、控制流、持久化、重试、消息结构、日志、并发、检查点。
2. LangGraph：把 Agent 看成状态图
LangGraph 最重要的抽象不是 API，而是：State + Node + Edge。
Graph = State + Node + Edge
📦
State
当前运行状态，例如消息、任务进度、工具结果。
⚙️
Node
本质就是函数：调用模型、执行工具、处理数据。
↔️
Edge
决定下一步去哪里，相当于显式控制流。
为什么不是直接 while True？简单 Agent 可以，但复杂系统有分支、回退、人工确认、检查点、并发时，Graph 能把控制流显式化。
3. AutoGen：重点理解 Multi-Agent 协作
AutoGen 最值得学的不是接口，而是：多个 Agent 如何通过消息与团队结构协作。
Multi-Agent ≠ 自动更强。更多 Agent 会增加 Token、延迟、协调成本和错误传播。只有职责、工具、上下文确实需要分离时才值得拆。
4. AgentScope：观察“消息”和“工具箱”的设计
AgentScope 适合用来理解一个成熟 Agent 框架为什么会把 Message 和 Toolkit 单独抽象出来。
💬
Message
Message(
role="user",
content="分析这个报错",
metadata={...}
)
统一 Agent、LLM、工具之间的数据交换格式。
🧰
Toolkit
Toolkit(
tools=[
search,
run_python,
read_file
]
)
统一管理工具的 Schema、调用方式与执行能力。
5. 自己搭一个 Agent Framework，需要哪几个核心组件？
🧠
LLM
统一封装不同模型供应商。上层 Agent 不应该关心 OpenAI、Qwen 还是 Gemini。
💬
Message
统一消息结构：role、content、tool_calls、metadata。
🛠
Tool
定义 name、description、parameters 和 run()。
🤖
Agent
定义控制策略，例如 ReAct、Reflection、Plan-and-Solve。
📦
State
保存当前任务的进度、计划、工具结果与临时信息。
⚡
Runtime
负责真正执行循环、工具、错误处理、重试、终止条件。
最小目录结构
hello_agents/
├── core/
│ ├── llm.py
│ ├── message.py
│ ├── agent.py
│ └── state.py
├── agents/
│ ├── react_agent.py
│ ├── reflection_agent.py
│ └── plan_solve_agent.py
├── tools/
│ ├── base.py
│ └── registry.py
└── runtime/
└── executor.py
6. Runtime / Harness：Agent 系统真正“干活”的地方
这是最容易被忽略、但最关键的概念之一。
LLM = Decision Maker Runtime = Execution Engine
while step < max_steps:
response = llm.chat(
messages=state.messages,
tools=tool_schemas
)
if response.final:
return response.answer
tool_call = response.tool_call
result = runtime.execute_tool(tool_call)
state.update(result)
step += 1
LLM 负责
理解任务、选择动作、生成参数、判断是否完成。
Runtime 负责
调用模型、执行工具、维护状态、处理异常、限制最大步数、重试、记录日志。
关键区分：“Agent 想执行命令”和“系统真的允许并执行命令”是两件事。权限、沙箱、超时、重试，都属于 Runtime / Harness 层。
7. State ≠ Memory
| 概念 | 含义 | 例子 |
|---|---|---|
| State | 当前这次运行中的状态 | 现在执行到第 3 步、最新报错、当前计划 |
| Memory | 跨步骤甚至跨会话保留的信息 | 过去失败经验、用户偏好、长期知识 |
记忆口诀：State 回答“现在做到哪”，Memory 回答“以前发生过什么”。第 8～9 章会进一步展开。
8. 映射到“科研论文复现 Agent”
Agent：决定当前要解决“环境问题、代码问题还是实验问题”。
Runtime：真正执行 read / clone / install / run / retry。
Tools：负责 PDF、GitHub、Shell、测试与指标提取。
State：保存当前步骤、环境信息、错误日志、实验结果。
Evaluator：判断是否达到复现目标，必要时触发下一轮。
9. 一页总结
LangGraph = State + Node + Edge
AutoGen = Agent + Team + Message
AgentScope = Agent + Message + Toolkit
Agent Framework = LLM + Message + Tool + State + Agent + Runtime
LLM 决策；Runtime 执行
| 你真正要会的 | 含义 |
|---|---|
| 为什么需要 Message | 统一模块之间的数据交换格式 |
| 为什么需要 State | 保存当前任务运行状态 |
| 为什么需要 Tool Registry | 统一发现与执行工具 |
| 为什么需要 Runtime | 把模型决策变成真实执行 |
| 为什么需要 Graph | 复杂控制流显式化 |
下一份：第 8～9 章——Memory、RAG、State、Context Engineering。重点把四个最容易混淆的概念彻底区分，并画出 GSSC：Gather → Select → Structure → Compress。