HelloAgents V1.0.0 Release Notes
📅 发布日期: 2026-02-21
📦 安装: pip install hello-agents>=1.0.0
🔗 GitHub: https://github.com/jjyaoao/HelloAgents
📚 文档: https://github.com/jjyaoao/HelloAgents/tree/main/docs
🎯 概述
HelloAgents V1.0.0 是一个里程碑版本，标志着框架从教学原型升级为生产级多智能体框架。本版本集成了 16 项核心能力，涵盖工具响应协议、上下文工程、可观测性、会话持久化、子代理机制、异步生命周期、流式输出等完整的工程化支持，为构建复杂智能体应用提供坚实基础。(感谢项目YYHDBL/MyCodeAgent给予的部分实现灵感支持~)
✨ 核心亮点
- 🏗️ 生产级架构: Function Calling 统一架构，解析成功率 99%+
- 🔧 16 项核心能力: 从工具协议到异步生命周期的完整工程化支持
- 🚀 性能优化: Token 成本降低 85%，上下文压缩智能化
- 🔍 可观测性: 双格式审计日志（JSONL + HTML）
- 🔄 会话持久化: 断点续跑，异常自动保存
- 🌐 多 LLM 支持: OpenAI/Anthropic/Gemini 三种适配器
- 📊 流式输出: SSE 实时响应，支持前端集成
- ⚡ 异步架构: 工具并行执行，生命周期钩子
🔧 安装与升级
新安装
# 基础安装
pip install hello-agents>=1.0.0
# 完整安装（包含所有可选依赖）
pip install hello-agents[all]从旧版本升级
# 升级到最新版本
pip install --upgrade hello-agents
# 指定版本
pip install hello-agents==1.0.0验证安装
import hello_agents
print(hello_agents.__version__) # 应输出: 1.0.0🆕 核心特性
阶段 1：基础设施
1. 工具响应协议（ToolResponse）
问题: 旧版本工具返回纯字符串，状态不明确，错误处理依赖正则解析
解决方案: 统一 ToolResponse 协议
from hello_agents.tools import ToolResponse, ToolStatus, ToolErrorCode
# 成功响应
return ToolResponse.success(
text="计算结果: 5",
data={"result": 5, "expression": "2+3"},
stats={"time_ms": 10}
)
# 部分成功（截断、回退）
return ToolResponse.partial(
text="结果已截断...",
error_code=ToolErrorCode.TRUNCATED,
data={"full_path": "tool-output/xxx.json"}
)
# 错误响应
return ToolResponse.error(
text="文件不存在",
error_code=ToolErrorCode.NOT_FOUND
)收益:
- ✅ 三种状态：SUCCESS / PARTIAL / ERROR
- ✅ 15 种标准错误码
- ✅ 结构化数据传递
- ✅ 自动时间统计
2. 上下文工程（Context Engineering）
问题: 长对话无限增长导致爆窗、Token 成本爆炸、缓存失效
解决方案: HistoryManager + TokenCounter + ObservationTruncator
from hello_agents import ReActAgent, HelloAgentsLLM, Config
# 配置上下文工程
config = Config(
context_window=128000, # 上下文窗口
compression_threshold=0.8, # 80% 时触发压缩
min_retain_rounds=10, # 保留最近 10 轮
enable_smart_compression=False, # 简单摘要（默认）
tool_output_max_lines=2000, # 工具输出截断
tool_output_max_bytes=51200 # 50KB
)
agent = ReActAgent("assistant", HelloAgentsLLM(), config=config)收益:
- ✅ 自动历史压缩（summary + 最近 N 轮）
- ✅ 缓存友好设计（只追加，不编辑）
- ✅ Token 计数优化（O(n) → O(1)）
- ✅ 工具输出统一截断
- ✅ 智能摘要生成（可选）
阶段 2：核心能力
3. 可观测性（TraceLogger）
问题: 无法追踪 Agent 执行轨迹，调试困难
解决方案: 双格式审计日志（JSONL + HTML）
from hello_agents import ReActAgent, HelloAgentsLLM, Config
# 启用 TraceLogger（默认启用）
config = Config(
trace_enabled=True,
trace_output_dir="memory/traces"
)
agent = ReActAgent("assistant", HelloAgentsLLM(), config=config)
agent.run("分析项目结构")
# 查看日志
# - memory/traces/trace-20250221-103045.jsonl（机器可读）
# - memory/traces/trace-20250221-103045.html（人类可读）收益:
- ✅ 实时流式追加
- ✅ 自动脱敏（API Key、路径）
- ✅ 内置统计（Token、工具调用、错误）
- ✅ 可视化界面（HTML 交互式面板）
4. 熔断器（CircuitBreaker）
问题: 工具连续失败导致资源浪费
解决方案: 自动熔断机制，连续失败 3 次自动禁用工具，5 分钟后恢复
收益:
- ✅ Token 成本节省 97%（3 次失败 vs 无限重试）
- ✅ 自动监控工具执行
- ✅ 定时自动恢复
- ✅ 零配置开箱即用
📖 详细文档: circuit-breaker-guide.md
5. 会话持久化（SessionStore）
问题: 会话仅存在内存，崩溃即丢失
解决方案: 完整的会话保存/恢复机制
收益:
- ✅ 断点续跑（长时间任务）
- ✅ 异常自动保存（Ctrl+C / Exception）
- ✅ 环境一致性检查（配置、工具 Schema）
- ✅ Read 工具缓存集成（支持乐观锁）
📖 详细文档: session-persistence-guide.md
阶段 3：增强能力
6. 子代理机制（SubAgent）
问题: 复杂任务难以分解，上下文混乱
解决方案: 主子 Agent 协作，上下文隔离
核心特性:
- ✅ 所有 Agent 类型都可作为子代理（react/reflection/plan/simple）
- ✅ 工具过滤（ReadOnly/FullAccess/Custom）
- ✅ 轻量模型路由（子任务用 DeepSeek，节省 70% 成本）
- ✅ TaskTool 零配置集成
📖 详细文档: subagent-guide.md
7. Skills 知识外化
问题: 领域知识硬编码在系统提示词，Token 成本高
解决方案: 渐进式披露机制
核心特性:
- ✅ 启动时仅加载元数据（~100 tokens/skill）
- ✅ 按需加载完整技能（~2000+ tokens）
- ✅ 人类可编辑（Markdown 格式）
- ✅ 零配置（检测 skills/ 目录自动激活）
收益: Token 成本降低 85%（40K → 6K）
📖 详细文档: skills-usage-guide.md
8. 乐观锁机制（Optimistic Locking）
问题: 多 Agent 协作时文件冲突
解决方案: Read 时缓存元数据，Write/Edit 时检测冲突
核心特性:
- ✅ 4 个文件工具（Read/Write/Edit/MultiEdit）
- ✅ 自动冲突检测（基于 mtime）
- ✅ 自动备份机制（.backups/）
- ✅ 原子写入保证
📖 详细文档: file_tools.md
9. TodoWrite 进度管理
问题: 任务状态通过对话历史跟踪，易遗漏
解决方案: 结构化任务列表管理
核心特性:
- ✅ 单线程强制（最多 1 个 in_progress）
- ✅ 自动 Recap 生成（
[2/5] 进行中: xxx） - ✅ 持久化支持断点恢复
- ✅ 零配置集成
📖 详细文档: todowrite-usage-guide.md
阶段 4：辅助功能
10. DevLog 开发日志
问题: Agent 决策过程不透明
解决方案: 结构化开发日志工具
核心特性:
- ✅ 7 种类别（decision/progress/issue/solution/refactor/test/performance）
- ✅ 持久化到 memory/devlogs/
- ✅ 支持过滤查询
- ✅ Agent 可用工具
📖 详细文档: devlog-guide.md
11. 异步生命周期
问题: 同步执行效率低
解决方案: 完整的异步支持
核心特性:
- ✅
arun()/arun_stream()异步方法 - ✅ 工具并行执行（用户工具并行，内置工具串行）
- ✅ 生命周期钩子（on_start/on_step/on_tool_call/on_finish/on_error）
- ✅ 向后兼容（现有
run()方法不变）
📖 详细文档: async-agent-guide.md
阶段 5：核心架构重构
12. 流式输出与 SSE
问题: 长时间等待，用户体验差
解决方案: 真正的异步流式输出
核心特性:
- ✅ 使用 AsyncOpenAI 原生客户端
- ✅ SSE 标准协议（兼容浏览器 EventSource）
- ✅ 8 种事件类型（AGENT_START/STEP_START/TOOL_CALL/LLM_CHUNK 等）
- ✅ FastAPI 集成示例
性能提升: 首字节时间从 15 秒降低到 1.3 秒（11.7 倍）
📖 详细文档: streaming-sse-guide.md
13-14. Function Calling 统一架构
问题: ReActAgent 使用正则解析，成功率 85-90%
解决方案: 所有 Agent 类型统一使用 Function Calling
核心成果:
- ✅ LLM 基类重构（
invoke_with_tools()统一接口） - ✅ 3 种适配器（OpenAI/Anthropic/Gemini）
- ✅ 4 个 Agent 完整重构（ReAct/Simple/Reflection/Plan）
- ✅ 解析成功率提升到 99%+
📖 详细文档: function-calling-architecture.md
15. 日志系统（四种范式）
问题: 日志系统混乱，难以调试
解决方案: 分层日志设计
四种范式:
- TraceLogger - 生产审计轨迹（JSONL + HTML）
- AgentLogger - 开发日志（结构化，轮转）
- DevLogTool - 开发决策记录（Agent 可用）
- 标准 logging - 框架内部日志
📖 详细文档: logging-system-guide.md
16. 自定义工具扩展
问题: 用户不知道如何创建自定义工具
解决方案: 完整的扩展机制 + 文档 + 模板
三种实现方式:
- 函数式工具（最简单）-
registry.register_function(my_func) - 标准工具类（推荐）- 继承
Tool基类 - 可展开工具（高级）-
@tool_action装饰器
📖 详细文档: custom_tools_guide.md
主要变更
- 工具返回值:
str→ToolResponse对象 - Agent 架构: 正则解析 → Function Calling
向后兼容
- ✅ 函数工具自动包装为新协议
- ✅ 现有
run()方法完全不变 - ✅ 配置项可选（默认启用，可禁用）
📚 迁移指南
从 v0.x 迁移到 v1.0.0
1. 更新工具实现
# 旧版本
def my_tool(input: str) -> str:
return "结果"
# 新版本
from hello_agents.tools import Tool, ToolResponse
class MyTool(Tool):
def run(self, parameters):
return ToolResponse.success(text="结果")2. 更新 Agent 创建
# 旧版本和新版本完全相同
agent = ReActAgent("assistant", llm, tool_registry=registry)3. 启用新特性
from hello_agents import Config
config = Config(
trace_enabled=True, # 可观测性
session_enabled=True, # 会话持久化
subagent_enabled=True, # 子代理
skills_enabled=True, # Skills
todowrite_enabled=True # TodoWrite
)🎉 致谢与展望
致谢
感谢所有贡献者和学习者的支持，V1.0.0 的完成离不开社区的反馈和建议。