jjyaoao/HelloAgents

HelloAgents – 生产级多智能体框架（Python）

是什么 – 基于 OpenAI 兼容 API 构建的 Python 库，提供一个开箱即用、可扩展的平台，用于构建多智能体应用。它集成了多项工程级能力（工具响应协议、上下文管理、会话持久化、子智能体路由、乐观文件锁定、熔断器、技能加载、进度追踪、日志、可观测性、SSE 流式传输、异步生命周期等），使你能够专注于智能体逻辑，而非样板代码。

核心概念

组件	作用
HelloAgentsLLM	包装任何 OpenAI 兼容、Anthropic 或 Gemini 提供商。根据 `LLM_BASE_URL` 自动检测正确的适配器。
智能体基类 (`ReActAgent`, `SimpleAgent`, `ReflectionAgent`, `PlanAndSolveAgent`)	实现函数调用 / ReAct 模式，处理工具调用、工具响应和迭代推理。
ToolRegistry & ToolResponse	注册内置或自定义工具（文件读写、任务委派、待办事项追踪、开发日志、技能提取）。注册表强制执行 `ToolResponse` 模式。
SessionStore	将对话历史持久化到磁盘，使智能体可后续恢复。
HistoryManager / TokenCounter / ContextBuilder	管理上下文窗口，统计 token 数量，在达到限制时进行截断。
CircuitBreaker	在可配置的失败阈值后停止运行，防止工具调用失控。
TraceLogger	输出结构化追踪信息，用于可观测性（对调试或监控很有用）。
流式传输（SSE）	实时将 LLM 的部分输出发送给客户端。

快速开始

pip install hello-agents

from hello_agents import ReActAgent, HelloAgentsLLM, ToolRegistry
from hello_agents.tools.builtin import ReadTool, WriteTool, TodoWriteTool

llm = HelloAgentsLLM()                     # 从 .env 自动检测提供者
registry = ToolRegistry()
registry.register_tool(ReadTool())
registry.register_tool(WriteTool())
registry.register_tool(TodoWriteTool())

agent = ReActAgent(name="assistant", llm=llm, tool_registry=registry)
agent.run("分析项目结构并生成报告")

创建一个包含凭据的 .env 文件：

LLM_MODEL_ID=your-model-name
LLM_API_KEY=your-api-key
LLM_BASE_URL=api.your‑provider.com

该库将根据 URL 自动选择正确的适配器（OpenAI 兼容、Anthropic 或 Gemini）。

安装与兼容性

Python ≥ 3.10
在 PyPI 上发布为 hello-agents
源码采用 MIT 风格，但项目以 CC BY‑NC‑SA 4.0（非商业、相同方式共享）发布。商业用途需联系维护者。

扩展框架

添加自定义工具 – 实现 ToolResponse（函数、类或可扩展风格），并通过 ToolRegistry.register_tool() 注册。
创建新智能体 – 继承 hello_agents.core.agent.Agent 并重写 plan/act 方法，或复用提供的智能体（SimpleAgent、ReActAgent 等）。
接入新 LLM 提供商 – 在 core/llm_adapters.py 中添加遵循现有 OpenAI/Anthropic/Gemini 接口的适配器。

文档与资源

Docs 文件夹 – 16 个核心功能的详细指南（工具响应协议、上下文工程、可观测性、熔断器、会话持久化、子智能体机制、技能系统、乐观锁、TODO 进度、开发日志、异步生命周期、SSE 流式传输、函数调用架构、日志系统、自定义工具开发）。
示例 – examples/ 目录下的可运行脚本，展示典型工作流。
学习版 – 与 Datawhale「Hello‑Agents」教程匹配的稳定分支（learn_version）。
社区移植 – 非 Python 生态系统的 Go（HelloAgents-go）和 TypeScript（HelloAgents-ts）重实现。

许可证

代码以 Creative Commons BY‑NC‑SA 4.0 发布。只要署名作者并保持相同许可证，即可非商业用途使用、修改和共享。商业用途需与维护者另行协商。

总结 – HelloAgents 为多智能体 AI 系统提供了生产就绪的骨架，处理工具编排、上下文限制、持久化、可观测性等繁琐工程问题，让开发者能专注于智能体的领域逻辑。