👋 关于作者
你好,这里是一条泥憨鱼 | 专注于 后端开发、AI 前沿技术与计算机基础 。

🏠 个人主页 :一条泥憨鱼
通过技术博客记录技术成长,分享学习心得与经验。期待与您共同交流!
一个智能体框架需要哪些稳定接口,才能让不同模型、不同执行范式和不同工具在同一套结构里工作。
HelloAgents 给出的答案很克制。核心只保留 LLM、消息、配置和 Agent 基类;具体 Agent 负责不同推理策略;其余能力尽量收敛到 Tool。作者把这个原则概括成“万物皆为工具”。读完再看后面的记忆、RAG 和协议,它们都能接在这套框架上,而不用重写 Agent 主循环。
先看框架骨架
第七章的目录结构已经把职责划得很清楚:
hello_agents/
├── core/
│ ├── agent.py
│ ├── llm.py
│ ├── message.py
│ ├── config.py
│ └── exceptions.py
├── agents/
│ ├── simple_agent.py
│ ├── react_agent.py
│ ├── reflection_agent.py
│ └── plan_solve_agent.py
└── tools/
├── base.py
├── registry.py
├── chain.py
├── async_executor.py
└── builtin/
可以把它压缩成三层:
Agent 负责任务执行
LLM 负责模型调用
Tool 系统负责把外部能力接入执行流程
我更喜欢再加一层“协议层”来理解 Message 和 Config。前者规定 Agent 与模型怎样传消息,后者规定运行参数从哪里来。它们不直接完成任务,却决定了整个框架是否稳定、是否容易替换。
为什么还要自己写框架
原文列出的理由集中在四类成本:成熟框架抽象层多,升级后接口容易变化,内部机制不透明,依赖链也重。这些问题在大项目里未必致命,但会拖慢学习和定位错误的速度。
自建框架的好处在于每一层都能被读懂、替换和检查。对一个学习项目来说,这种透明度比多接十个 API 更有用。
HelloAgentsLLM:把模型差异挡在框架外
第四章已经有一个能调用 OpenAI 兼容接口的基础客户端。第七章把它扩成 HelloAgentsLLM,补上了多提供商、本地模型和自动检测。
扩展新供应商时,原文推荐继承,不直接改安装包源码。以 ModelScope 为例:
class MyLLM(HelloAgentsLLM):
def __init__(self, provider="auto", **kwargs):
if provider == "modelscope":
# 解析 ModelScope 的 key、base_url 和默认模型
...
else:
super().__init__(provider=provider, **kwargs)
这段代码展示了扩展边界:定制逻辑只拦截新增的 provider,其他情况仍交给父类。以后升级库时,已有定制不会和框架源码缠在一起。
本地模型也走同一条接口
VLLM 和 Ollama 都把模型包装成 OpenAI 兼容 API:
VLLM → http://localhost:8000/v1
Ollama → http://localhost:11434/v1
因此框架只需要把 provider、model、base_url 和 api_key 填对,Agent 代码不用动。本地服务通常不校验真实密钥,但仍要填一个非空字符串,例如 "vllm" 或 "ollama"。
这种统一有个实际好处:开发时先接云端模型,验证功能后换成 Ollama,再按性能需要切到 VLLM,调用侧保持同一套消息和流式接口。
自动检测的优先级
_auto_detect_provider() 按三层判断:
- 先看特定服务商的环境变量,如
MODELSCOPE_API_KEY、OPENAI_API_KEY、ZHIPU_API_KEY; - 没有特定 key 时,再看
base_url的域名和端口; - 最后才尝试根据通用 API key 的格式推断。
确定 provider 后,_resolve_credentials() 再补齐对应的 key、默认 base_url 和模型参数。
习题专门问了一个组合:同时设置 OPENAI_API_KEY 和 LLM_BASE_URL=http://localhost:11434/v1 时会选谁。按原文规则,特定服务商环境变量优先,所以会选 OpenAI,而不是本地的 Ollama。想强制使用本地服务,最稳妥的方式仍是显式传 provider="ollama"。
三个基础接口:Message、Config、Agent
Message:对内保留上下文,对外兼容 API
Message 用 Pydantic BaseModel 定义四个字段:
content: str
role: Literal["user", "assistant", "system", "tool"]
timestamp: datetime
metadata: Optional[Dict[str, Any]]
role 使用 Literal 限定取值,能提前拦住错误角色。timestamp 和 metadata 供日志、调试和后续扩展使用;真正发给模型时,to_dict() 只输出兼容接口的 role 和 content。
这种“内部信息丰富,外部格式克制”的设计很实用。框架可以在消息里保留来源、时间或工具信息,而不把这些字段硬塞进模型请求。
Config:默认值与环境变量
Config 集中保存模型名、provider、温度、最大 Token、调试开关和历史长度。from_env() 负责把环境变量转成配置对象。
这样部署时不必改代码。测试环境可以设置 DEBUG=true,线上环境换一组 LOG_LEVEL 和模型参数,程序入口保持一致。
原文习题还问到配置单例。需要注意,正文展示的 Config 是 Pydantic 模型,片段里没有出现单例实现。复习时不要把“配置对象”和“全局只能存在一个实例”混为一谈,后者需要额外的工厂或类方法保证。
Agent:统一执行入口
Agent 继承 ABC,构造函数接收名称、LLM、系统提示词和配置,并初始化内部历史:
self._history: list[Message] = []
最重要的抽象方法是:
@abstractmethod
def run(self, input_text: str, **kwargs) -> str:
...
任何具体 Agent 都必须实现 run()。基类另外提供 add_message()、clear_history() 和 get_history()。get_history() 返回副本,避免调用方拿到内部列表后直接改坏状态。
这层抽象的价值是统一入口。SimpleAgent 可以只做对话,ReActAgent 可以做多步工具调用,PlanAndSolveAgent 可以先规划再执行,但外部看到的都是同一个 run()。
五种 Agent 实现怎么选
第七章把第四章的三种经典范式重新放回框架,又补上 SimpleAgent 和后续版本加入的 FunctionCallAgent。几种实现面向不同任务形态,选择时看任务需要多轮行动、质量迭代还是显式规划。
SimpleAgent:最小可用的对话与工具循环
SimpleAgent 的 run() 先组装三类消息:系统提示词、历史消息、当前用户输入。
没有工具时,它直接调用 llm.invoke(),然后保存用户消息和助手回复。
启用工具后,系统提示词会追加工具描述和固定调用格式:
[TOOL_CALL:工具名:参数]
执行循环大致是:
调用 LLM
→ 用正则查找工具调用标记
→ 逐个执行工具
→ 把工具结果作为新的上下文交回 LLM
→ 直到没有工具调用或达到最大轮数
默认最多执行 3 轮工具调用。这个上限很有必要,否则模型可能反复搜索、计算,永远不给最终回答。
SimpleAgent 还支持流式输出和动态工具管理:stream_run() 边生成边返回;add_tool()、remove_tool()、list_tools() 负责运行时调整工具集合。
ReActAgent:把“想”和“做”交替起来
ReAct 每轮只允许一个步骤,输出格式固定为:
Thought: 当前分析和下一步意图
Action: tool_name[input]
或者:
Action: Finish[最终答案]
框架版的改动主要有两处。第一,提示词明确限制每次只执行一个动作;第二,工具统一从 ToolRegistry 查找和执行。
执行历史会保存 Action 和 Observation,下一轮一起送入提示词。max_steps 默认是 5,达到上限仍未结束时返回“无法在限定步数内完成”。
ReAct 适合需要边查边判断的任务。它的弱点也很清楚:输出格式靠提示词约束,模型写错格式或编造工具名时,解析会失败。生产环境里需要把格式错误、工具不存在和执行异常分别处理。
ReflectionAgent:先做一版,再审一版
Reflection 的核心是三步提示词:
initial → 生成初稿
reflect → 找问题和改进点
refine → 根据反馈改写
框架版把提示词从第四章的代码生成专用模板改成了通用模板,并通过 custom_prompts 允许替换。这样同一个 Agent 可以用于文章、分析和代码任务。
它适合质量优先、对延迟不敏感的生成任务。每轮反思都意味着额外 LLM 调用,成本和延迟会随轮数线性增加。原文习题提出用质量评分控制提前结束,这个方向比固定轮数更合理。
PlanAndSolveAgent:先拆任务,再逐步执行
这个范式分成 Planner 和 Executor。
Planner 必须输出 Python 列表:
["步骤1", "步骤2", "步骤3"]
Executor 每轮收到原始问题、完整计划、历史步骤和当前步骤,只输出当前步骤结果。
固定列表格式降低了“计划看起来合理,但后续无法解析”的风险。对长流程、步骤之间有依赖的任务,它比 ReAct 更容易审计。
代价是计划质量决定整个流程的上限。第一步拆错,后面的执行再努力也很难拉回来。
FunctionCallAgent:让模型按工具 schema 调用
FunctionCallAgent 使用 OpenAI 原生 function calling,不靠文本正则解析工具调用。原文列出四个关键能力:
_build_tool_schemas
_extract_message_content
_parse_function_call_arguments
_convert_parameter_types
ToolRegistry.to_openai_schema() 会根据 ToolParameter 生成参数定义,包括类型、描述和 required 字段。模型返回 JSON 参数后,框架再做类型转换并执行工具。
相比 SimpleAgent 的 [TOOL_CALL:...:...],原生 function calling 对参数类型和工具结构有更明确的约束,鲁棒性更好。代价是框架需要适配不同供应商的函数调用能力,不能假设所有兼容 OpenAI 聊天接口的模型都完整支持 tools。
工具系统:框架真正向外生长的地方
Tool 与 ToolParameter
所有工具都有名称、描述和两个方法:
def run(self, parameters: Dict[str, Any]) -> str: ...
def get_parameters(self) -> List[ToolParameter]: ...
ToolParameter 描述单个参数:
name: str
type: str
description: str
required: bool = True
default: Any = None
这组元数据同时服务三件事:生成提示词、校验参数、转成 OpenAI function schema。工具接口统一返回字符串,也让 Agent 主循环不必区分不同工具的输出结构。
ToolRegistry 管理发现与执行
注册表支持两种接入方式:
- 注册完整的
Tool对象,适合复杂工具; - 用
register_function()直接注册普通函数,适合快速接一个小能力。
同名工具默认覆盖,并打印警告。开发时方便迭代,生产环境则要考虑覆盖是否应改成显式开关。
get_tools_description() 生成工具列表,直接拼进 Agent 提示词;to_openai_schema() 生成 function calling 所需的 JSON schema。
计算工具:白名单 AST 比 eval 安全
示例计算器使用 ast.parse(..., mode="eval"),只允许数字、四则运算、sqrt 和 pi。
它没有直接执行 eval(expression),而是遍历 AST,只处理白名单节点。这个差别很关键。面向用户的表达式入口不能默认相信字符串,允许的方法和函数越少,误用风险越低。
多源搜索:优先使用,失败后降级
SearchTool 支持 Tavily、SerpApi 或 hybrid 模式。混合模式先尝试 Tavily,失败后切到 SerpApi;没有可用密钥或依赖时,返回明确的配置提示。
多源接入不复杂,难的是统一结果。原文会把标题、摘要、链接整理成同一种文本格式,Agent 才能稳定消费。真实项目里还应补上来源时间、去重和失败日志,否则“多源”可能只是把重复结果放大。
ToolChain:把工具结果显式传给下一步
ToolChain 的每个步骤包含:
tool_name
input_template
output_key
input_template 使用 Python 的 format(**context) 替换变量,上一步结果以指定的 output_key 写回上下文。这样链式流程可以看到数据怎样流向下一个工具。
模板变量缺失时,链会立即返回错误,不会把半个结果继续传下去。
AsyncToolExecutor:适合 I/O 等待
异步执行器用 ThreadPoolExecutor 把工具调用丢进线程池,再通过 asyncio.gather() 等待多个任务。
它适合网络搜索、远程 API 这类 I/O 密集任务。若工具本身是 CPU 密集计算,线程池受 GIL 影响,收益有限;若工具共享外部客户端且不线程安全,还需要额外加锁或隔离连接。
框架设计里的可复用经验
统一入口比功能数量重要
五个 Agent 的推理方式不同,但都实现 run();所有工具的参数形式不同,但都通过 Registry 发现和执行。上层不需要知道下层用了哪种范式。
适配差异放在边界,不放进主循环
模型供应商差异被 HelloAgentsLLM 吸收,工具差异被 Tool 和 ToolRegistry 吸收。Agent 主循环只关心“调用模型”和“执行工具”这两个动作。
格式约束就是可靠性
ReAct 的 Thought/Action、PlanAndSolve 的 Python 列表、FunctionCall 的 JSON schema,都在约束模型输出。格式越明确,执行器越容易判断下一步,也越容易在错误发生时停下。
上限必须写进循环
SimpleAgent 有 max_tool_iterations,ReActAgent 有 max_steps。多步 Agent 必须设终止条件,只靠模型自己说“完成”并不可靠。
总结
先统一模型和工具边界,再让不同 Agent 范式共享同一套执行入口。HelloAgents 的复杂度也就停在这里,后面的能力都能沿着这两个边界继续扩展。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/2503_94545876/article/details/170743220




