jjyaoao/HelloAgents

HelloAgents – プロダクショングレードのマルチエージェントフレームワーク (Python)

何であるか – OpenAI互換APIの上に構築されたPythonライブラリで、マルチエージェントアプリケーションを構築するための即戦力で拡張可能なプラットフォームを提供します。ツール応答プロトコル、コンテキスト管理、セッション永続化、サブエージェントルーティング、オプティミスティックファイルロック、サーキットブレーカー、スキルロード、進捗追跡、ログ、観測性、SSEによるストリーミング、非同期ライフサイクルなど、エンジニアリングレベルの機能をバンドルすることで、ボイラープレートではなくエージェントロジックに集中できます。

コアコンセプト

コンポーネント	役割
HelloAgentsLLM	OpenAI互換、Anthropic、Geminiプロバイダーのいずれかをラップ。`LLM_BASE_URL`から自動的に適切なアダプターを検出します。
エージェントベースクラス (`ReActAgent`, `SimpleAgent`, `ReflectionAgent`, `PlanAndSolveAgent`)	関数呼び出し / ReActパターンを実装。ツール呼び出し、ツール応答、反復的推論を処理します。
ToolRegistry & ToolResponse	ビルトインまたはカスタムツール（ファイル読み書き、タスク委任、TODO追跡、開発ログ、スキル抽出）を登録。レジストリは`ToolResponse`スキーマを強制します。
SessionStore	会話履歴をディスクに永続化し、エージェントが後から再開できるようにします。
HistoryManager / TokenCounter / ContextBuilder	コンテキストウィンドウを管理、トークン数をカウント、制限に達した場合に切り詰めます。
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("プロジェクト構造を分析してレポートを生成")

API認証情報を含む.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システムのプロダクション対応の骨組みを提供し、ツールオーケストレーション、コンテキスト制限、永続化、観測性といった面倒なエンジニアリング課題を処理することで、開発者がエージェントのドメインロジックに集中できるようにします。