shibing624/agentica

Agentica – 本地多代理 LLM 框架

這是什麼 – Agentica 是一個開源、採用 Apache-2.0 授權的 Python 套件，讓您能在自己的電腦上執行大型語言模型代理。它提供了一個單一引擎，可透過三個共享相同狀態的前端來存取：

• CLI – 一個互動式終端機 (agentica)，其中每個對話都是一個自主代理。
• 網頁閘道器 – 一個本地 SPA (agentica‑gateway)，位於 http://127.0.0.1:8881/chat，具備多使用者帳號、聊天紀錄以及 IM 橋接器（WeChat、Feishu、Telegram 等）。
• 桌面應用程式 – 原生的 macOS/Windows/Linux 版本，嵌入了相同的 UI 與資料目錄 (~/.agentica)。

這三者都在相同的後端上執行，因此您可以在它們之間切換而不會遺失上下文或記憶。

---

核心概念

概念	Agentica 如何實現
一個模型，多個代理	單一 LLM（OpenAI、DeepSeek、Claude、ZhipuAI、Qwen、Ollama 等）為每個工作階段提供動力。每個終端機工作階段都是一個代理；您可以生成臨時的子代理 (task) 或全流程委派者 (delegate)。
自我演化	在任務完成後，Agentica 會將經驗擷取為 Markdown skill (SKILL.md)。未來類似的任務會自動重複使用該 skill，減少從頭開始的需要。
持久記憶	聊天紀錄、檔案工作區和擷取的記憶會儲存在磁碟上，針對相關性進行索引，並透過雙層上下文壓縮管線進行壓縮。
工具使用	用於檔案 I/O、修補、grep/glob、命令執行和網頁搜尋的內建工具。工具以非同步方式執行，且可以並行串流。
安全防護	輸入、輸出和工具層級的防護機制，可即時過濾內容。
多模態	在底層模型允許的情況下，支援文字、影像、音訊和視訊輸入。
協作	代理可以跨終端機互相通訊（peer 訊息），並且可以透過 Python/TypeScript SDK 組合成工作流程、群集或辯論式迴圈。
RAG 與整合	內建知識庫管理、混合檢索、重新排序，以及 LangChain / LlamaIndex 的轉接器。
協定	實作了 Model Context Protocol (MCP) 和 Agent Communication Protocol (ACP) 以進行標準化的資料交換。

---

快速開始 (Python 優先)

# Install the core package
pip install -U agentica

# Run the interactive CLI
agentica

在 CLI 中，您可以輸入自然語言命令，例如：

帮我看下这个仓库的单测为什么挂了

---

網頁閘道器與桌面應用程式

# Install the gateway extras (includes FastAPI + UI)
pip install -U "agentica[gateway]"
agentica-gateway   # starts the local web UI at http://127.0.0.1:8881/chat

Docker – 提供了隨開即用的映像檔；只需在 .env.docker.example 中設定 OPENAI_API_KEY 並執行 docker compose up。

桌面版本提供為未簽署的 DMG (macOS)、NSIS 安裝程式 (Windows) 和 AppImage/DEB (Linux)。首次啟動會自動安裝內建的 Python 3.12 執行階段。

---

SDK

• Python – 以程式設計方式建立代理：

from agentica import DeepAgent
agent = DeepAgent()               # full‑featured agent with tools, memory, skills
agent.run_sync("写一篇关于 Python 3.13 新特性的报告到 report.md")

• TypeScript – 從 Node 與執行中的閘道器通訊：

import { Agentica } from "@agentica-ai/sdk";
const client = new Agentica({baseURL: "http://127.0.0.1:8881", apiKey: process.env.AGENTICA_GATEWAY_TOKEN});
for await (const ev of client.chat.stream({message: "ping", session_id: "demo"})) {
  if (ev.event === "content") process.stdout.write(String(ev.data));
}

這兩個 SDK 都公開了相同的非同步優先 API，允許將代理當作工具在其他代理內部使用、執行工作流程，或是建置自訂 UI。

---

為什麼選擇 Agentica？

1. 與模型無關 – 適用於任何 OpenAI 相容或本地端模型；您可以切換供應商而無需更改程式碼。
2. 本地優先 – 所有資料都保留在您的機器上；除了 LLM API 之外，不需要任何外部 SaaS。
3. 團隊式代理 – 內建的子代理、委派者和對等訊息概念，讓您能夠協調複雜的多步驟工作。
4. 自我學習 – skills 會從過去的執行中自動產生，讓系統隨著時間推移變得更快、更便宜。
5. 豐富的 UI 選項 – CLI、基於瀏覽器的 SPA 和原生桌面用戶端共享相同的歷史紀錄和工作區。

---

文件與社群

• 完整文件：https://shigbing624.github.io/agentica
• 範例庫：https://github.com/shibing624/agentica/tree/main/examples
• 透過 GitHub 回報問題與貢獻。
• 中文 WeChat 群組提供即時協助（QR code 在 README 中）。

---

授權

Apache License 2.0 – 免費供商業和學術使用。

---

總結 – Agentica 是一個可用於生產環境、可擴充的框架，用於在您自己的硬體上建置、執行和演化 LLM 驅動的代理，專注於多代理協作、持久記憶，以及透過 CLI、網頁 UI、桌面應用程式或 SDK 輕鬆整合。