Agent Orchestration
Plugin
helloagents
🤖 生产级多智能体框架 - 工具响应协议、上下文工程、会话持久化、子代理机制等16项核心能力 HelloAgents 是一个基于 OpenAI 原生 API 构建的生产级多智能体框架，集成了工具响应协议（ToolResponse）、上下文工程（HistoryManager/TokenCounter）、会话持久化（SessionStore）、子代理机制（TaskTool）、乐观锁（文件编辑）、熔断器（CircuitBreaker）、Skills 知识外化、TodoWrite 进度管理、DevLog
Plugin Signal63/100Solid
maintained69
capable60
documented50
adopted73
Install
$ npx -y skills add jjyaoao/helloagents --agent claude-code
What's inside
Skill(17 skills)
/ASRImplement speech-to-text (ASR/automatic speech recognition) capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to transcribe audio files, convert speech to text, build voice input features, or process audio recordings. Supports base64 encoded audio files/LLMImplement large language model (LLM) chat completions using the z-ai-web-dev-sdk. Use this skill when the user needs to build conversational AI applications, chatbots, AI assistants, or any text generation features. Supports multi-turn conversations, system prompts, and context/TTSImplement text-to-speech (TTS) capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to convert text into natural-sounding speech, create audio content, build voice-enabled applications, or generate spoken audio files. Supports multiple voices, adjustable/VLMImplement vision-based AI chat capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to analyze images, describe visual content, or create applications that combine image understanding with conversational AI. Supports image URLs and base64 encoded images/docxComprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When GLM needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content,/financeComprehensive Finance API integration skill for real-time and historical financial data analysis, market research, and investment decision-making. Priority use cases: stock price queries, market data analysis, company financial information, portfolio tracking, market news
README
HelloAgents
🤖 生产级多智能体框架 - 工具响应协议、上下文工程、会话持久化、子代理机制等16项核心能力
HelloAgents 是一个基于 OpenAI 原生 API 构建的生产级多智能体框架，集成了工具响应协议（ToolResponse）、上下文工程（HistoryManager/TokenCounter）、会话持久化（SessionStore）、子代理机制（TaskTool）、乐观锁（文件编辑）、熔断器（CircuitBreaker）、Skills 知识外化、TodoWrite 进度管理、DevLog 决策记录、流式输出（SSE）、异步生命周期、可观测性（TraceLogger）、日志系统（四种范式）、LLM/Agent 基类重构等 16 项核心能力，为构建复杂智能体应用提供完整的工程化支持。
📌 版本说明
重要提示：本仓库目前维护两个版本
-
📚 学习版本（推荐初学者）：learn_version 分支 与 Datawhale Hello-Agents 教程 正文完全对应的稳定版本，适合跟随教程学习使用。
-
🚀 开发版本（当前分支）：持续迭代中的最新代码(V1.0.0)，包含新功能和改进，部分实现可能与教程内容存在差异。如需学习教程，请切换到
learn_version分支。 -
🔁 AtomGit 镜像仓库：https://atomgit.com/jjyaoao/HelloAgents 用于同步 GitHub 仓库内容，便于国内网络环境访问。
-
📦 历史版本：Releases 页面 提供从 v0.1.1 到 v0.2.9 的所有版本，每个版本对应教程的特定章节，可根据学习进度选择对应版本。
-
🐹 Golang 开发版本：HelloAgents-go 社区贡献的HelloAgents 的 Go 语言重实现版本，适合 Go 语言开发者使用。
🚀 快速开始
安装
pip install hello-agents
基本使用
from hello_agents import ReActAgent, HelloAgentsLLM, ToolRegistry
from hello_agents.tools.builtin import ReadTool, WriteTool, TodoWriteTool
llm = HelloAgentsLLM()
registry = ToolRegistry()
registry.register_tool(ReadTool())
registry.register_tool(WriteTool())
registry.register_tool(TodoWriteTool())
agent = ReActAgent("assistant", llm, tool_registry=registry)
agent.run("分析项目结构并生成报告")
环境配置
创建 .env 文件：
LLM_MODEL_ID=your-model-name
LLM_API_KEY=your-api-key-here
LLM_BASE_URL=your-api-base-url
# 自动检测provider
llm = HelloAgentsLLM() # 框架自动检测为modelscope
print(f"检测到的provider: {llm.provider}")
💡 智能检测: 框架会根据API密钥格式和Base URL自动选择合适的provider
支持的LLM提供商
框架基于 3 种适配器 支持所有主流 LLM 服务：
1. OpenAI 兼容适配器（默认）
支持所有提供 OpenAI 兼容接口的服务：
| 提供商类型 | 示例服务 | 配置示例 |
|---|---|---|
| 云端 API | OpenAI、DeepSeek、Qwen、Kimi、智谱 GLM | LLM_BASE_URL=api.deepseek.com |
| 本地推理 | vLLM、Ollama、SGLang | LLM_BASE_URL=http://localhost:8000 |
| 其他兼容 | 任何 OpenAI 格式接口 | LLM_BASE_URL=your-endpoint |
2. Anthropic 适配器
| 提供商 | 检测条件 | 配置示例 |
|---|---|---|
| Claude | base_url 包含 anthropic.com | LLM_BASE_URL=https://api.anthropic.com |
3. Gemini 适配器
| 提供商 | 检测条件 | 配置示例 |
|---|---|---|
| Google Gemini | base_url 包含 googleapis.com 或 generativelanguage | LLM_BASE_URL=https://generativelanguage.googleapis.com |
💡 自动适配：框架根据
base_url自动选择适配器，无需手动指定。
🏗️ 项目结构
hello-agents/
├── hello_agents/ # 主包
│ ├── core/ # 核心组件
│ │ ├── llm.py # LLM 基类与配置
│ │ ├── llm_adapters.py # 三种适配器（OpenAI/Anthropic/Gemini）
│ │ ├── agent.py # Agent 基类（Function Calling 架构）
│ │ ├── session_store.py # 会话持久化
│ │ ├── lifecycle.py # 异步生命周期
│ │ └── streaming.py # SSE 流式输出
│ ├── agents/ # Agent 实现
│ │ ├── simple_agent.py # SimpleAgent
│ │ ├── react_agent.py # ReActAgent
│ │ ├── reflection_agent.py # ReflectionAgent
│ │ └── plan_solve_agent.py # PlanAndSolveAgent
│ ├── tools/ # 工具系统
│ │ ├── registry.py # 工具注册表
│ │ ├── response.py # ToolResponse 协议
│ │ ├── circuit_breaker.py # 熔断器
│ │ ├── tool_filter.py # 工具过滤（子代理机制）
│ │ └── builtin/ # 内置工具
│ │ ├── file_tools.py # 文件工具（乐观锁）
│ │ ├── task_tool.py # 子代理工具
│ │ ├── todowrite_tool.py # 进度管理
│ │ ├── devlog_tool.py # 决策日志
│ │ └── skill_tool.py # Skills 知识外化
│ ├── context/ # 上下文工程
│ │ ├── history.py # HistoryManager
│ │ ├── token_counter.py # TokenCounter
│ │ ├── truncator.py # ObservationTruncator
│ │ └── builder.py # ContextBuilder
│ ├── observability/ # 可观测性
│ │ └── trace_logger.py # TraceLogger
│ └── skills/ # Skills 系统
│ └── loader.py # SkillLoader
├── docs/ # 文档
├── examples/ # 示例代码
└── tests/ # 测试用例
🤝 贡献
欢迎贡献代码！请遵循以下步骤：
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
📄 许可证
本项目采用 CC BY-NC-SA 4.0 许可证 - 查看 LICENSE 文件了解详情。
许可证要点：
- ✅ 署名 (Attribution): 使用时需要注明原作者
- ✅ 相同方式共享 (ShareAlike): 修改后的作品需使用相同许可证
- ⚠️ 非商业性使用 (NonCommercial): 不得用于商业目的
如需商业使用，请联系项目维护者获取授权。
🙏 致谢
- 感谢 Datawhale 提供的优秀开源教程
- 感谢 Hello-Agents 教程 的所有贡献者
- 感谢所有为智能体技术发展做出贡献的研究者和开发者
📚 文档资源
详细了解 HelloAgents v1.0.0 的 16 项核心能力：
基础设施
核心能力
增强能力
- 子代理机制 - TaskTool 与 ToolFilter
- Skills 知识外化 - 技能系统使用指南
- 乐观锁 - 文件编辑工具的并发控制
- TodoWrite 进度管理 - 任务进度追踪
辅助功能
- DevLog 决策日志 - 开发决策记录
- 异步生命周期 - 异步 Agent 实现
核心架构
- 流式输出 - SSE 流式响应
- Function Calling 架构 - LLM/Agent 基类重构
- 日志系统 - 四种日志范式
扩展能力
- 自定义工具扩展 - 三种工具实现方式（函数式/标准类/可展开）
HelloAgents - 让智能体开发变得简单而强大 🚀
File tree
jjyaoao/helloagentsView on GitHub
.env.example
.gitignore
.python-version
docs/
async-agent-guide.md
circuit-breaker-guide.md
context-engineering-guide.md
custom_tools_guide.md
devlog-guide.md
file_tools.md
function-calling-architecture.md
logging-system-guide.md
observability-guide.md
session-persistence-guide.md
skills-quickstart.md
skills-usage-guide.md
streaming-sse-guide.md
subagent-guide.md
todowrite-usage-guide.md
tool-response-protocol.md
examples/
async_agent_demo.py
circuit_breaker_demo.py
context_engineering_demo.py
custom_tools/
advanced_tool_template.py
code_formatter_tool.py
complete_example.py
expandable_tool_template.py
simple_tool_template.py
weather_tool.py
devlog_demo.py
fastapi_sse_server.py
file_tools_demo.py
observability_demo.py
parallel_tools_demo.py
session_persistence_demo.py
skills_demo.py
sse_client.html
subagent_demo.py
test_sse_client.py
todowrite_demo.py
todowrite_real_world.py
tool_response_demo.py
hello_agents/
__init__.py
agents/
__init__.py
factory.py
plan_solve_agent.py
react_agent.py
reflection_agent.py
simple_agent.py
context/
__init__.py
builder.py
history.py
token_counter.py
truncator.py
core/
__init__.py
agent.py
config.py
exceptions.py
lifecycle.py
llm_adapters.py
llm_response.py
llm.py
message.py
session_store.py
streaming.py
observability/
__init__.py
trace_logger.py
skills/
__init__.py
loader.py
tools/
__init__.py
base.py
builtin/
__init__.py
calculator.py
devlog_tool.py
file_tools.py
skill_tool.py
task_tool.py
todowrite_tool.py
circuit_breaker.py
errors.py
registry.py
response.py
tool_filter.py
version.py
LICENSE
MANIFEST.in
pyproject.toml
README.md
requirements.txt
setup.py
skills/
ASR/
LICENSE.txt
scripts/
asr.ts
SKILL.md
docx/
CHANGELOG.md
docx-js.md
LICENSE.txt
ooxml/
ooxml.md
schemas/
ecma/
fouth-edition/
opc-contentTypes.xsd
opc-coreProperties.xsd
opc-digSig.xsd
opc-relationships.xsd
ISO-IEC29500-4_2016/
dml-chart.xsd
dml-chartDrawing.xsd
dml-diagram.xsd
dml-lockedCanvas.xsd
dml-main.xsd
dml-picture.xsd
dml-spreadsheetDrawing.xsd
dml-wordprocessingDrawing.xsd
pml.xsd
shared-additionalCharacteristics.xsd
shared-bibliography.xsd
shared-commonSimpleTypes.xsd
shared-customXmlDataProperties.xsd
shared-customXmlSchemaProperties.xsd
shared-documentPropertiesCustom.xsd
shared-documentPropertiesExtended.xsd
shared-documentPropertiesVariantTypes.xsd
shared-math.xsd
shared-relationshipReference.xsd
sml.xsd
vml-main.xsd
vml-officeDrawing.xsd
vml-presentationDrawing.xsd
vml-spreadsheetDrawing.xsd
vml-wordprocessingDrawing.xsd
wml.xsd
xml.xsd
mce/
mc.xsd
microsoft/
wml-2010.xsd
wml-2012.xsd
wml-2018.xsd
wml-cex-2018.xsd
wml-cid-2016.xsd
wml-sdtdatahash-2020.xsd
wml-symex-2015.xsd
scripts/
pack.py
unpack.py
validate.py
validation/
__init__.py
base.py
docx.py
pptx.py
redlining.py
scripts/
__init__.py
add_toc_placeholders.py
document.py
templates/
comments.xml
commentsExtended.xml
commentsExtensible.xml
commentsIds.xml
people.xml
utilities.py
SKILL.md
finance/
Finance_API_Doc.md
SKILL.md
frontend-design/
.gitignore
examples/
css/
components.css
tokens.css
typescript/
design-tokens.ts
sample-components.tsx
theme-provider.tsx
utils.ts
LICENSE
OPTIMIZATION_SUMMARY.md
package.json
README.md
SKILL.md
templates/
globals.css
tailwind.config.js
gift-evaluator/
html_tools.py
SKILL.md
image-generation/
LICENSE.txt
scripts/
image-generation.ts
SKILL.md
LLM/
LICENSE.txt
scripts/
chat.ts
SKILL.md
pdf/
forms.md
LICENSE.txt
reference.md
scripts/
add_zai_metadata.py
check_bounding_boxes_test.py
check_bounding_boxes.py
check_fillable_fields.py
convert_pdf_to_images.py
create_validation_image.py
extract_form_field_info.py
fill_fillable_fields.py
fill_pdf_form_with_annotations.py
sanitize_code.py
SKILL.md
podcast-generate/
generate.ts
LICENSE.txt
package.json
readme.md
SKILL.md
test_data/
segments.jsonl
tsconfig.json
pptx/
SKILL.md
TTS/
LICENSE.txt
SKILL.md
tts.ts
video-generation/
LICENSE.txt
scripts/
video.ts
SKILL.md
video-understand/
LICENSE.txt
scripts/
video-understand.ts
SKILL.md
VLM/
LICENSE.txt
scripts/
vlm.ts
SKILL.md
web-reader/
LICENSE.txt
scripts/
web-reader.ts
SKILL.md
web-search/
LICENSE.txt
scripts/
web_search.ts
SKILL.md
xlsx/
LICENSE.txt
recalc.py
SKILL.md
tests/
test_all_agents.py
test_async_lifecycle.py
test_circuit_breaker.py
test_context_engineering.py
test_custom_tools.py
test_devlog_tool.py
test_file_tools.py
test_llm_function_calling.py
test_llm_streaming.py
test_observability.py
test_pydantic_v2_serialization.py
test_session_persistence.py
test_skills.py
test_smart_summary.py
test_subagent_mechanism.py
test_todowrite.py
test_tool_filter.py
test_tool_response_protocol.py
test_trace_integration.py
uv.lockFAQ
helloagents is a Claude Code plugin with 17 hand-picked skills for agent orchestration work, indexed on Flowy. Install it with the command on its page. It includes ASR, LLM, TTS. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is helloagents?
- 🤖 生产级多智能体框架 - 工具响应协议、上下文工程、会话持久化、子代理机制等16项核心能力 HelloAgents 是一个基于 OpenAI 原生 API 构建的生产级多智能体框架，集成了工具响应协议（ToolResponse）、上下文工程（HistoryManager/TokenCounter）、会话持久化（SessionStore）、子代理机制（TaskTool）、乐观锁（文件编辑）、熔断器（CircuitBreaker）、Skills 知识外化、TodoWrite 进度管理、DevLog
- How do I install helloagents?
- Run these in Claude Code: npx -y skills add jjyaoao/helloagents --agent claude-code. Then prompt normally.
- Does helloagents auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is helloagents free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.