🇨🇳中文 | 🌐English | 🇯🇵日本語

---

Agentica

一个人，一支 agent 团队。

终端里起多个会话并行干活、互相通信；长任务跑着的时候人走开了，也能从微信/企微把它喊回来。

Agentica 是给开发者使用的本机 Agent CLI + Python SDK：把一个终端会话变成一个可协作的 agent，把多个会话组成一支可并行推进任务的队伍。

安装

pip install -U agentica

配置

三选一，配上任一模型厂商的 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

进入交互终端后直接说话即可，例如「帮我看下这个仓库的单测为什么挂了」。长任务用 /goal，多会话协作用 delegate / peer 消息，详见下文 CLI 一节。

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，流式实时检测
• 多模态 — 文本、图像、音频、视频理解

长任务与协作

• /goal 长任务循环 — await agent.run_goal("xxx") 持续推进，自动判断完成、续跑、暂停；支持 token / wall-clock / turn 三种 hard cap；CLI /goal /subgoal 即开即用，详见 文档
• 多智能体 — SDK：Agent.as_tool()、Workflow、Swarm、Markdown Subagent；CLI：进程内 task、进程级 delegate、跨终端 peer 消息（见 终端文档）
• Actor-Critic 精炼 — refine() + 多 Critic 并行评审，SchemaCritic 程序级零成本验证 / AgentCritic 异构强模型把关，循环检测自动早停

记忆与进化

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

集成

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

架构

Agentica 提供从底层模型路由到顶层多智能体协作的完整抽象：

核心执行引擎 (Agentic Loop)

Agentica 的单体 Agent 运行在一个纯粹的基于控制流的 while(true) 引擎中，严格依据工具调用来驱动，并内置防死循环、成本追踪、两层上下文压缩（免费淘汰 → LLM 摘要）和四层安全护栏：

CLI

agentica

长任务：/goal

让 Agent 持续向一个目标推进，每轮结束自动判断是否完成，没完成就续跑——直到 judge 判 done、预算耗尽、或用户主动停下。

CLI：

/goal 实现 xxx 功能并跑通 pytest    # 设置目标 + 自动开跑
/goal status                       # 显示状态、预算、subgoals
/goal pause | resume | clear
/subgoal 必须补单测                  # 给目标加验收条件

完整说明：Standing Goal Loop 文档。

协作：task / delegate / peer

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

Web UI / IM 集成

pip install -U "agentica[gateway]"

启动：

agentica-gateway

Web 网页会启动在 http://127.0.0.1:8881/chat。

除 Web 网页外，还支持手机端 IM 接入 QQ / 飞书 / 微信 / 企微 / Telegram / Discord / Slack 等，内置定时任务调度。

IM 接入详细参考（扫码绑定、渠道配置、环境变量）：Gateway 文档。

示例

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

→ 查看完整示例目录

和其它 Agent CLI 对比

🔥 News

• [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

文档

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

致谢

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