跳到主要内容

AgenticSeek — 架构与原理

30 秒导读： AgenticSeek 是一个 全本地运行的“多专家 AI 助手”（定位为 Manus 的本地替代品）。你用终端/网页说一句话，它先用两个小型 ML 分类器判断“该谁接活、多难”，再交给会写代码 / 查文件 / 爬网 / 做规划的专家 agent。难事交给 规划 agent 拆成多步计划，再调度其他 agent 依次完成。

1. 这是什么（零基础也能懂）​

一句话定义： AgenticSeek 是一个跑在你自己机器上的 AI 助手，能自主上网、写并运行代码、操作本地文件、把大任务拆成多步去做。

解决什么问题 / 给谁用：

市面上像 Manus / OpenAI Operator 这类“能自己干活的 AI agent”都跑在云上——你的文件、对话、搜索都会上传。AgenticSeek 的卖点是 隐私：配合本地 LLM（如 Ollama / LM Studio 跑的 DeepSeek、Qwen），可以零云端依赖。适合：有一台能跑本地模型的机器、不想把数据交给云的开发者/极客。

它能做什么：

  • 自主浏览网页：搜索、读页、提信息、填表单（用本地 SearxNG + Selenium）。
  • 写、调试、运行代码：Python / Bash / C / Go / Java。
  • 找文件、读文件、操作本地文件。
  • 自动选 agent：你只管说话，它自己判断该用哪个专家。
  • 拆解复杂任务：“规划 agent”把大任务分成多步，多个 agent 接力完成。
  • （进行中）语音交互：TTS / STT。

用起来什么样： 你在终端里打一句话：

➤➤➤ Make a snake game in python

它会：路由到 coder agent → 生成 Python 代码 → 自动跑一遍 → 报错就自修重试 → 成功才告诉你。

换一句复杂点的：

➤➤➤ Search the web for top cafes in Rennes, France, and save a list of three with addresses in rennes_cafes.txt

这句会被判为 HIGH 复杂度 → 路由到 planner agent → 拆成“Web 搜索 → File 写入”两步，依次执行。

一句话直觉/类比： 把它想成一个“前台接待 + 一拨专家”的公司。路由器是前台（听你说话、招呼到对的人），规划 agent 是项目经理（拆任务、派活、盯进度），其他 agent 是干活的专家。

2. 顶层全景（它大概怎么转）​

主要部件​

部件干什么在哪个文件
入口 (CLI / API)读配置、创建所有 agent、启动交互循环cli.py、api.py
Interaction读用户输入（键盘/语音）、调路由、调 agent、显示回复sources/interaction.py
AgentRouter用两个 ML 分类器决定“哪个 agent + 多难”sources/router.py
各专家 Agent实际干活：casual / coder / file / browser / planner / mcpsources/agents/*.py
各 Toolsagent 的“手脚”：代码解释器、文件查找、web 搜索…sources/tools/*.py
BrowserSelenium 驱动的真实浏览器（导航/取文/填表）sources/browser.py
Provider多后端 LLM dispatch（ollama/openai/anthropic/…）sources/llm_provider.py
Memory会话记忆 + 可选压缩sources/memory.py

一张顶层图（控制流）​

怎么读：从上到下是一次请求的生命周期；HIGH 复杂度是“复杂任务”才走的旁路。

  用户一句话
      |
      v
  (1) Interaction.get_user()        读输入（键盘或语音转写）
      |                              interaction.py
      v
  (2) AgentRouter.select_agent()    检语种->翻译成英文->估复杂度->选 agent
      |                              router.py
      |--复杂度 HIGH-----------+
      |                        v
      |                   (8) PlannerAgent     拆成 JSON 计划，依次调子 agent
      |                        |             planner_agent.py
      v<-----------------------+
  (3) 选中的 Agent.process()         ReAct 循环：问 LLM->抽代码块->执行->反馈
      |                              agents/*.py
      v
  (4) execute_modules()             每个工具扫 answer 里的代码块并执行
      |                              agents/agent.py
      v
  (5) Tools.execute()               真跑代码 / 搜索 / 浏览器动作
      |                              tools/*.py
      v
  (6) 结果回填 memory -> 成功则结束，失败则重试
      |
      v
  Interaction.show_answer() / speak_answer()

主线走一遍（高层）​

以 CLI 为例（cli.py:64-68），主循环只有四步：get_user() 读输入 → await think() 路由+处理 → show_answer() 显示 → speak_answer() 朗读。

真正的“选谁干活”发生在 Interaction.think()（interaction.py:276-296）：它调 router.select_agent(query) 拿到 agent，再 await agent.process(query, speech)。一个细节：如果这次的 agent 跟上次不同，会把上轮问答推进新 agent 的记忆（interaction.py:284-293），让跨 agent 也有连贯上下文。

3. 核心设计（一句话版，详见各章）​

AgenticSeek 有几个不显而易见、值得学的设计：

  • 路由不靠 LLM，靠两个小分类器投票。 为什么？本地小模型让它“自己选 agent”不靠谱；用 BART zero-shot + 自适应分类器投票，快、独立、可控。详见 01-routing.md。
  • 工具调用不靠 function-calling，靠 Markdown 代码块。 LLM 写一段带 tag 的代码围栏，对应工具自己去 answer 里扫同名 tag 的块来执行。详见 02-agents-and-tools.md。
  • 复杂任务“分而治之”。 planner 让 LLM 输出一份 JSON 计划（每步指定 agent + 依赖），逐步执行并根据成败重规划。详见 03-planner.md。
  • 自主浏览是“页面转 Markdown 喂给 LLM”的循环。 Selenium 隐身驱动抓页 → markdownify 转成精简文本 → LLM 决定“记笔记/跳链接/填表/退出”。详见 04-browser.md。
  • 一套 provider 调度接十多种 LLM 后端。 同一个 respond() 接口，背后是 ollama / openai / anthropic / lm-studio … 详见 05-llm-and-memory.md。

4. 阅读地图（建议顺序）​

  1. 01-routing.md — 先看“一句话怎么变成选哪个 agent”，这是项目名里“Seek”的智能点。
  2. 02-agents-and-tools.md — 再看 agent 与工具的通用骨架（代码块协议 + 执行循环），这是所有 agent 的公共机制。
  3. 03-planner.md — 看多-agent 编排是怎么做的。
  4. 04-browser.md — 深入最工程化的子系统：自主浏览。
  5. 05-llm-and-memory.md — 多后端接入与记忆。

5. 边界与局限（诚实）​

  • 代码执行几乎无沙箱。 Python 用裸 exec()（tools/PyInterpreter.py:41），Bash 用 subprocess + shell=True（tools/BashInterpreter.py:52-58）。有一个“危险命令黑名单”（tools/safety.py），但 只在 safe_mode=True 时生效，而 safe_mode 默认 False 且代码里从未被设为 True（tools/tools.py:44）。官方设计上靠 Docker 隔离，但本体不拦。
  • MCP agent 尚未可用。 源码明确标注 “work in progress, not functional yet”（agents/mcp_agent.py:9），且在 cli.py:52-54 被注释掉。
  • 路由依赖预设 few-shot 例子。 复杂度/任务分类的准确度绑在 router.py 里手写的各一百余条例子上（任务≈144、复杂度≈122）；超出分布的请求可能误路由。
  • 记忆压缩是实验性的。 get_ideal_ctx 靠从模型名里抽“7b/14b”数字估算上下文（memory.py:46-67），模型名不含数字时直接不压缩。

6. 横向对比（同 shelf 兄弟）​

维度AgenticSeek典型其他 autonomous agent
路由专门的 ML 分类器投票（BART + adaptive classifier）多数用 LLM 自身决策选工具/子 agent
工具调用Markdown 代码块（带 tag 的围栏）多数用 OpenAI function-calling / JSON tool schema
部署目标本地优先、隐私优先多数云端 API 优先
多语言内置 Helsinki-NLP 翻译模型，路由前先翻成英文少见

“用小分类器而非 LLM 做路由”是 AgenticSeek 最鲜明的取舍：用确定性、廉价、可控的判别器，避开让弱小的本地模型去做元推理。

7. 代码地图（导航索引）​

主题文件符号
入口 + 主循环cli.pymain
交互编排sources/interaction.pyInteraction.think、Interaction.get_user
路由sources/router.pyAgentRouter.select_agent、router_vote、estimate_complexity
agent 基类 + 执行sources/agents/agent.pyAgent.execute_modules、Agent.sync_llm_request
工具基类 + block 解析sources/tools/tools.pyTools.load_exec_block
规划sources/agents/planner_agent.pyPlannerAgent.make_plan、update_plan、process
浏览器 agentsources/agents/browser_agent.pyBrowserAgent.process、make_navigation_prompt
浏览器驱动sources/browser.pyBrowser.go_to、get_text、fill_form
LLM 后端sources/llm_provider.pyProvider.respond、Provider.ollama_fn
记忆sources/memory.pyMemory.push、Memory.compress