框架共同抽象:把对象还原成可控制的 Agent Loop
从消息、配置、模型适配、工具注册和生命周期看懂框架,并用可取消的异步循环检查抽象是否合理。
看到 Agent、Runnable、Session、Runtime 等名字,先问一个更具体的问题:谁保存历史,谁决定下一步,谁真正执行工具,谁负责停止?这些责任能画清楚,才知道引入框架替掉了哪段代码。对象名字相似,不代表取消、重试、持久化和权限语义相同。
四种对象对应四种责任
Message 承载角色、内容块、调用ID、来源与时间。内部消息最好与供应商JSON分离:工具结果必须关联调用ID,图像或文件不能被随意变成字符串,系统策略不能混进不可信检索文本。消息格式是数据契约,不是权限凭证。
Config 放模型标识、超时、最大步数和运行标签。会话状态放用户历史与待完成工作,两者不要共用一个可变字典:如果多个请求共用同一个Config并往里面写工具结果,就会产生跨会话污染。凭据应由部署环境注入模型客户端,普通消息与轨迹里不保存key。
Agent 是控制器:读取状态、请求模型、解释行动、检查预算、分派工具、收集结果,再决定继续或结束。Tool 包含名称、说明、输入模式和执行函数。模型只提出名称与参数,真正的执行器还要检查工具是否注册、参数是否合法、当前身份是否允许这次操作。给模型一个“只能查询”的提示,并没有取消底层函数的写权限。
适配层与扩展点放在哪
模型适配器负责内部消息到供应商请求、供应商响应到内部行动的双向转换,保留完成原因、usage和错误类别。工具适配器把函数、HTTP服务或MCP工具映射成统一调用描述。不要在每个业务Agent里判断供应商响应字段;那会让多Agent、路由和重试策略重复耦合到具体API。
扩展点应有明确顺序。例如before_model可以构造上下文,after_model可以记录用量,before_tool做授权,after_tool对输出脱敏,on_error分类异常,finally释放连接。记录钩子抛错时是否阻断业务要预先决定。安全校验若只是一个允许用户随意移除的日志回调,就不能构成可靠执行边界。
选择框架时做一张责任表:状态与checkpoint能否导出;工具校验在何处;取消如何传播;重试会不会重放副作用;trace能否关联原始业务请求;特定后端不可用时怎样降级。简单单轮结构化提取通常不需要复杂图运行时;长流程含人工审批、恢复与并行分支时,持久化与状态迁移价值更大。这个判断来自你的任务约束,而不是框架下载量。
同步与异步改变的不是返回值名字
同步函数调用期间阻塞当前线程。异步函数在等待网络时允许事件循环服务其他任务,但把同步SDK直接塞进async函数仍会阻塞。CPU密集计算通常需要进程或专用执行器;异步并不能把Python计算自动并行化。
取消从请求入口传到模型流、子任务和工具。清理写在finally,取消异常通常应该继续传播;吞掉它再重试,会让用户已经关闭的请求继续花钱或执行动作。并行工具需要独立状态与总并发限制,不能只给每个工具局部超时。超时表示调用方停止等待,不必然表示远端动作没发生。
跟做:把生命周期和步数预算放回循环
保存下面程序为 framework_loop.py,使用Python 3.11或更高版本运行 python framework_loop.py。只有标准库;FixtureModel是固定响应,不进行模型推理。工具是内存订单字典,不访问真实订单。这个小例子省略了流式协议、工具ID与业务鉴权,不可直接作为生产执行器。
"""标准库手写框架边界;模型输出为固定夹具,不调用模型。"""
import asyncio
from dataclasses import dataclass
from typing import Protocol
@dataclass(frozen=True)
class Message:
role: str
content: str
@dataclass(frozen=True)
class Config:
max_steps: int = 3
class Model(Protocol):
async def next(self, history: list[Message]) -> dict: ...
class FixtureModel:
async def next(self, history):
await asyncio.sleep(0)
if history[-1].role == 'tool':
return {'type': 'final', 'text': history[-1].content}
return {'type': 'tool', 'name': 'lookup', 'key': 'order-1'}
async def run(model, config, events):
history = [Message('user', '查订单')]
tools = {'lookup': lambda key: {'order-1': '已发货'}[key]}
events.append('start')
try:
for step in range(config.max_steps):
action = await model.next(history)
events.append(f'model:{step}')
if action['type'] == 'final':
return action['text']
if action['name'] not in tools:
raise ValueError('未注册工具')
value = tools[action['name']](action['key'])
history.append(Message('tool', value))
events.append('tool:lookup')
raise RuntimeError('step budget exceeded')
finally:
events.append('close')
if __name__ == '__main__':
events = []
print(asyncio.run(run(FixtureModel(), Config(), events)))
print(' → '.join(events))
short = []
try:
asyncio.run(run(FixtureModel(), Config(1), short))
except RuntimeError as error:
print(str(error), short[-1])实际输出:
已发货
start → model:0 → tool:lookup → model:1 → close
step budget exceeded close第一次循环模型要求lookup,结果作为tool消息进入历史;第二次模型返回final,控制器结束。最后的close来自finally,正常返回同样会执行。最大步数改成1后,查询已经完成,但模型还没有机会生成final,于是抛出预算异常;这说明“工具成功”和“整个任务完成”不是同一个状态。
把工具名改成未注册名称,应该在调用前拒绝;把工具函数改成抛异常,仍应看到close。继续扩展时,可以把事件列表换成trace sink,把FixtureModel换成真实适配器,而不改变循环中授权与预算的位置。
失败时沿控制链定位
历史重复先检查是否同时由框架和业务代码追加消息;结果串会话先查共享可变对象与会话键;取消后仍有调用先查后台task是否被追踪、同步SDK是否阻塞以及远端是否支持取消;升级后工具不执行则核对消息类型、工具schema和finish reason映射。框架日志中的“成功”可能仅指模型节点成功,业务成功仍要看工具结果和完成条件。
这里用自己的Loop理解责任,再阅读 LangGraph概览 和 AutoGen分层介绍。对照具体版本的运行语义,避免把所有框架当作同一种接口包装。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
框架对象如何映射到手写Loop?
参考思路与常见误区
Message承载历史与调用关联,Config约束运行,Agent决定下一步,Adapter转换协议,Tool Executor校验并执行工具;循环外层负责生命周期与预算。
常见误区:把Agent对象当成自动具备安全和持久化的黑盒。
async函数为什么仍会阻塞?
参考思路与常见误区
内部同步网络调用或CPU计算不让出事件循环;应采用异步SDK或适当执行器,同时保留取消和并发限制。
常见误区:只给函数加async就获得并行和可取消能力。
before_tool与after_model分别适合做什么?
参考思路与常见误区
前者在副作用前做授权与参数检查,后者记录模型响应和用量;安全门禁不能仅作为可随意移除的日志回调。
常见误区:把任何hook都视为等效扩展位置。
最大步数耗尽为什么不是任务成功?
参考思路与常见误区
可能只完成某个工具动作而没有满足业务完成条件,应保留部分结果并报告预算停止;close仅说明资源清理。
常见误区:工具成功或finally执行就代表任务完成。
选择框架应先检查哪些责任?
参考思路与常见误区
状态导出、消息契约、取消传播、重试副作用、checkpoint与trace等是否匹配实际任务;用固定失败夹具验证。
常见误区:仅按流行度或最短演示代码选型。