shibing624/agentica

Agentica – 本地多代理 LLM 框架

它是什么 – Agentica 是一个开源、基于 Apache-2.0 许可证的 Python 包，允许您在自己的计算机上运行大型语言模型代理。它提供了一个单一引擎，可通过三个共享相同状态的前端进行访问：

• CLI – 一个交互式终端 (agentica)，其中每个对话都是一个自主代理。
• Web 网关 – 一个本地 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 中，您可以输入自然语言命令，例如：

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

---

Web 网关与桌面应用

# 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 群组提供实时帮助（README 中有二维码）。

---

许可证

Apache License 2.0 – 免费用于商业和学术用途。

---

总结 – Agentica 是一个可用于生产环境、可扩展的框架，用于在您自己的硬件上构建、运行和发展 LLM 驱动的代理，专注于多代理协作、持久记忆，以及通过 CLI、Web UI、桌面应用或 SDK 轻松集成。