Skip to content

README_JP.md

Latest commit

 

History

History
239 lines (168 loc) · 15.3 KB

README_JP.md

File metadata and controls

239 lines (168 loc) · 15.3 KB
Raw

🇨🇳中文 | 🌐English | 🇯🇵日本語

Agentica

Agent を「何時間でも走らせる」——暴走せず、実際に手を動かし、使うほど強くなる。 Async-first Python agent harness · 40+ ツール · 20+ モデル · MCP · CLI + Web Gateway

PyPI version Downloads GitHub stars License Apache 2.0 python_version last commit GitHub issues Wechat Group

Agentica は単なる LLM API のチャットラッパーではなく、Async-First の agent harness です——エージェントを本当に「動かす」：ツール呼び出し、長時間タスク、マルチエージェント協調、セッションをまたぐ記憶、そして継続的な自己進化。
長く走る、暴走しない Runner 駆動の LLM ↔ ツール長ループ。コンテキスト圧縮・コスト予算・無限ループ防止を内蔵し、長時間タスクが途切れない
手を動かす、雑談だけではない ファイル・実行・検索・ブラウザ・MCP・マルチエージェント・Workflow——単一 IDE に縛られず実際に作業する
覚える、そして忘れる 記憶はエントリ単位で保存・関連性想起・drift 防御。確認済みの好みをグローバルな ~/.agentica/AGENTS.md に同期
使うほど強くなる ツール失敗 / ユーザー修正 / 成功シーケンスが経験カードになり、再利用可能な SKILL.md へ自動コンパイル、セッションをまたいで有効
すべて交換可能、ロックインしない モデル・ツール・記憶・Skill・Guardrails・MCP はすべて置換可能な部品。閉鎖的な SaaS ブラックボックスではない

他フレームワークとの比較

Agentica LangChain AutoGen / CrewAI Pydantic AI
Async-first agentic loop ✅ 圧縮/予算/暴走防止 内蔵 部分拼装 ✅ ✅
自己進化 Skill ✅ SKILL.md 自動コンパイル ❌ ❌ ❌
/goal 長時間タスクループ ✅ ❌ ❌ ❌
セッションをまたぐ永続記憶 ✅ すぐ使える 自前組み立て 部分 自前組み立て
CLI + Web Gateway 同梱 ✅ ❌ ❌ ❌

🔥 News

  • [2026/07/24] v1.4.10：カタログ駆動のモデル能力判定によるネイティブ画像入力を追加；/rename と名前指定の /resume を追加；Pillow コア依存関係のメタデータを修正。詳細は Release-v1.4.10
  • [2026/07/21] v1.4.9：SDK/CLI/Web の権限を 3 階層（ask/auto/allow-all、yolo/full/strict 廃止）に統一；内蔵サブエージェントは読み取り専用化（task のデフォルトを explore に、edit/execute を禁止し aux モデルの低品質コード生成を修正）；OpenAIChat が OpenAI 互換プロキシから漏れた Claude <invoke> テキストツール呼び出しを解析；edit_file を硬拒否から tip 提示に変更；ask_user_question の CLI フリーズを修正。詳細は Release-v1.4.9
  • [2026/07/05] v1.4.7：CLI に統一 braille スピナー（thinking/tool/answering 全フェーズで回転し、稼働中とハングを目視で判別可能）を追加；ask_user_input の入力フリーズと /btw が主モデルを汚染するバグを修正；cron ランタイム（/cron コマンド + デーモン）、自己管理（/upgrade、/config set|env）を追加；設定を ~/.agentica/config.yaml に統一（main + aux model、cli_config.json/task_model を削除、コメントを保持）；/resume が完全/プレフィックス/省略 session id に対応。stream upload の OOM と /api/upload のパストラバーサル（CWE-22）も修正。詳細は Release-v1.4.7
  • [2026/06/03] v1.4.6：クロスプロバイダー fallback がツール呼び出しターンに対応——fallback モデルがツールを呼び出して最終回答を生成でき、そのプロバイダー固有の履歴は圧縮され、主モデルへのリプレイがクリーンに保たれます。fallback モデルは run ごとにクローンされ並行安全性を確保。編集時 LSP 診断 CLI フラグ（--enable-diagnostics/--diagnostics-server）、強化版 agentica doctor、/checkpoint restore --yes 確認、/goal 予算フラグを追加。詳細は Release-v1.4.6
  • [2026/05/11] v1.4.4：MemoryExtractHooks の最適化——新しい auto_extract_memory_background がメモリ抽出をバックグラウンドで実行（on_agent_end をブロックしなくなりました）、抽出は高速・低コストな auxiliary_model を優先。詳細は Release-v1.4.4
  • [2026/05/10] v1.4.3：Skill ライフサイクルのリファクタリング + VaG の分離——VaG 実験コードは evaluation/vag/ 研究モジュールへ移動、統一された SkillLifecycleHooks 拡張ポイントを追加。詳細は Release-v1.4.3

アーキテクチャ

Agentica は、低レベルのモデルルーティングから高レベルのマルチエージェントオーケストレーションまで、完全な抽象化スタックを提供します：

Agentica Architecture

コア実行エンジン (Agentic Loop)

Agent のコアは、ツール呼び出しによって厳密に駆動される決定論的な while(true) エンジン内で実行され、無限ループ防止、コスト追跡、コンテキストのマイクロ圧縮 (Compaction)、および4層のガードレールシステムが組み込まれています：

Agentica Loop Architecture

インストール

pip install -U agentica

クイックスタート

asyncio を学ぶ必要はありません。run_sync は内部で完全な agentic loop （並列ツール呼び出し、ストリーミング、圧縮、リトライ）を実行しますが、 外から見れば普通の同期関数です：

from agentica import Agent, OpenAIChat

agent = Agent(model=OpenAIChat(id="gpt-4o-mini"))
result = agent.run_sync("北京を一文で紹介してください")
print(result.content)
北京は中国の首都であり、三千年以上の歴史を持つ文化都市で、政治・文化・国際交流の中心地です。

Agent に実際に「作業」させる——Web 検索してファイルに書き出す、run_sync 一発：

from agentica import Agent, OpenAIChat, BuiltinWebSearchTool, BuiltinFileTool, BuiltinExecuteTool

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[BuiltinWebSearchTool(), BuiltinFileTool(work_dir="./workspace"), BuiltinExecuteTool(work_dir="./workspace")],
)
agent.run_sync("Python 3.13 の新機能を調べて features.md に書いてください")

機能

  • Async-First — ネイティブ async API、asyncio.gather() による並列ツール実行、同期アダプター対応
  • 20以上のモデル — OpenAI / DeepSeek / Claude / ZhipuAI / Qwen / Moonshot / Ollama / LiteLLM など
  • 40以上の組み込みツール — 検索、コード実行、ファイル操作、ブラウザ、OCR、画像生成
  • RAG — ナレッジベース管理、ハイブリッド検索、Rerank、LangChain / LlamaIndex 統合
  • マルチエージェント — Agent.as_tool()（軽量合成）、Swarm（並列 / 自律）、Workflow（確定的オーケストレーション）
  • Actor-Critic 精錬 — refine() による複数 Critic 並列レビュー、SchemaCritic のゼロコストプログラム検証 / AgentCritic の異種強モデル監査、ループ検出による自動早期停止
  • /goal 長時間タスク — await agent.run_goal("xxx") で目標に向けて継続的に推進、完了・再開・一時停止を自動判定；token / wall-clock / turn の 3 種ハードキャップ対応；CLI の /goal /subgoal はそのまま使えます。詳細は ドキュメント
  • ガードレール — 入力 / 出力 / ツールレベルのガードレール、ストリーミングリアルタイム検出
  • MCP / ACP — Model Context Protocol と Agent Communication Protocol のサポート
  • スキルシステム — Markdown ベースのスキル注入、モデル非依存
  • 永続メモリ — インデックス / コンテンツ分離、関連性ベースの想起、4タイプ分類、drift 防御、グローバル AGENTS.md への同期対応
  • マルチモーダル — テキスト、画像、音声、動画の理解
  • 自己進化 — 経験カードがセッションをまたいで再利用できる SKILL.md に自動コンパイル（フローは下図）
Agentica Self-Evolution Pipeline

Agent レシピ（Recipes）

カスタムツールの組み合わせ

from agentica import Agent, OpenAIChat, BuiltinWebSearchTool, BuiltinFileTool, BuiltinExecuteTool

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[BuiltinWebSearchTool(), BuiltinFileTool(work_dir="./workspace"), BuiltinExecuteTool(work_dir="./workspace")],
)
agent.run_sync("Python 3.13 の新機能を調べて features.md に書いてください")

フルパワー（CLI / Gateway / 長時間タスク）

from agentica import DeepAgent
agent = DeepAgent()  # 40+ 組み込みツール + 圧縮 + 長期記憶 + skills + MCP、すぐに使える

CLI

agentica

長時間タスク：/goal

Agent に目標へ向けて継続的に推進させ、各ラウンド終了時に自動で完了を判定、未完了なら続行——judge が done と言うか、予算が尽きるか、ユーザーが手動で止めるまで。

CLI：

/goal xxx 機能を実装し pytest を通す    # 目標設定 + 自動開始
/goal status                         # 状態・予算・subgoals を表示
/goal pause | resume | clear
/subgoal 単体テストを追加する            # 目標に受入条件を追加

完全な解説：Standing Goal Loop ドキュメント。

Web UI / IM Integration

pip install -U "agentica[gateway]"

起動：

agentica-gateway

デフォルトでは http://127.0.0.1:8881/chat で起動します。

IM (QQ / Feishu / WeChat / WeCom / Telegram / Discord / Slack) への接続をサポート。

IM 集成詳細（スキャンコードバインディング、チャネル設定、環境変数）：Gateway ドキュメント。

サンプル

完全なサンプルは examples/ をご覧ください：

カテゴリ 内容
基本 Hello World、ストリーミング、構造化出力、マルチターン、マルチモーダル、Agentic Loop 比較
ツール カスタムツール、Async ツール、検索、コード実行、並列ツール、並行安全、コスト追跡、サンドボックス隔離、圧縮
エージェントパターン Agent-as-Tool、並列実行、チームコラボレーション、ディベート、ルーティング、Swarm、サブエージェント、モデルレイヤーフック、セッション復元
ガードレール 入力 / 出力 / ツールレベルのガードレール、ストリーミングガードレール
メモリ セッション履歴、WorkingMemory、コンテキスト圧縮、Workspace メモリ、LLM 自動メモリ
RAG PDF Q&A、高度な RAG、LangChain / LlamaIndex 統合
ワークフロー データパイプライン、投資リサーチ、ニュースレポート、コードレビュー
MCP Stdio / SSE / HTTP トランスポート、JSON 設定
可観測性 Langfuse、トークン追跡、Usage 集約
アプリケーション LLM OS、ディープリサーチ、カスタマーサービス、金融リサーチ（6-Agent パイプライン）

→ 完全なサンプルディレクトリを見る

ドキュメント

完全なドキュメント：https://shibing624.github.io/agentica

コミュニティとサポート

Agentica がお役に立てば、ぜひ ⭐ Star をお願いします——より多くの人に届きます。337 stars and growing 🚀

  • GitHub Issues — issue を開く
  • WeChat Group — WeChat で xuming624 を追加し、「llm」と伝えて開発者グループに参加

引用

研究で Agentica を使用する場合は、以下を引用してください：

Xu, M. (2026). Agentica: A Human-Centric Framework for Large Language Model Agent Workflows. GitHub. https://github.com/shibing624/agentica

ライセンス

Apache License 2.0

貢献

貢献を歓迎します！CONTRIBUTING.md をご覧ください。

謝辞