Agentica

一个人，一支 agent 团队。
CLI 终端、本机 Web、Desktop App 是同一套产品，跑在你自己的机器上。

⬇️ 下载桌面版

macOS · Windows · Linux

简体中文 | English

为什么选 Agentica

1. 🏆 同一个模型，更少的时间和 token

工具面刻意收窄、接口保持底层，对 DeepSeek 等开放模型深度适配。和 OpenAI Codex 各跑同一个模型、同一批公开题目，正面对比：

Benchmark: Agentica 在 coding 与 data analysis 两个公开题库上准确率不低于 Codex，墙钟和输入 token 都少一截

编程题全对、数据分析题准确率更高——而且快一倍、输入 token 少三分之二。 复现命令、逐项指标与原始 predictions.jsonl 见评测页。

2. 🤝 一个会话是一个 agent，多个会话是一支队伍

一个终端会话就是一个可协作的 agent。进程内 task 拉临时 subagent，进程级 delegate 另起一整个 agent 去干独立的大活，跨终端 peer 消息让两个会话互相说话——都不需要额外部署任何东西。

3. 🧬 自进化，越用越强

跑完的经验自动编译成可跨会话复用的 SKILL.md；下次遇到同类任务，agent 读的是自己上次的结论，不是从零开始。流程见 Skills 文档。

4. 📱 人可以离开现场

微信 / 企微 / 飞书 / Telegram 直连本机 agent：@会话名 自己寻址，或者只说一句人话，让网关 agent 去指挥这台机器上的所有会话。

安装

pip install -U agentica

桌面版

窗口里就是同一套 Web UI，同一 ~/.agentica，和 CLI / 浏览器混用没有区别。

[!IMPORTANT] 桌面版是个壳，服务端仍是 Python 的 gateway。装应用之前先装它： pip install -U "agentica[gateway]"（同一台机器、能在终端里跑起来即可）。

系统	安装包
macOS 11+	Apple 芯片（arm64） · Intel（x64）
Windows 10+	x64 安装程序（NSIS）
Linux x64	AppImage（免安装） · deb

也都附在每个 GitHub Release 里。当前构建未签名，系统可能拦第一次启动，按对应系统操作一次即可：

🍎 macOS 提示「Agentica 已损坏，无法打开」

macOS 给从网络下载的文件加了隔离标记，应用未签名时会被误报成「已损坏」。删掉标记即可：

打开 dmg，把 Agentica.app 拖进「应用程序」。
打开「终端」，粘贴这条命令回车（要输开机密码，输入时不显示字符）：
```
sudo xattr -rd com.apple.quarantine /Applications/Agentica.app
```

🪟 Windows 提示「Windows 已保护你的电脑」

SmartScreen 会拦未签名的安装程序：点「更多信息」→「仍要运行」。只有第一次需要。

🐧 Linux 双击 AppImage 没反应

浏览器下载的 AppImage 默认没有执行权限（deb 走包管理器，没这个问题）：

chmod +x agentica-desktop-linux-x86_64.AppImage

也可以直接从源码跑：cd desktop && npm install && npm start，详见 desktop/README.md。

配置

配上任一模型厂商的 API Key 即可（优先级：shell 环境变量 > .env > config.yaml）：

export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_API_KEY="sk-xxx"
# 或用可免费起步的智谱：export ZAI_API_KEY="your-api-key"

也可以写进 ~/.agentica/.env，或运行 agentica setup 生成 ~/.agentica/config.yaml（CLI 内随时 /model 切换）。完整说明见安装文档。

快速开始

CLI（推荐先玩这个）

终端输入：

agentica

进交互终端后直接说话，例如「帮我看下这个仓库的单测为什么挂了」。

Web

pip install -U "agentica[gateway]"
agentica-gateway

本机网页在 http://127.0.0.1:8881/chat（聊天、轨迹、设置）。首次启动会建一个 admin 账号并把随机初始密码打在终端里。微信 / 企微 / 飞书 / Telegram 直连见 Gateway 文档。

Python SDK

让 Agent 直接搜资料 + 写文件，一行 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")

开箱即用的完全体（内置工具 + 压缩 + 长期记忆 + skills + MCP）：

from agentica import DeepAgent
agent = DeepAgent()

功能特性

核心引擎

Async-First — 原生 async API，asyncio.gather() 并行工具执行，同步适配器兼容
内置工具 — 搜索、代码执行、文件操作、浏览器、OCR、图像生成
多模型 — OpenAI Chat Completions / Responses API、DeepSeek、Claude、ZhipuAI、Qwen、Moonshot、Ollama、LiteLLM 等
安全守卫 — 输入/输出/工具级 Guardrails，流式实时检测
多模态 — 文本、图像、音频、视频理解

产品入口

CLI — agentica 交互终端；进程内 task、进程级 delegate、跨终端 peer 消息
Web — agentica-gateway 本机 SPA（聊天 / 轨迹 / 设置）+ IM 渠道
Desktop App — Electron 薄壳，同一套 Web，先 attach 再 spawn

协作

多智能体 — SDK：Agent.as_tool()、Workflow、Swarm、Markdown Subagent；CLI：task / delegate / peer 消息（见终端文档）
Actor-Critic 精炼 — refine() + 多 Critic 并行评审，SchemaCritic 程序级零成本验证 / AgentCritic 异构强模型把关，循环检测自动早停

记忆与进化

持久化记忆 — 索引/内容分离、相关性召回、四类型分类、drift 防御；常驻规则写在 AGENTS.md
Skill 系统 — 基于 Markdown 的技能注入，支持项目级、用户级和外部托管 skill 目录
自进化 — 经验卡片自动编译为可跨会话复用的 SKILL.md

集成

MCP / ACP — Model Context Protocol 和 Agent Communication Protocol 支持
RAG — 知识库管理、混合检索、Rerank，集成 LangChain / LlamaIndex

架构与执行引擎（Agentic Loop、两层上下文压缩、四层护栏）见架构文档。

多会话协作：`task` / `delegate` / peer

机制	做什么	何时用
`task`	同进程 subagent（默认 auxiliary 模型，只读）	搜代码、查资料等短活
`delegate`	另起一个完整 `agentica --query --print` 进程	需要独立 context / 另一目录的大活；`/ps`、`wait`、`/stop` 可管
peer	两个交互终端互发纯文本（`list_agents` / `send_message`）	告诉另一会话「这边改了什么」，不是雇工

选型细节：Choosing · 终端文档。

示例

查看 examples/ 获取完整示例，涵盖：

类别	内容
基础用法	Hello World、流式输出、结构化输出、多轮对话、多模态、Agentic Loop 对比
工具	自定义工具、Async 工具、搜索、代码执行、并行工具、并发安全、成本追踪、沙箱隔离、压缩
Agent 模式	Agent 作为工具、并行执行、团队协作、辩论、路由分发、Swarm、子 Agent、模型层钩子、会话恢复
安全护栏	输入/输出/工具级 Guardrails、流式护栏
记忆	会话历史、WorkingMemory、上下文压缩、Workspace 记忆、LLM 自动记忆
RAG	PDF 问答、高级 RAG、LangChain / LlamaIndex 集成
工作流	数据管道、投资研究、新闻报道、代码审查
MCP	Stdio / SSE / HTTP 传输、JSON 配置
可观测性	Langfuse、Token 追踪、Usage 聚合
应用	LLM OS、深度研究、客服系统、金融研究（6-Agent 流水线）

→ 查看完整示例目录

和其它 Agent CLI 对比

	Agentica	Claude Code	Codex CLI
模型选择	✅ 多厂商自由切换	仅 Claude 模型	仅 OpenAI 模型
跨终端多会话协作	✅ peer + `delegate` / `task`	❌	❌
Web + Desktop + IM	✅ 本机网页 / Desktop App / 微信企微飞书 Telegram	❌	❌
自进化 Skill	✅ 经验自动编译 `SKILL.md`	❌	❌
Python SDK	✅ 完整 SDK，可嵌入任意代码	部分（绑定 Claude）	❌
开源	✅ Apache 2.0	❌	✅

🔥 News

[2026/08/20] v1.4.13：Web 换成 Vite + React SPA 并新增轨迹页；网页界面默认英文、设置里可切简体中文；新增 Desktop App 安装包（macOS dmg / Windows NSIS / Linux AppImage·deb）。详见 Release-v1.4.13
[2026/08/10] v1.4.12：上下文压缩升级：三层上下文压缩收敛为两层（截断旧 tool result → LLM/native 摘要）；新增跨终端 peer 消息（list_agents / send_message）与进程级 delegate（独立 agentica --query --print，经 /ps /stop wait 托管），与进程内 task 分工明确。详见 Release-v1.4.12
[2026/08/04] v1.4.11：新增 OpenAI Responses API（含原生 compaction）、Markdown 可配置 subagent、apply_patch 多文件；CLI resume/状态栏/压缩提示增强；裁减 prompt 与 grep/glob schema；修复 Learned Experiences 污染与 write_todos 全量回显。详见 Release-v1.4.11

更多版本

[2026/07/24] v1.4.10：支持视觉模型原生图片输入与模型能力 catalog 路由；新增 /rename 和按名称 /resume。详见 Release-v1.4.10
[2026/07/21] v1.4.9：内置 subagent 全部改为只读；edit_file 改为 tip 提示而非硬拒；修复 ask_user_question CLI 卡死。详见 Release-v1.4.9
[2026/07/05] v1.4.7：CLI 新增 cron 运行时（/cron 命令 + daemon）、自管理（/upgrade、/config set|env）；统一配置到 ~/.agentica/config.yaml。详见 Release-v1.4.7
[2026/06/03] v1.4.6：支持fallback模型可配置，支持多个fallback模型；支持 LSP， CLI 开启 LSP 开关（--enable-diagnostics/--diagnostics-server）；支持 agentica doctor；支持 /goal 长程任务。详见 Release-v1.4.6
[2026/05/11] v1.4.4：MemoryExtractHooks 优化，新增 auto_extract_memory_background 后台抽取（不再阻塞 on_agent_end），memory 抽取优先走更快更便宜的 auxiliary_model。详见 Release-v1.4.4
[2026/05/10] v1.4.3：Skill 生命周期重构 + VaG 解耦，新增 SkillLifecycleHooks 统一扩展点。详见 Release-v1.4.3

文档

完整使用文档：https://shibing624.github.io/agentica

社区与支持

如果 Agentica 帮到了你，欢迎点个 ⭐ Star，让更多人看到！

GitHub Issues — 提交 issue
微信群 — 添加微信号 xuming624，备注 "llm"，加入技术交流群

引用

如果您在研究中使用了 Agentica，请引用：

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

BibTeX：

@misc{xu2026agentica,
  author    = {Xu, Ming},
  title     = {Agentica: A Human-Centric Framework for Large Language Model Agent Workflows},
  year      = {2026},
  publisher = {GitHub},
  url       = {https://github.com/shibing624/agentica}
}

仓库根目录也提供了 CITATION.cff。

许可证

Apache License 2.0

贡献

欢迎贡献！请查看 CONTRIBUTING.md。

致谢

ollama azure litellm google groq mistral cohere bedrock mcp acp rag chroma lancedb qdrant pgvector pinecone milvus weaviate huggingface ddg wikipedia serper exa bocha tavily yfinance arxiv newspaper dblp dalle cogview cogvideo ocr image-analysis video-analysis browser crawl jupyter sql e2b resend volc-tts weather tools-search tools-research tools-finance tools-media tools-browser tools-extra vectordbs postgres mysql redis mongo storage gateway telegram discord slack qq wecom dingtalk wechat langfuse opentelemetry tracing models full dev

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

agentica-1.4.13.tar.gz (1.3 MB view details)

Uploaded Aug 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

agentica-1.4.13-py3-none-any.whl (1.5 MB view details)

Uploaded Aug 20, 2026 Python 3

File details

Details for the file agentica-1.4.13.tar.gz.

File metadata

Download URL: agentica-1.4.13.tar.gz
Upload date: Aug 20, 2026
Size: 1.3 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.5

File hashes

Hashes for agentica-1.4.13.tar.gz
Algorithm	Hash digest
SHA256	`2fd83eb208c75f07ccb6a4bde3157818a1f80a76fdf66eb4ed469f3e031237fb`
MD5	`f57a6da55485d7037d6b6942d1f06884`
BLAKE2b-256	`4df12d94916bd1b576f72d3ba49899145a9995b20a22ee3ccffcb838286e6a39`

See more details on using hashes here.

File details

Details for the file agentica-1.4.13-py3-none-any.whl.

File metadata

Download URL: agentica-1.4.13-py3-none-any.whl
Upload date: Aug 20, 2026
Size: 1.5 MB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.5

File hashes

Hashes for agentica-1.4.13-py3-none-any.whl
Algorithm	Hash digest
SHA256	`85817930509a1f5111c3ac23b58001811691060a25e8694bea531791d269468e`
MD5	`2fc047012b8695738de6cf5ed87da63a`
BLAKE2b-256	`403381f93d5392812199a5394241eea69a17eda6ebd2ec094a4eeec90cca2a54`