Skip to main content

Agentica Logo

Agentica

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

⬇️ Download Desktop App

macOS · Windows · Linux

PyPI version GitHub stars License Apache 2.0 Python 3.10+ Wechat Group

简体中文 | English

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

为什么选 Agentica

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

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

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

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

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

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

3. 🧬 越用越懂你的项目

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

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

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

  • 超大输出自动存文件 — 命令或工具输出太长时自动落盘,上下文里只留预览和文件路径,需要细节时 Agent 自己读回
  • 窗口快满时先清旧工具输出 — 优先清掉早期的工具结果,保留你的对话和当前正在执行的步骤
  • 满窗自动换新窗并交接进度 — 自动把当前目标、约束和未完事项写进 <session>.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 . -e ./gateway(Web 后端已是独立发行包 agentica-gateway,agentica[gateway] 会把它一起装上)。详见 安装文档。

桌面版

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

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

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

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

  2. 打开「终端」,粘贴这条命令回车(要输开机密码,输入时不显示字符):

    sudo xattr -rd com.apple.quarantine /Applications/Agentica.app
    
🪟 Windows 提示「Windows 已保护你的电脑」

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

🐧 Linux 双击 AppImage 没反应

浏览器下载的 AppImage 默认没有执行权限(deb 走包管理器,没这个问题):

chmod +x Agentica-x86_64.AppImage

也可以直接从源码跑:cd desktop && npm install && npm start(Node 22 及以上),详见 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

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

Agentica CLI 截图

Web

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

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

Agentica Web UI 截图

自托管(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/11/04] v1.5.1:Web 后端拆成独立包 agentica-gateway(与 agentica 同版本发布,uv tool install "agentica[gateway]" 不用改)。Web 构建产物改为 web/dist,打进 gateway wheel。一个 v* tag 同时发 PyPI(两个包)、npm(@agentica-ai/sdk)、Desktop 安装包和 GitHub Release。详见 Release-v1.5.1
  • [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
更多版本
  • [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。

致谢

Metadata

Release files for agentica 1.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentica 1.5.1
File Size Uploaded Provenance Actions
agentica-1.5.1.tar.gz 2.9 MB Without provenance Details for agentica-1.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentica 1.5.1
File Interpreter ABI Platform Actions
agentica-1.5.1-py3-none-any.whl Python 3 none any Details for agentica-1.5.1-py3-none-any.whl

Total release size: 6.1 MB

Release files / agentica-1.5.1.tar.gz

Download URL agentica-1.5.1.tar.gz
Size 2.9 MB
Tags Source
SHA-256 checksum
How to use checksums
f394c2482986995e3734b8f7247f9f39745c744612bdae57203926254f3291e1
BLAKE2b-256 checksum
How to use checksums
da0e0b22218a69aa4c74951c568e5dcdca91a3f609690205b30dea83285194f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.12

Release files / agentica-1.5.1-py3-none-any.whl

Download URL agentica-1.5.1-py3-none-any.whl
Size 3.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
52610930bfb9adb44b9cd3b1ea7667aeb3b66c0dab3557b49102f8c3478e9c40
BLAKE2b-256 checksum
How to use checksums
24c929955162777c9e5d1d44b16d389ed688aa068e99b3967c7dd9974c81598f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.12

Security for agentica 1.5.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.5.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page