Skip to content
Back to search

HelloAgents

A agent framework based on the tutorial hello-agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jjyaoao--helloagents/badge.svg)](/listings/jjyaoao--helloagents)

HTML

<a href="/listings/jjyaoao--helloagents"><img src="/api/listings/jjyaoao--helloagents/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

推荐使用 64 位 Python 3.13,也支持 Python 3.12。在仓库根目录选择一种安装方式;3.12 运行时显示推荐提示,不会因此停止。

使用 uv:

uv sync --locked
uv run --locked python -X utf8 -m examples.agents.async_agent_demo

使用 pip(先创建并激活虚拟环境):

python -m pip install -r requirements.txt
python -X utf8 -m examples.agents.async_agent_demo

更多安装选项见[安装指南](docs/installation.md),按功能查看[示例代码](examples/README.md)。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 294 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # HelloAgents
  2. > 🤖 组件化多智能体框架 - Agent Loop、工具执行、上下文工程、知识检索与持久记忆
  3. <p>
  4. <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12--3.13-blue.svg" alt="Python 3.12–3.13" style="display: inline-block; vertical-align: middle; margin: 0;" /></a>
  5. <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/"><img src="https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg" alt="License: CC BY-NC-SA 4.0" style="display: inline-block; vertical-align: middle; margin: 0;" /></a>
  6. </p>
  7. HelloAgents 是一个围绕原生 Function Calling 构建的**组件化多智能体框架**,从简单的工具调用循环,到具备上下文管理、知识检索、持久记忆与多智能体协作的应用,为智能体开发提供可组合的工程组件。
  8. 框架集成**工具响应协议、上下文工程、会话持久化、子代理、Skills、流式输出与运行追踪**,并提供 **MCP 工具接入、RAG 与 GraphRAG、结构化用户画像、语义记忆检索和后台任务**。通过 `SimpleAgent` 快速搭建 Agent Loop,再按需加入执行权限、调用预算、熔断与恢复机制;检索、记忆和上下文组件也可独立使用。
  9. ## 📌 版本说明
  10. > **重要提示**:本仓库目前维护两个版本
  11. - **📚 学习版本(推荐初学者)**:[learn_version 分支](https://github.com/jjyaoao/HelloAgents/tree/learn_version)
  12. 与 [Datawhale Hello-Agents 教程](https://github.com/datawhalechina/hello-agents) 正文完全对应的稳定版本,适合跟随教程学习使用。
  13. - **🚀 当前版本(v1.0.1)**:提供工具调用、上下文、检索记忆与组件组合,文档和案例均按当前源码维护。跟随 Hello-Agents 原教程时,请使用 `learn_version` 分支。
  14. - **🔁 AtomGit 镜像仓库**:[https://atomgit.com/jjyaoao/HelloAgents](https://atomgit.com/jjyaoao/HelloAgents) — 用于同步 GitHub 仓库内容,便于国内网络环境访问。
  15. - **📦 历史版本**:[Releases 页面](https://github.com/jjyaoao/HelloAgents/releases)
  16. 提供从 v0.1.1 到 v0.2.9 的所有版本,每个版本对应教程的特定章节,可根据学习进度选择对应版本。
  17. - **🐹 Golang 开发版本**:[HelloAgents-go](https://github.com/chaojixinren/HelloAgents-go)
  18. 社区贡献的 HelloAgents 的 Go 语言重实现版本,适合 Go 语言开发者使用。
  19. - **🔷 TypeScript 开发版本**:[HelloAgents-ts](https://github.com/JunLang-7/HelloAgents-ts)
  20. 社区贡献的 HelloAgents 的 TypeScript 语言重实现版本,适合 TypeScript 语言开发者使用。
  21. ## 🚀 快速开始
  22. ### 安装
  23. 推荐使用 64 位 Python 3.13,也支持 Python 3.12。在仓库根目录选择一种安装方式;3.12 运行时显示推荐提示,不会因此停止。
  24. 使用 uv:
  25. ```bash
  26. uv sync --locked
  27. uv run --locked python -X utf8 -m examples.agents.async_agent_demo
  28. ```
  29. 使用 pip(先创建并激活虚拟环境):
  30. ```bash
  31. python -m pip install -r requirements.txt
  32. python -X utf8 -m examples.agents.async_agent_demo
  33. ```
  34. 更多安装选项见[安装指南](docs/installation.md),按功能查看[示例代码](examples/README.md)。
  35. ### 基本使用
  36. ```python
  37. from dotenv import load_dotenv
  38. from hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry
  39. from hello_agents.tools import CalculatorTool
  40. load_dotenv() # 显式加载当前应用的 .env
  41. registry = ToolRegistry()
  42. registry.register_tool(CalculatorTool())
  43. with HelloAgentsLLM() as llm:
  44. agent = SimpleAgent("assistant", llm, tool_registry=registry)
  45. print(agent.run("调用计算器计算两晚住宿每晚 320 元,加上 180 元交通费的总预算"))
  46. ```
  47. `SimpleAgent` 执行“模型请求 → 工具执行 → 回执 → 再次调用”的循环。默认不自动注册 Skills、子代理、待办或日志工具,也不创建会话与追踪目录;需要时通过 `Config` 或 `AgentComponents` 开启。详见[运行循环](docs/runtime-guide.md)。
  48. ### 环境配置
  49. 创建 `.env` 文件:
  50. ```bash
  51. LLM_MODEL_ID=your-model-name
  52. LLM_API_KEY=your-api-key-here
  53. LLM_BASE_URL=your-api-base-url
  54. ```
  55. ```python
  56. # 根据服务地址选择适配器
  57. llm = HelloAgentsLLM()
  58. print(f"检测到的 provider: {llm.provider}")
  59. ```
  60. > 💡 **智能检测**: 框架根据 Base URL 选择适配器;模型名称与密钥由环境配置提供
  61. ### 支持的 LLM 提供商
  62. 框架提供 **3 种适配器**。服务需要支持对应的消息与工具调用协议:
  63. #### 1. OpenAI 兼容适配器(默认)
  64. 支持所有提供 OpenAI 兼容接口的服务:
  65. | 提供商类型 | 示例服务 | 配置示例 |
  66. | ------------ | -------------------------------------- | ------------------------------------ |
  67. | **云端 API** | OpenAI、DeepSeek、Qwen、Kimi、智谱 GLM | `LLM_BASE_URL=https://api.deepseek.com` |
  68. | **本地推理** | vLLM、Ollama、SGLang | `LLM_BASE_URL=http://localhost:8000/v1` |
  69. | **其他兼容** | 任何 OpenAI 格式接口 | `LLM_BASE_URL=your-endpoint` |
  70. #### 2. Anthropic 适配器
  71. | 提供商 | 检测条件 | 配置示例 |
  72. | ---------- | ------------------------------- | ---------------------------------------- |
  73. | **Claude** | `base_url` 包含 `anthropic.com` | `LLM_BASE_URL=https://api.anthropic.com` |
  74. #### 3. Gemini 适配器
  75. | 提供商 | 检测条件 | 配置示例 |
  76. | ----------------- | -------------------------------------------------------- | -------------------------------------------------------- |
  77. | **Google Gemini** | `base_url` 包含 `googleapis.com` 或 `generativelanguage` | `LLM_BASE_URL=https://generativelanguage.googleapis.com` |
  78. > 💡 **自动适配**:框架根据 `base_url` 自动选择适配器,无需手动指定。
  79. ### 组件扩展
  80. 检索、记忆与上下文可以独立使用,也可以通过 `AgentComponents` 注入运行组件。示例:[旅行助手](examples/applications/travel_assistant.py) · [工具与会话恢复](examples/agents/runtime_features.py)。两者默认均可离线运行,具体用法见下方文档。
  81. ## 🏗️ 项目结构
  82. ```
  83. hello-agents/
  84. ├── hello_agents/ # 主包
  85. │ ├── core/ # 核心组件
  86. │ │ ├── llm.py # LLM 基类与配置
  87. │ │ ├── llm_adapters.py # OpenAI / Anthropic / Gemini
  88. │ │ ├── agent.py # Agent 基类(Function Calling 架构)
  89. │ │ ├── components.py # AgentComponents
  90. │ │ ├── runtime.py # 模型与工具运行循环
  91. │ │ ├── budget.py # 跨模型共享调用预算
  92. │ │ ├── session_store.py # 会话持久化
  93. │ │ ├── lifecycle.py # 异步生命周期
  94. │ │ └── streaming.py # SSE 流式输出
  95. │ ├── agents/ # Agent 实现
  96. │ │ ├── simple_agent.py # SimpleAgent
  97. │ │ ├── react_agent.py # ReActAgent
  98. │ │ ├── reflection_agent.py # ReflectionAgent
  99. │ │ └── plan_solve_agent.py # PlanSolveAgent
  100. │ ├── tools/ # 工具系统
  101. │ │ ├── registry.py # 工具注册表
  102. │ │ ├── response.py # ToolResponse 协议
  103. │ │ ├── circuit_breaker.py # 熔断器
  104. │ │ ├── mcp.py # MCP stdio / HTTP 工具桥接
  105. │ │ ├── permissions.py # 宿主执行权限
  106. │ │ ├── tool_filter.py # 工具过滤(子代理机制)
  107. │ │ └── builtin/ # 内置工具
  108. │ │ ├── file_tools.py # 文件工具(乐观锁)
  109. │ │ ├── task_tool.py # 子代理工具
  110. │ │ ├── todowrite_tool.py # 进度管理
  111. │ │ ├── devlog_tool.py # 决策日志
  112. │ │ ├── skill_tool.py # Skills 知识外化
  113. │ │ ├── rag_tool.py # 检索与来源回读
  114. │ │ ├── memory_tool.py # 记忆维护
  115. │ │ ├── graphrag_tool.py # 图检索与全局综合
  116. │ │ └── relation_tool.py # 关系证据检索
  117. │ ├── context/ # 上下文工程
  118. │ │ ├── history.py # HistoryManager
  119. │ │ ├── token_counter.py # TokenCounter
  120. │ │ ├── truncator.py # ObservationTruncator
  121. │ │ ├── builder.py # ContextBuilder 与预算诊断
  122. │ │ ├── types.py # ContextPacket / ContextBuildResult
  123. │ │ └── providers.py # 上下文收集与组装
  124. │ ├── retrieval/ # 检索组件
  125. │ │ ├── store.py # RAGStore / BM25
  126. │ │ ├── embeddings.py # 可替换向量模型
  127. │ │ ├── qdrant.py # Qdrant 向量索引
  128. │ │ ├── hybrid.py # 多路排名融合
  129. │ │ ├── pipeline.py # 召回后端与重排协议
  130. │ │ ├── rerank.py # 模型重排
  131. │ │ ├── evaluation.py # 检索效果评测
  132. │ │ ├── graph/ # 抽取、Leiden 社区与图查询
  133. │ │ └── relations.py # RelationStore
  134. │ ├── memory/ # 用户画像、记忆记录与召回
  135. │ │ ├── store.py # 记忆存储与修订
  136. │ │ ├── search.py # 语义与混合记忆召回
  137. │ │ └── profile.py # ProfileStore 用户画像与上下文注入
  138. │ ├── background/ # 持久任务、租约与恢复
  139. │ ├── storage.py # 数据库版本、迁移与备份
  140. │ ├── observability/ # 可观测性
  141. │ │ └── trace_logger.py # TraceLogger
  142. │ └── skills/ # Skills 系统
  143. │ └── loader.py # SkillLoader
  144. ├── docs/ # 文档
  145. ├── examples/ # 按功能组织的示例
  146. │ ├── agents/ # Agent Loop 与异步执行
  147. │ ├── tools/ # 工具、MCP 与 Skills
  148. │ ├── context/ # 上下文与会话
  149. │ ├── retrieval/ # RAG 与 GraphRAG
  150. │ ├── memory/ # 用户画像与语义记忆
  151. │ ├── runtime/ # 后台任务与运行观测
  152. │ ├── applications/ # 综合案例
  153. │ └── web/ # SSE 服务与客户端
  154. ├── tests/ # 测试用例
  155. ├── requirements/ # 按功能导出的 pip 锁定清单
  156. ├── scripts/sync_requirements.py # 从 uv.lock 导出并检查清单
  157. ├── pyproject.toml # 依赖范围与包配置
  158. ├── uv.lock # uv 锁定结果
  159. └── requirements.txt # 基础安装的 pip 清单
  160. ```
  161. ## 🤝 贡献
  162. 欢迎贡献代码!请遵循以下步骤:
  163. 1. Fork 本仓库
  164. 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
  165. 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
  166. 4. 推送到分支 (`git push origin feature/AmazingFeature`)
  167. 5. 开启 Pull Request
  168. ## 📄 许可证
  169. 本项目采用 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
  170. **许可证要点**:
  171. - ✅ **署名** (Attribution): 使用时需要注明原作者
  172. - ✅ **相同方式共享** (ShareAlike): 修改后的作品需使用相同许可证
  173. - ⚠️ **非商业性使用** (NonCommercial): 不得用于商业目的
  174. 如需商业使用,请联系项目维护者获取授权。
  175. ## 🙏 致谢
  176. - 感谢 [Datawhale](https://github.com/datawhalechina) 提供的优秀开源教程
  177. - 感谢 [Hello-Agents 教程](https://github.com/datawhalechina/hello-agents) 的所有贡献者
  178. - 感谢所有为智能体技术发展做出贡献的研究者和开发者
  179. ## 📚 文档资源
  180. 从基础运行到检索与记忆,按功能选择使用指南。每份文档说明组件用法与配置,配套程序见[示例索引](examples/README.md)。
  181. ### 基础设施
  182. - **[安装与依赖管理](docs/installation.md)** - uv、pip 与版本锁定
  183. - **[运行可靠性与验收](docs/reliability-guide.md)** - 模型关闭、共享预算与数据维护
  184. - **[工具响应协议](docs/tool-response-protocol.md)** - ToolResponse 统一返回格式
  185. - **[上下文工程](docs/context-engineering-guide.md)** - 历史管理、输入组装与预算
  186. - **[组件组合](docs/component-composition-guide.md)** - AgentComponents 按需注入
  187. ### 核心能力
  188. - **[可观测性](docs/observability-guide.md)** - TraceLogger 追踪系统
  189. - **[熔断器](docs/circuit-breaker-guide.md)** - CircuitBreaker 容错机制
  190. - **[会话持久化](docs/session-persistence-guide.md)** - 保存、中断与恢复
  191. ### 知识与记忆
  192. - **[知识检索](docs/rag-guide.md)** - RAG、召回重排与关系证据
  193. - **[检索评测与模型重排](docs/retrieval-evaluation-guide.md)** - Recall、MRR、nDCG 与候选排序
  194. - **[向量与混合检索](docs/qdrant_retrieval.md)** - Qdrant、Embedding 与 RRF
  195. - **[云端检索入门](docs/cloud-retrieval-guide.md)** - 注册一个账号,配置地址与密钥,运行 RAG 和记忆检索
  196. - **[GraphRAG](docs/graphrag-guide.md)** - 实体关系、社区报告与局部/全局查询
  197. - **[持久化记忆](docs/memory-guide.md)** - 偏好、事实、经历与做法的记录管理
  198. - **[用户画像(Profile)](docs/profile-memory-guide.md)** - 结构化偏好、来源、并发修订与跨会话使用
  199. - **[记忆语义检索](docs/semantic-memory-guide.md)** - 向量召回、修订同步与用户隔离
  200. ### 增强能力
  201. - **[子代理机制](docs/subagent-guide.md)** - TaskTool 与 ToolFilter
  202. - **[Skills 知识外化](docs/skills-usage-guide.md)** - 按需加载操作指导
  203. - **[文件编辑](docs/file_tools.md)** - 乐观锁与批量编辑
  204. - **[TodoWrite 进度管理](docs/todowrite-usage-guide.md)** - 任务进度追踪
  205. ### 辅助功能
  206. - **[DevLog 决策日志](docs/devlog-guide.md)** - 开发决策记录
  207. - **[异步生命周期](docs/async-agent-guide.md)** - 异步执行与回调
  208. - **[后台任务](docs/background-jobs-guide.md)** - 持久队列、进度、重试与恢复
  209. ### 核心架构
  210. - **[运行循环](docs/runtime-guide.md)** - 调用入口与结束状态
  211. - **[流式输出](docs/streaming-sse-guide.md)** - 流式事件与 SSE
  212. - **[Function Calling](docs/function-calling-architecture.md)** - 模型请求与工具执行
  213. - **[LLM 消息格式](docs/llm-message-guide.md)** - 消息与工具调用格式
  214. - **[日志系统](docs/logging-system-guide.md)** - 日志与运行轨迹
  215. ### 扩展能力
  216. - **[MCP 工具](docs/mcp-guide.md)** - 工具发现、调用与连接管理
  217. - **[工具权限](docs/tool-policy-guide.md)** - 宿主策略与执行边界
  218. - **[自定义工具](docs/custom_tools_guide.md)** - 函数式、标准类与可展开工具
  219. ---
  220. <div align="center">
  221. **HelloAgents** - 让智能体开发变得简单而强大 🚀
  222. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.