agt-agent

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。

---

功能

---

快速开始

1. 安装

pip install agt-agent

2. 配置模型

启动后点 ⚙ 设置 → 添加模型（base_url / api_token / model id），保存到 ~/.agt/models.json。

内置 Provider 目录（模型下拉框开箱可选——点选即弹引导：申请页直达 + key 粘贴，落地自动写配置）：

或手动：复制 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）时，首轮对话建议按此探索，快速建立对所处环境的认知：

1. 进程与环境：/status（工具箱规模 / MCP 连接 / 后台服务 / 子进程树）与 /context（模型与上下文配置）
2. 任务指引：read_file("AGENTS.md")——用户为当前 workspace 定制行为的入口（不存在则跳过）
3. workspace 结构：list_dir + README / 核心配置文件——先摸清这个 repo 是什么、用什么语言、怎么构建
4. 能力面：.agent/ 三件套——agents/（子 Agent 声明）、workflows/（工作流）、skills/（技能 SOP）
5. 模型配置：~/.agt/models.json——本机可用 provider 与默认模型；/config 查看运行时设置
6. 多实例组网：remote_connect(url) 连接其它机器上的 agt 实例（server_id 可省略自动生成）→ 之后任意工具调用 arguments 里带 "server_id" 即路由到远程执行（工具级直执行，不消耗远程 LLM token）
7. 框架参考：需要理解 / 修改 agt-agent 自身时，本仓库（GitHub: vgp7758/Agt）的 docs/ 与 .agent/wiki/（部署后）是权威资料

上下文管理

长对话不爆上下文、细节也不丢（session.py）：

• 分档投影：给模型设 max_effective_context_window（token 估算的软上限），超出即「毕业」——老轮按档位递进压缩（每档摘要上限减半），近期轮保持全量。冻结渲染 byte-stable，利于前缀缓存命中。
• 折叠召回：压到头仍超窗口，最老的整档退化为摘要，逐字原文用 /recall 召回。
• 默认（不设该字段）：走原策略——最近窗口全量 + 窗口外一句话摘要。

该值按成本/延迟耐受度定，不是模型的硬上下文上限。无缓存折扣的 route（如 ModelScope）建议 3.2 万~6.4 万；有缓存折扣的（Z.ai 直连 / DeepSeek）可更大。

---

工作流

1. 打开 http://localhost:8000/editor（或 WebUI 点 ✏ 编辑器）
2. 左侧调色板拖放节点 → 连线 → 右侧面板编辑属性 → Ctrl+S 保存
3. 文件存入 .agent/workflows/<名>.json
4. Agent 每轮自动扫描 → 注册为 wf_<名> 工具，模型可调用

自动工作流（Agentic RAG）：编辑器勾选 ✅ 自动 + 填写参数名，保存后 meta 写入 {"auto":true,"auto_param":"query"}。之后每次发消息，Agent 先跑该工作流取上下文再处理。

节点类型（13 类 + 外置插件）

内置核心（13 类）：开始/结束 · LLM · 代码 · 选择器(分支) · 循环 · 批处理 · 意图识别 · JSON 解析/构造 · 文本处理 · HTTP 请求 · 子工作流 · 插件 · 变量聚合/赋值

外置插件（扩展面）：节点类型可从内置代码外置为「同目录同名 .py + .js 配对」脚本——写两个文件即得全新节点类型，零框架改动。目录约定（三级，同名 type 后扫覆盖先扫）：

后端 .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）→ 组网产品化 → 云与生态。