Agentica

https://github.com/user-attachments/assets/39fb961e-3979-4629-a87d-81dce9196597

为什么选 Agentica

1. 🏆 同一个模型，更准、更快、更省钱

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

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

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

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

3. 🧬 自进化，越用越强

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

4. 🧠 长会话不失忆：压缩不调 LLM，全文可回取

业界主流的 compact 是让 LLM 把前文概括成摘要——花一次额外调用、有损，而且被概括掉的细节再也拿不回来。Agentica 的压缩路径全程零 LLM 摘要：

• 超大工具输出产生即落盘 — 上下文里只留 2000 字预览（40% 头 + 60% 尾）加一个文件路径，模型要细节自己 read_file 取回；会话本身没有读文件能力时就老实截断并说明，绝不发一个没人打得开的路径
• 窗口吃紧才淘汰 — 占用超过窗口 80% 才动手，最旧优先淘汰回 50%；占位符写明被淘汰的是哪个调用，模型可以原样重发。正在跑的那一轮（未返回的调用 + 末批结果）永不触碰
• 真满窗才换窗 — 装上 <context_window> 和交接 notes 开一个空活动窗，不合成假摘要轮

原文始终留在 session JSONL 里，search_session 随时按词取回。结果：长会话不失忆、不为压缩额外付 token、每个压缩点都可回溯。 细节见 压缩文档。

5. 📱 人可以离开现场

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

安装

CLI（agentica）和 Web / Desktop 后端（agentica-gateway）都用 uv tool 装进隔离环境，不绑系统 Python。没有 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh    # 独立安装，进 ~/.local/bin
# macOS 也可以：brew install uv

# CLI
uv tool install agentica

# Web / Desktop（同一套命令，多出 agentica-gateway）
uv tool install "agentica[gateway]"

已经装过 CLI、再补 Web：uv tool install --force "agentica[gateway]"。升级：uv tool upgrade agentica。命令找不到时跑一次 uv tool update-shell。

开发本仓库用 pip install -e .。详见 安装文档。

桌面版

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

[!IMPORTANT] 当前构建未签名，系统可能拦第一次启动，按对应系统操作一次即可。机器上还没有 agentica-gateway 时，桌面版会在第一次打开时用 uv 安装一份托管 runtime（Python 3.12 + agentica[gateway]），放在 Application Support，不进 ~/.agentica。已经 uv tool install（或旧的 pip install）过的继续用你原来的。

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

1. 打开 dmg，把 Agentica.app 拖进「应用程序」。

2. 打开「终端」，粘贴这条命令回车（要输开机密码，输入时不显示字符）：

   sudo xattr -rd com.apple.quarantine /Applications/Agentica.app
   

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

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

chmod +x Agentica-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

uv tool install "agentica[gateway]"
agentica-gateway

本机网页在 http://127.0.0.1:8881/chat（聊天、轨迹、设置）。首次启动会建一个 default 账号并把随机初始密码打在终端里；管理员可以在「用户管理」页加账号，每个账号有自己独立的会话和记忆。微信 / 企微 / 飞书 / Telegram 直连见 Gateway 文档。

自托管（Docker，镜像里编好 UI，运行时不需要 Node）：

cp .env.docker.example .env   # 填 OPENAI_API_KEY
docker compose up -d --build

浏览器打开 http://127.0.0.1:8881/chat。数据在 named volume，当前目录挂到容器 /workspace。

TypeScript SDK

给已经在跑的 gateway 写 Node 脚本时用，不是启动 Web 的步骤：

npm install @agentica-ai/sdk

包名必须写全 @agentica-ai/sdk（registry.npmjs.org，不要写成 agentica-sdk）。

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

源码在 sdk-ts/。

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() 并行工具执行，同步适配器兼容
• 内置工具 — read_file / write_file / apply_patch / grep / glob、execute、网页搜索；长报告用 write_file 写 HTML
• 多模型 — 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 — App 跟 Web、CLI 共用同一套历史记录、工作目录、模型、配置等状态

协作

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

记忆与进化

• 持久化记忆 — 索引/内容分离、相关性召回、四类型分类、drift 防御；常驻规则写在 AGENTS.md
• 无损上下文压缩 — 全程零 LLM 摘要：超大 tool 输出产生即落盘、窗口超 80% 才淘汰最旧结果、满窗换空窗；原文留在 session JSONL，search_session 随时取回，交接写 <session>.notes.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/10/15] v1.4.17：输出上限按用户配置 > 模型目录 > 网关默认；网关空回复会重发，写不完的回答标成未完成；内置 analyze_image。公开 from agentica import … 不变，子模块按领域收进子包；worktree 不再搬家上锁。详见 Release-v1.4.17
• [2026/09/15] v1.4.16：Layer 2 compact 改为空窗换窗（不再 LLM 摘要），旧对话用 search_session 查；交互 CLI 可选 attach / 外部 hooks（默认关）；MCP 只支持 2.x。详见 Release-v1.4.16
• [2026/09/01] v1.4.15：新增 TypeScript 客户端 @agentica-ai/sdk 与 Gateway Docker 镜像；/export 默认出 session JSONL；apply_patch 只精确匹配；CLI 不再把工具输出里的 [/path] 当成 Rich 标记。详见 Release-v1.4.15

• [2026/08/25] v1.4.14：权限档更新（ask 不再藏写工具，增加「拒绝类似」）；Web/桌面真正多账号；文件工具收成 apply_patch + write_file（read_file 支持 tail）；Worktree 默认进仓库内；系统 skill 包内加载；桌面版首次打开自动装 Python runtime。详见 Release-v1.4.14
• [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 的自进化与 skill 准入，请引用：

Shang, L., Xu, M., Sun, Y., Xia, T., Hu, L., Xu, L., & Zheng, N. (2026). When Self-Evolution Backfires: Pre-Commit Gating against Skill Contamination in LLM Agents. arXiv:2608.05810. https://arxiv.org/abs/2608.05810

BibTeX：

@misc{shang2026selfevolution,
  title         = {When Self-Evolution Backfires: Pre-Commit Gating against Skill Contamination in LLM Agents},
  author        = {Shang, Linfang and Xu, Ming and Sun, Yiding and Xia, Tianle and Hu, Lingxiang and Xu, Lan and Zheng, Ning},
  year          = {2026},
  eprint        = {2608.05810},
  archivePrefix = {arXiv},
  primaryClass  = {cs.AI},
  url           = {https://arxiv.org/abs/2608.05810}
}

软件本身：

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

@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。

致谢

• phidatahq/phidata
• openai/openai-agents-python