Agentica

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

⬇️ Download Desktop App

macOS · Windows · Linux

简体中文 | English

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

为什么选 Agentica

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

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

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

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

一个终端就是一个 agent。查资料、读代码可以让它拉起只读的子任务（task）；独立的大功能可以派给后台新进程（delegate）；开了多个终端还能直接互通消息（/list-agents、/send-message）——不需要额外部署任何服务。

3. 🧬 越用越懂你的项目

踩过的坑和总结出的做法会自动沉淀为可复用的 SKILL.md；你的长期偏好写在 AGENTS.md，项目事实存进长期记忆。下次做同类任务直接接着上回的结论走，不用每次重头交代背景。详见 Skills 文档。

4. 🧠 长对话不失忆，也不怕超窗口

普通工具动辄把上万行日志塞进上下文，聊几轮就报错或把你最早的要求忘掉。Agentica 自动替你管好上下文：

• 超大输出自动存文件 — 命令或工具输出太长时自动落盘，上下文里只留预览和文件路径，需要细节时 Agent 自己读回
• 窗口快满时先清旧工具输出 — 优先清掉早期的工具结果，保留你的对话和当前正在执行的步骤
• 满窗自动换新窗并交接进度 — 自动把当前目标、约束和未完事项写进 .notes.md 带入新窗口；完整历史始终留在本地会话日志里，Agent 随时用 search_session 查回原文，你也可以随时敲 /compact 手动换窗或 /resume 恢复会话

5. 📱 人离开电脑也能接着指挥

微信 / 企微 / 飞书 / Telegram 直连本机：发 @list 看电脑上哪些终端会话还在跑，发 @会话名 指令 直接把话敲进那个终端，或者直接用自然语言让网关替你安排。

安装

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 tool install 装过的会直接共用。

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

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()

功能特性

核心能力

• 开箱即用的内置工具 — 读写文件（read_file / write_file / apply_patch）、搜索代码（grep / glob）、执行命令（execute）、联网搜索与抓取（web_search / fetch_url）、看图（analyze_image）
• 多模型自由切换 — 支持 OpenAI（Chat Completions / Responses API）、DeepSeek、Claude、智谱、通义千问、Kimi、豆包、Ollama 等，会话中随时 /model 切换
• 多模态与安全护栏 — 支持文本、图像、音频、视频理解；提供输入、输出、工具调用四层 Guardrails 与系统沙箱（--sandbox workspace-write）
• 原生异步 SDK — async / sync 双接口，只读工具自动并发执行

• CLI 终端 — agentica 交互编程助手，支持 /goal 持续推进长任务、/resume 跨目录恢复会话、/worktree 多任务隔离
• Web 与桌面端 — agentica-gateway 提供本地网页与桌面 App（聊天 / 执行轨迹 / 设置 / 多账号隔离），并可接入微信、飞书、企微、Telegram、QQ、钉钉、Slack

• 多智能体编排 — CLI 内置 task（子任务）、delegate（后台独立进程）、peer（跨终端通信）；Python SDK 提供 Agent.as_tool()、Workflow、Swarm、自定义 Subagent
• 长期记忆与自进化 — 自动记住用户偏好与项目背景（MEMORY.md + AGENTS.md 常驻规则），任务经验可沉淀为 SKILL.md 跨会话复用
• 长会话上下文管理 — 大输出自动落盘、旧工具结果按需清理、满窗自动换新窗并交接笔记，历史原文随时通过 search_session 查回
• MCP / ACP / RAG — 支持接入外部 MCP 工具、连接 Zed / JetBrains 等 IDE（ACP 协议），以及本地文档知识库检索（RAG）

多会话协作：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/22] v1.5.0：Langfuse 5 每次用户请求一条 Trace，模型调用与工具执行是子 Observation，Hook 不上报。历史默认重放整个窗口（num_history_turns 默认 None，不再截断旧 tool 结果）。换模型保留工具历史，一轮内跨 provider fallback 能带着本轮工具结果完成。长会话按 provider 实测 token 校准压缩。详见 Release-v1.5.0
• [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

文档

完整使用文档：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