HelloAgents Skill 技能

技能简介

HelloAgents 是一款面向中文开发者的组件化多智能体框架，围绕原生 Function Calling 协议构建，覆盖从最小 Agent Loop 到具备上下文工程、知识检索、持久记忆与多智能体协作的完整工程链路。框架由 Datawhale 社区成员 jjyaoao 主导开发并于 2026-10-06 发布 PyPI 版本 v1.0.1，与 Datawhale「Hello-Agents」系列教程配套，提供 Python 3.12–3.13 官方支持。代码采用 CC BY-NC-SA 4.0 许可，并衍生 Golang 与 TypeScript 社区重写版本。

通过 SimpleAgent 入口，开发者可在数行代码内搭建"模型请求 → 工具执行 → 回执 → 再次调用"的标准 Agent Loop；后续按需叠加执行权限、调用预算、熔断与恢复机制。检索、记忆、上下文组件均可独立使用，并能自由拼装 Skills 子代理、后台任务、Profile 用户画像、GraphRAG 关系证据检索等高级模块，是国内团队搭建 LLM Agent 应用工程的实用底座。

核心能力

• 原生 Function Calling 适配：内置 HelloAgentsLLM 自动识别 Base URL 选择适配器，覆盖 DeepSeek/Qwen/ChatGLM 等国产 LLM；模型名称与密钥由 .env 注入，框架层不耦合特定服务。
• 四种 Agent 范式：SimpleAgent（基础循环）/ ReActAgent（推理+行动）/ ReflectionAgent（反思优化）/ PlanSolveAgent（计划求解），覆盖学术主流范式的工程落地。
• 工具系统与 MCP 桥接：ToolRegistry + ToolResponse 统一返回协议 + CircuitBreaker 熔断 + MCP stdio/HTTP 桥接 + Permissions 宿主执行权限；支持本地函数式工具与标准类自定义工具。
• 检索与图检索（RAG/GraphRAG）：RAGStore 支持 BM25、Qdrant 向量索引、Hybrid 多路融合、模型重排与 RRF；GraphRAG 模块提供实体抽取、Leiden 社区发现、局部/全局查询，并附 Recall/MRR/nDCG 评测。
• 结构化记忆与用户画像：MemoryStore 持久化语义记忆、ProfileStore 结构化用户画像（偏好/事实/经历/做法）支持并发修订与跨会话注入。
• 上下文工程与会话持久化：HistoryManager + TokenCounter + ObservationTruncator + ContextBuilder 自动诊断预算；SessionStore 支持中断恢复、TraceLogger 记录轨迹。
• Skills 知识外化与子代理：SkillLoader 按需加载操作指导文件；TaskTool + ToolFilter 启用子代理隔离执行，避免子任务污染主代理上下文。
• 后台任务与可观测性：BackgroundJobs 持久任务队列（进度上报+重试+恢复）；StreamingSSE 服务端流式事件；DevLog 决策日志记录关键调用。

安装配置

1. 环境准备：安装 Python 3.12 或 3.13（64 位，3.12 启动会输出推荐提示但不阻塞）；推荐使用 uv 作为依赖管理器，亦兼容 pip + venv。
2. 克隆与依赖锁定：git clone https://github.com/jjyaoao/HelloAgents → 仓库根目录执行 uv sync --locked（或 python -m pip install -r requirements.txt）保证依赖一致。
3. 环境变量配置：在仓库根创建 .env，依次填入 LLM_MODEL_ID、LLM_API_KEY、LLM_BASE_URL；框架将根据 Base URL 自动推断 provider。
4. 学习版与开发版：跟随 Datawhale「Hello-Agents」教程请切换到 learn_version 分支（与教程章节严格对齐）；v1.0.1 主分支包含完整组件、文档与示例。
5. 网络受限环境：通过 AtomGit 国内镜像 https://atomgit.com/jjyaoao/HelloAgents 克隆源码，避开 GitHub 访问不稳定问题。

使用步骤

1. 最小 Agent 启动：from hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry，load_dotenv() 后 with HelloAgentsLLM() as llm: agent = SimpleAgent("assistant", llm)，调用 agent.run("调用计算器计算 320×2+180") 验证循环。
2. 注册自定义工具：构造 ToolRegistry 实例并 register_tool(MyTool())，把工具集传给 SimpleAgent(..., tool_registry=registry)，让 LLM 在循环中自主选择调用。
3. 启用 Skills 知识外化：在 Config(enable_skills=True, ...) 中开启 Skills 模块，SkillLoader 自动发现 skills/*.md 文档并按需注入到上下文。
4. 启动 MCP 工具：注册 MCP 桥接后调用 agent.run("查询本机磁盘剩余空间")，框架通过 MCP 调用外部工具并把结果回灌 Agent 推理流程。
5. 添加 RAG/GraphRAG：导入 RAGStore 与 GraphRAGTool，配合 qdrant_retrieval.md 构建向量索引；调用 RAGTool.search(query) 做混合检索。
6. 观察运行轨迹：开启 TraceLogger 与 DevLog 后可在 debug-agent.log 查看每一步模型请求、工具执行、上下文组装与预算消耗。

适用场景

• 中文 LLM Agent 教学与培训：与 Datawhale「Hello-Agents」教程完整配套，提供从循环原理到工程组件的渐进式学习路径。
• 企业内部 Agent 中台建设：Tool Registry + 子代理隔离 + 后台任务 + 会话持久化，构成可拼装的中台基座。
• RAG/GraphRAG 知识库项目：内置 BM25/Qdrant/混合检索/关系图/检索评测全套组件，可直接作为企业知识库底层框架。
• 多智能体协作原型：四种 Agent 范式 + 上下文工程 + Profile 用户画像，方便快速验证 ReAct/Reflection/Plan-Solve 等多 Agent 协作模式。
• 国产 LLM 模型集成：自动识别 Base URL 适配 DeepSeek/Qwen/ChatGLM 等国产模型，方便做国产化替代与成本优化。
• 开源 Agent 学习与二次开发：CC BY-NC-SA 许可 + 模块化结构 + 完善文档，社区开发者可阅读源码做定制改造或学习 Agent 框架设计原理。

适用人群

• AI 应用开发者：希望搭建 LLM Agent 工程但又不想被某家商业平台锁定的工程师。
• LLM 研究与教学人员：需要可读、可改、可教学的 Agent 框架源码来做论文复现或课堂教学。
• 数据与算法工程师：做 RAG/GraphRAG/检索增强项目，需要结构化检索 + 评估 + 重排的完整组件库。
• 企业架构师：评估"自建 Agent 中台 vs 引入商业方案"，需要一个能跑得起来的最小可用原型。
• 学生与初学者：跟随 Datawhale 教程从零入门多智能体框架设计与实现。

工作原理

HelloAgents 围绕「Agent Loop → 组件组合 → 上下文工程」三层架构。底层 runtime/ 定义运行循环（共享调用预算/会话持久化/异步生命周期/流式输出），通过 SimpleAgent.run(prompt) 暴露入口；中层 agents/ 提供四种范式（Simple/ReAct/Reflection/PlanSolve），将循环与决策策略解耦；上层 tools/、context/、retrieval/、memory/、background/、observability/、skills/ 七个组件域各自以 Protocol 暴露接口，由 AgentComponents 按需注入。

Function Calling 路径上，HelloAgentsLLM 启动时根据 LLM_BASE_URL 自动推断 provider；每次循环把对话历史、工具定义、上下文预算一起塞进 ContextBuilder 组装成 ContextPacket，由 LLM 决定调用哪个工具；工具结果经 ToolResponse 统一格式化，由 ObservationTruncator 截断过长返回，写回 HistoryManager；整套流程被 TraceLogger 与 DevLog 持久化。检索与记忆组件走独立管线：RAG 通过 RAGStore 做 BM25 + 向量混合召回与重排，记忆通过 MemoryStore 做语义记忆与用户画像检索，两者结果可注入 ContextBuilder 作为额外上下文。

官方链接

• GitHub 仓库：https://github.com/jjyaoao/HelloAgents
• PyPI 包：https://pypi.org/project/hello-agents/
• AtomGit 镜像：https://atomgit.com/jjyaoao/HelloAgents
• Datawhale 教程仓库：https://github.com/datawhalechina/hello-agents
• 学习版分支：https://github.com/jjyaoao/HelloAgents/tree/learn_version
• Golang 社区版：https://github.com/chaojixinren/HelloAgents-go
• TypeScript 社区版：https://github.com/JunLang-7/HelloAgents-ts
• 许可证：CC BY-NC-SA 4.0（署名-非商业-相同方式共享）