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 系統提供生產就緒的骨架，處理工具編排、上下文限制、持久化、可觀測性等繁瑣工程問題，讓開發者能專注於智能體的領域邏輯。