Agt — AI Agent 框架
自己开发自己的 AI Agent 框架。
An agent framework that builds itself. —— 本仓库的绝大多数迭代由 Agt 自身完成（dogfooding：用它开发它）。 A quine that evolves：输出不是自己的副本，而是下一个版本的自己。
多模型 ReAct 引擎 + MCP 工具 + Coze 工作流 + WebUI + 可视化编辑器。不依赖 LangChain / LlamaIndex / AutoGen，每个模块手写。
pip install agt-agent
agt # CLI 对话
agt-web # WebUI → http://localhost:8000
架构总览
┌────────────────────────── 交付层 ──────────────────────────┐
│ CLI (agt) │ WebUI (agt-web) │ 桌面 │ Android │
├────────────────────────── 应用层 ──────────────────────────┤
│ 会话与上下文引擎 工作流引擎 自主模式/定时 │
│ ·三级记忆·分档投影 ·13 类节点 ·消息队列 │
│ ·97%+ 前缀缓存 ·可视化编辑器 ·目标驱动 │
│ ·/branch /merge 分支 │
├────────────────────────── 协作层 ──────────────────────────┤
│ 多 Agent（声明式子代理/防递归） 远程组网（remote_*） │
│ event-sourcing 全事件回放 human-in-the-loop 审批 │
├────────────────────────── 工具层 ──────────────────────────┤
│ MCP Client/Server │ 沙箱执行 │ 技能包(.agent/skills) │
│ wiki 知识库 │ Agentic RAG │ 批处理 │ 随包资产 │
├────────────────────────── 模型层 ──────────────────────────┤
│ 多模型网关：10+ Provider · 自动路由 · 回退链 · Token 核算 │
└────────────────────────────────────────────────────────────┘
零重依赖（仅 PyYAML + websocket-client）· MIT 开源
每一层都可独立替换/扩展——详见 ROADMAP.md。
功能
| 模块 | 说明 |
|---|---|
| ReAct 引擎 | 思考 → 工具调用 → 观察 → 循环，最大步数 + Token 预算 + Ctrl+C 中断 |
| 多模型 | DeepSeek / Qwen / GLM / MiniMax / StepFun / 任意 OpenAI 兼容，热切换 + 回退链 |
| MCP | Model Context Protocol 客户端，自动发现工具 |
| 工作流 | Coze 原生画布 JSON 执行器，13 类节点，每轮扫描注册为 Agent 工具 |
| 可视化编辑器 | SVG 画布 + 节点拖拽 + 流程线/变量线(彩色) + 属性面板，零依赖 |
| 多 Agent | SubAgent 并行调度，工具继承，防递归 |
| WebUI | FastAPI + WebSocket，多客户端广播，断线续连 |
| 会话 | 分档上下文投影（毕业压缩 + 折叠召回）+ 全局摘要 + recall 召回 + 存档/恢复 |
| 自主模式 | 定时/目标驱动，消息队列 |
| Wiki | .agent/wiki/ 知识库 CRUD + 子 Agent 自动维护 |
| 技能 | .agent/skills/ YAML 渐进式披露 |
| Agentic RAG | 工作流设 auto:true，消息自动预取注入 |
| 批处理 | 任意节点对数组逐元素执行，输出 all/filtered/nth |
| 随包资产 | /download 按需取用内置工作流 / MCP / 脚本 |
| 反馈通道 | /feedback 一键提交（本地存档） + GitHub Issues |
快速开始
1. 安装
pip install agt-agent
2. 配置模型
启动后点 ⚙ 设置 → 添加模型（base_url / api_token / model id），保存到 ~/.agt/models.json。
内置 Provider 目录（模型下拉框开箱可选——点选即弹引导：申请页直达 + key 粘贴，落地自动写配置）：
| Provider | 为什么选它 | |
|---|---|---|
| 🎁 | ModelScope | 开源模型每日免费额度，零成本起步首选 |
| ⚡ | Z.ai（智谱） | GLM 官方直连、国内低延迟，新户送额度 |
| 🐋 | DeepSeek 官方 | V4 官方 API：价格厚道，缓存命中折扣极深 |
| 🌊 | 硅基流动 | 一把 key 用遍各家开源模型，注册即送额度 |
| 🧭 | OrcaRouter | 一把 key 零加价路由 11 家前沿模型（含免费池） |
| 🔀 | OpenRouter | 全球最大聚合网关：一把 key 400+ 前沿模型 |
或手动：复制 models.example.py → models.py，填 token。
3. 启动
agt # CLI
agt-web # WebUI（浏览器打开 http://localhost:8000）
4. 多实例统一看板（dashboard）
agt-web --dashboard # http://localhost:9100（端口可跟在后面：agt-web --dashboard 9100）
一张页面管多台 agt 实例（本机多端口 / 局域网 / cpolar 公网隧道）：
- 状态总览：🟢空闲 / 🟡忙碌 / 🔴离线，model·session·轮数、recap（最近在干嘛）
- 本地实例启停：dashboard 直接拉起（detached Popen）/ 停止（杀进程树，含 MCP 子进程）
- 发现一键导入：netstat 扫本机 LISTEN →
/api/status含 session_name 判定 agt，勾选导入 - 拉网线：卡片间连线 = 对 A 调
/api/remote/add（复用组网端点，零改动）；拓扑显示在卡片 chips - 互动群聊流：旁听各实例 WS 事件，采集
remote_*/notify调用（发送方视角），飞书式时间线 - 远程实例：kind 选「远程」填 url（局域网地址或
https://xxx.cpolar.top/port-N）；开了 callback_token 的实例在条目里填 token，dashboard 探测/拉线自动带X-Cb-Token
纯管理面：不装配 Agent、不占 session、不消耗 LLM，崩了不影响被管实例。数据文件：
~/.agt/dashboard.json（实例注册表）、~/.agt/dashboard_interactions.jsonl（互动流追加日志，
重启不丢）。旧版实例无互动历史回填端点（GET /api/interactions）时自动降级——只从 dashboard
启动起积累。
端到端冒烟（隔离 AGT_HOME 起 2 实例 + dashboard → 发现导入 → 拉线 → 真发跨实例消息 →
验证互动流 → 启停 → 清理）见 smoke/smoke_launch.py / smoke_drive.py（python smoke/smoke_launch.py
&& python smoke/smoke_drive.py，清理 python smoke/smoke_cleanup.py）。
Agent 上手指引（新环境探索）
本节写给 Agent 自己——当 agt 实例被部署到新环境（云容器 / 新机器 / 新 repo）时，首轮对话建议按此探索，快速建立对所处环境的认知：
- 进程与环境：
/status（工具箱规模 / MCP 连接 / 后台服务 / 子进程树）与/context（模型与上下文配置） - 任务指引：
read_file("AGENTS.md")——用户为当前 workspace 定制行为的入口（不存在则跳过） - workspace 结构：
list_dir+ README / 核心配置文件——先摸清这个 repo 是什么、用什么语言、怎么构建 - 能力面：
.agent/三件套——agents/（子 Agent 声明）、workflows/（工作流）、skills/（技能 SOP） - 模型配置：
~/.agt/models.json——本机可用 provider 与默认模型；/config查看运行时设置 - 多实例组网：
remote_connect(url)连接其它机器上的 agt 实例（server_id 可省略自动生成）→ 之后任意工具调用 arguments 里带"server_id"即路由到远程执行（工具级直执行，不消耗远程 LLM token） - 框架参考：需要理解 / 修改 agt-agent 自身时，本仓库（GitHub: vgp7758/Agt）的
docs/与.agent/wiki/（部署后）是权威资料
上下文管理
长对话不爆上下文、细节也不丢（session.py）：
- 分档投影：给模型设
max_effective_context_window（token 估算的软上限），超出即「毕业」——老轮按档位递进压缩（每档摘要上限减半），近期轮保持全量。冻结渲染 byte-stable，利于前缀缓存命中。 - 折叠召回：压到头仍超窗口，最老的整档退化为摘要，逐字原文用
/recall召回。 - 默认（不设该字段）：走原策略——最近窗口全量 + 窗口外一句话摘要。
| 参数 | 作用 | 在哪设 |
|---|---|---|
max_effective_context_window |
每模型：何时开始压缩（空=关闭分档） | 模型编辑器 / /config max_effective_context_window N |
max_level |
全局：最高压缩档位（默认 4） | 设置表单 / /config max_level N |
该值按成本/延迟耐受度定，不是模型的硬上下文上限。无缓存折扣的 route（如 ModelScope）建议 3.2 万~6.4 万；有缓存折扣的（Z.ai 直连 / DeepSeek）可更大。
工作流
- 打开
http://localhost:8000/editor（或 WebUI 点 ✏ 编辑器） - 左侧调色板拖放节点 → 连线 → 右侧面板编辑属性 → Ctrl+S 保存
- 文件存入
.agent/workflows/<名>.json - Agent 每轮自动扫描 → 注册为
wf_<名>工具，模型可调用
自动工作流（Agentic RAG）：编辑器勾选 ✅ 自动 + 填写参数名，保存后 meta 写入 {"auto":true,"auto_param":"query"}。之后每次发消息，Agent 先跑该工作流取上下文再处理。
节点类型（13 类 + 外置插件）
内置核心（13 类）：开始/结束 · LLM · 代码 · 选择器(分支) · 循环 · 批处理 · 意图识别 · JSON 解析/构造 · 文本处理 · HTTP 请求 · 子工作流 · 插件 · 变量聚合/赋值
外置插件（扩展面）：节点类型可从内置代码外置为「同目录同名 .py + .js 配对」脚本——写两个文件即得全新节点类型，零框架改动。目录约定（三级，同名 type 后扫覆盖先扫）：
| 目录 | 用途 |
|---|---|
src/assets/nodes_builtin/ |
随包核心插件（pip 安装即有：text/tojson/fromjson） |
nodes/ |
workspace 级 |
.agent/nodes/ |
用户/Agent 私有（扩展面：timestamp 验收节点） |
后端 .py 用 workflow_node_api SDK（稳定依赖面），前端 .js 用 EdFW 组件（ioTable/textArea/propShell）。/reload nodes 热加载后端 handler，前端改 .js 需 Ctrl+F5。详见 .agent/wiki/architecture/node-plugins.md。
项目结构
├── pyproject.toml # pip install 配置（entry: agt, agt-web）
├── src/ # 源代码
│ ├── chat.py # CLI(REPL) + 装配层 + agt-web 入口(web_main)
│ ├── server.py # Web 视图（FastAPI/WS，由 chat 内嵌，/web 启停）
│ ├── agent.py # ReAct 引擎
│ ├── workflow.py # Coze 工作流执行器
│ ├── tools.py # Tool/Toolbox
│ ├── real_tools.py # 内置工具（Python/文件读写/grep/搜索/shell）
│ ├── llm_client.py # 多模型客户端
│ ├── session.py # 分层上下文会话
│ ├── mcp_client.py # MCP 协议
│ ├── multiagent.py # 多 Agent
│ └── ...
├── src/static/ # WebUI 前端
│ ├── index.html # 聊天界面
│ └── workflow_editor.html # 工作流编辑器
├── .agent/ # 工作区（workflows/rules/skills/wiki）
└── examples/ # step0-7 教程
开发
git clone https://github.com/vgp7758/Agt.git
cd Agt
pip install -e .
运行测试：python examples/step*.py
反馈与联系
用着顺手、遇到 bug、或有想法，都欢迎反馈：
- GitHub Issues（推荐，公开可追踪）：提一个 Issue
- WebUI：顶栏「💬 反馈」按钮 → 类型 / 内容 / 联系方式 → 提交（存档
~/.agt/feedback/） - CLI：
/feedback [类型] <内容>
联系作者：微信 mrbrick123 · 邮箱 vgp123@foxmail.com · GitHub @vgp7758 · Issues
随包资产
内置工作流 / MCP / 脚本可按需取用到本地工作区：
/download # 列出随包资产
/download <名> # 下载某项到默认目录
卸载
pip uninstall agt-agent
rm -rf ~/.agt
License
MIT
路线图
见 ROADMAP.md：稳内核（v1.0）→ 组网产品化 → 云与生态。
1 maintainer
Metadata
1 maintainer
Release files for agt-agent 0.35.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agt_agent-0.35.3.tar.gz | 2.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agt_agent-0.35.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.4 MB
Release files / agt_agent-0.35.3.tar.gz
| Download URL | agt_agent-0.35.3.tar.gz |
|---|---|
| Size | 2.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
884546cb7063afb71a47b5253a161fa857dc32a33e0dcd90bba730615bebe90c
|
|
BLAKE2b-256 checksum How to use checksums |
c6a935f2380bdf544a54ef895ce669875a3c857a74d94df7c71d3c1da23bb43e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.6
|
Release files / agt_agent-0.35.3-py3-none-any.whl
| Download URL | agt_agent-0.35.3-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f8d31941da5b99fcc6af0081a019ec038cc04814f56347ebfdc0170da0f73ee5
|
|
BLAKE2b-256 checksum How to use checksums |
db68020f13598b04052bfcc3ff2d27083dbc6a78e823173a14728a9e018aee34
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.6
|
