读 Octop 源码(5):一个数据库行,怎么变成一个活着的 Agent

文章目录

上一篇只摊了地图,这篇开始钻。按重要性,第一个要读的是 infra/agents/manager.py——4187 行,是整个后端最大的单个文件。

我原以为它会很复杂,读完发现职责其实很清楚,就四件事:启动、注册、执行、回收。复杂的是每一件事背后的并发问题。

版本锚点:本文基于 octop v1.0.2(commit dd9dce4),octop-harness 1.0.4、deepagents 0.7.28、langgraph 1.2.16。行号会变,函数名短期应该不会。

环境准备

读这个模块,光看代码不够,得能看到"活的状态"。准备三样:

第一,跑起来看真实日志。 Agent 的启动是逐条的,日志里能看出耗时:

cd ~/WorkBuddy/Claw/octop
grep -E "Agent .* started|Failed to start agent" .home/.octop/logs/octop.log | tail -10

我这台机器 4 个 Agent 的实测(本机 SQLite、空 workspace):

07:13:28,946  Agent aaaaa  started with mcp_servers=[] mcp_tool_count=0
07:13:29,014  Agent aaaaa  (通用专家) started
07:13:29,274  Agent C4XMFK started ...
07:13:29,339  Agent C4XMFK (AI 编程实战导师) started
07:13:29,527  Agent BDBNYX (aaaa) started
07:13:29,788  Agent hello  started ...
07:13:29,854  Agent hello  (小通 · 通用助手) started

从第一条到最后一条 908 毫秒,平均每个约 230 毫秒。 这个数字后面要用来推天花板。

第二,直接读状态字段。 Agent 的生死在数据库里有个 last_state,出问题第一件事是看它:

sqlite3 .home/.octop/octop.db \
  "select agent_id, name, last_state, substr(coalesce(last_error,''),1,40) from agents;"

第三,盯住那几个计数字典。 AgentManager.__init__ 里那堆 dict 和 set 就是全部的运行时状态,比读方法体更快理解它在防什么。我会在最后一节拿它们算一笔账。

流程

一、先分清三样东西

读这个类最容易混的是"Agent"这个词指了三个不同的东西:

概念类型存在哪谁负责
行AgentRow控制面数据库 agents 表agent_repo
入口AgentEntryoctop-harness 的内存注册表HarnessAgentManager
实例HarnessAgent内存,持着编译好的 LangGraph 图它自己

三者不是一一同步的。AgentManager 的 docstring 第一句就把话说死了:

Row data is always read directly from the DB — no in-process row cache — so callers always see the latest persisted state.

行永远从数据库现读,不缓存。 这个决定顺手解决了一堆问题:多进程改库、管理员直接改库、迁移脚本改库,都不需要通知内存。代价是每次读都要查库——但 SQLite 本地读几十微秒,值。

而"入口"和"实例"是常驻内存的,这才是真正要管的东西。

二、启动:全量 eager,不是懒加载

这是第一个反直觉的地方。我以为这种多租户平台会是"用户点开哪个 Agent 就加载哪个",实际是进程启动时把所有 Agent 全拉起来。

boot() 一共不到 60 行,核心就一个循环:

rows = self._repos.agent_repo.list_all(include_disabled=False)
for row in rows:
    if row.last_state == "stopped":
        continue
    try:
        await asyncio.wait_for(
            self._start_agent(row),
            timeout=_AGENT_BOOT_START_TIMEOUT,      # 60.0 秒
        )
    except TimeoutError:
        if self._octop_harness_or_none(row.agent_id) is not None:
            self._repos.agent_repo.set_state(row.agent_id, "running", error=None)
            logger.warning("Agent %s start exceeded %.0fs but is already registered", ...)
            continue
        logger.error("Agent %s start timed out after %.0fs; continuing boot", ...)
        self._repos.agent_repo.set_state(row.agent_id, "failed", error=AGENT_START_TIMEOUT)

三个细节各有来历。

为什么跳过 stopped。 用户手动停掉的 Agent,重启后不能被自动拉起——否则"停用"这个操作就失效了。所以状态必须持久化到行里,而不是只在内存里标个 flag。

为什么是 60 秒超时。 Agent 启动要初始化 workspace、编译 LangGraph 图、注入 MCP 工具、同步技能。MCP 服务器连不上时,这一步能挂很久。60 秒是"再慢就不该等"的经验值。

超时后的处理最见功力。 注意它是先查一下注册表:如果超时了但对象已经注册进去了,说明只是慢、并没失败,那就标 running 继续跑;只有确实没注册上,才标 failed。这是一句 if self._octop_harness_or_none(...) is not None 解决的,但它想清楚了一件事:超时 ≠ 失败。

代价也很明显:单进程里所有 Agent 常驻。用上面的实测数字外推——每个约 230ms,100 个 Agent 启动要 20 秒以上,500 个就接近两分钟。而且这还是空 workspace、无 MCP 的理想情况。真实的 MCP 连接、技能包同步会让单条启动慢一个量级。

所以这个设计隐含了一个容量假设:单实例管理的 Agent 数量是几十到几百,不是几千。 这也和 ADR 001 那句"只能垂直扩容"对得上。

三、一个行怎么变成 Agent:_start_agent 的七步

真正的转换发生在 _start_agent()(3190 行起)。流程本身不复杂,值得看的是它防并发的三层。

① 前置检查:shared_factory 为空 → 直接标 failed(NO_MODELS_CONFIGURED)
      没有模型工厂,编译图必然失败,不如不试
  ↓
② 拿 per-agent 生命周期锁  async with self._lifecycle_lock_for(agent_id)
  ↓
③ 幂等检查:已经在注册表里 → 标 running,直接返回现有实例
  ↓
④ 清掉 bootstrap 闩锁 self._bootstrap_known.pop(agent_id)
  ↓
⑤ 组装配置 _agent_runtime_bundle(row) → (cfg, metadata, tags, user_display)
  ↓
⑥ await self._harness_manager.acreate_agent(cfg, agent_id=..., init_workspace=...)
  ↓
⑦ _post_start_agent(...):注入 gateway 工具、清洗 MCP 工具名、同步内置技能与插件技能
  ↓
标 running / 异常则标 failed(format_agent_start_error(exc))

第 ① 步值得单独说。 shared_factory 是 harness 里的模型工厂,为空意味着一个 provider 都没配。这时候不启动 Agent、直接把行标成 failed 并写上 NO_MODELS_CONFIGURED,用户在界面上看到的是"这个 Agent 没配模型",而不是"启动中"一直转圈。把一个注定失败的操作提前短路,并且给出可解释的原因——这是个好习惯。

第 ②③ 步合起来是三层防重。 这个 Agent 被注册两次的后果是 ValueError: already exists in the registry,而这个错误在并发场景下很容易发生:进程启动时的 boot()、provider 热重载、用户点"重载"按钮,三条路都可能同时走到这里。所以他们上了三层:

# 第一层:per-agent 锁,串行化同一个 agent 的启动/重载
async with self._lifecycle_lock_for(row.agent_id):
    # 第二层:幂等检查
    existing = self._octop_harness_or_none(row.agent_id)
    if existing is not None:
        self._repos.agent_repo.set_state(row.agent_id, "running", error=None)
        return existing
    try:
        ...
    except Exception as exc:
        # 第三层:异常兜底,识别"别处已经注册成功"这种良性冲突
        recovered = self._octop_harness_or_none(row.agent_id)
        if recovered is not None and self._is_already_registered_error(exc):
            self._repos.agent_repo.set_state(row.agent_id, "running", error=None)
            return recovered
        ...

管理者自己的注释也承认了这个动机:「Serialize start/reload per agent so parallel provider reloads cannot double-register the same harness id」。

这里我要提一个批评。 第三层靠的是字符串匹配:

@staticmethod
def _is_already_registered_error(exc: BaseException) -> bool:
    return "already exists in the registry" in str(exc)

而这句消息来自 harness 里 AgentRegistry.add() 抛的 ValueError,原文是 f"Agent '{entry.agent_id}' already exists in the registry."。两个独立发布的包,用异常文案当类型标识——上游哪天改个措辞,这层防护就静默失效了。正确做法是上游抛一个专门的异常类型(比如 AgentAlreadyRegistered),下游 except 它。

考虑到 octop-harness 和 octop 是同一批人维护、同版本发布,这个耦合短期不会炸;但它属于应该记在技术债清单上的那一类。

四、创建:create() 与那个 defer_bootstrap 开关

create() 是 175 行长函数,在全局 self._lock 里干完整套事。我挑四个有意思的点。

ID 分配重试 16 次。

for _ in range(16):
    agent_id = new_short_id()
    if self._repos.agent_repo.get(agent_id) is None:
        break
else:
    raise RuntimeError("failed to allocate unique agent_id")

短 ID 碰撞概率极低,但这是幂等前缀没有唯一约束时的兜底。16 次全撞的概率可以忽略,写成 for...else 比 while True 更明确。

workspace 不能越界。 这一行是安全边界:

raise_if_backend_outside_user_root(
    self._repos.user_policy_repo,
    spec.user_id,
    config.get("backend"),
)

用户给自己的 Agent 指定存储后端时,路径必须在自己的根目录下。不做这个检查,一个用户就能把 workspace 指到别人的目录——多租户系统里这类"配置项即攻击面"的地方最容易被忽略。

创建失败要能回滚。 有三处调用 _abort_incomplete_create(),都在"行已经插入数据库、但后续步骤失败"的位置(种子模板失败、workspace 初始化失败、team 启动失败)。已落库的行必须撤销,否则会留下一个永远启动不了的僵尸 Agent。

defer_bootstrap 是给重活准备的。 默认 False(同步启动),传 True 时:

if defer_bootstrap:
    self._repos.agent_repo.set_state(agent_id, "starting")
    asyncio.create_task(
        self._complete_create_bootstrap(row),
        name=f"bootstrap-agent-{agent_id}",
    )

行先标 starting,把启动扔到后台任务,接口立刻返回。谁在用这个开关?我 grep 了一遍,全是"重"路径:

  • api/routers/experts.py:906(从专家市场安装)
  • infra/agents/experts/market_creation.py:367(市场模板创建)
  • infra/agents/experts/published_creation.py:414(发布态专家创建)
  • infra/agents/experts/default_agent.py:83(首次安装的默认 Agent)
  • cli/commands/agent.py:98(CLI 创建)

判断标准很清楚:带模板种子、带技能包的创建要延迟,纯手工创建的同步返回。 因为前者的耗时不可控(要写一堆文件、编译图),后者轻。

配套的 starting 这个中间态,解释了 __init__ 里那条注释:

# Completion latch set by the bootstrap callback. Do not cache False:
# the middleware can complete between dashboard polls.
self._bootstrap_known: dict[str, bool] = {}

不要把 False 缓存起来——因为前端在轮询状态,两次轮询之间后台可能刚好完成了。这是典型的"缓存了负结果导致状态永远不刷新"的坑,作者把结论直接写进注释了。

五、执行:三个入口,同一把锁

启动讲完,看执行。AgentManager 对外暴露三个执行方法:

方法场景是否流式
stream()Dashboard / IM 通道的主路径是
call()一次性调用(cron、子代理)否
resume_hitl()人机协同中断后恢复是

三个方法体不一样,但开头的锁完全一样:

async with (
    self._thread_execution_lock(agent_id, thread_id),
    self._track_invocation(agent_id),
):

第一把锁 _thread_execution_lock(agent_id, thread_id) 是 per-(Agent, 会话) 的。为什么要细到这个粒度?注释说得很直接:

Serialize harness execution per thread. Dashboard turns are queued by the channel debounce lock, but POST /chat/hitl/resume (and cron) drive the same checkpoint without it — two concurrent executions on one thread interleave LangGraph checkpoint writes.

翻译一下:同一个 thread 上并发跑两轮,LangGraph 的 checkpoint 会交错写入。 Dashboard 的正常对话有防抖锁兜着,但"人工审批后恢复"和"定时任务"这两条路绕过了它,直接打到同一个 checkpoint 上。如果不加锁,用户会看到历史消息出现奇怪的交错——这类 bug 极难复现和排查。

第二把锁 _track_invocation() 是引用计数,不是为了串行化,而是为了让回收机制知道"这个 Agent 现在正忙"。这个下一节展开。

顺带注意 _apply_pending_bootstrap_graph_refresh() 在前后各调了一次。因为 bootstrap 期间可能改了图配置,要在轮次边界上刷新,不能在轮次中间换——换了会让 LangGraph 的 checkpoint 和当前图对不上。

六、reclaim 根本不卸载 Agent

这是我这次读源码最大的误判。看到 schedule_store_reclaim、_reclaim_pending_loop、compact_agent_database 这一串名字,我以为是"空闲 Agent 从内存卸载,需要时再加载"的 LRU 机制。

完全不是。

看它的实现就明白:

def _compact_agent_database_sync(self, agent_id: str) -> bool:
    ...
    harness = self._octop_harness_or_none(agent_id)
    if harness is not None:
        memory = getattr(getattr(harness, "_memory_runtime", None), "memory", None)
        if memory is None:
            return True
        return compact_live_sqlite(memory)          # 压缩活着的那个
    return compact_agent_store_file(...)            # 或者压缩磁盘上的文件

它做的是 SQLite 文件的 freelist 压缩。SQLite 删数据不会缩小文件,删掉的页进 freelist 等着复用;如果一直删、又没用到那些页,文件就一直虚胖。所以删完对话之后,需要在空闲时重建一次文件(VACUUM 那类操作)。

Agent 从启动到进程退出,一直是活着的。 内存不回收,只回收磁盘空洞。

那这套机制值不值得这么复杂?值得,因为它要解决一个真实的竞争:压缩数据库的时候绝对不能有对话在跑(会锁表、会读到半截)。于是有了一个四角色的互斥协议:

角色数据结构含义
正在跑_active_invocations: dict[str, int]计数,可能 >1(并发轮次)
想跑_invocation_waiters: dict[str, int]已经来了但被挡住的
正在压_reclaim_holds: dict[str, Event]占位,压完 set 事件
正在回填_history_backfills: dict[str, Event]历史回填也不能被打断

两个关键函数,一读就懂:

async def _begin_invocation(self, agent_id: str) -> None:
    # 先登记"我要进来了",这样压缩就没法抢
    self._invocation_waiters[agent_id] = self._invocation_waiters.get(agent_id, 0) + 1
    try:
        while True:
            event = self._history_backfills.get(agent_id) or self._reclaim_holds.get(agent_id)
            if event is None:
                break
            await event.wait()
    finally:
        ...
    self._active_invocations[agent_id] = self._active_invocations.get(agent_id, 0) + 1

顺序是刻意反过来的:先登记 waiter,再等锁。 如果反过来,中间那个空隙里压缩就可能抢进来。

压缩那一侧的检查是双重的:

def _try_acquire_reclaim(self, agent_id: str) -> bool:
    if (self.is_agent_active(agent_id)
            or self._invocation_waiters.get(agent_id, 0) > 0
            or agent_id in self._reclaim_holds
            or agent_id in self._history_backfills):
        return False
    self._reclaim_holds[agent_id] = asyncio.Event()
    # 占位之后再查一遍:占位那一瞬间可能刚好有 waiter 登记进来
    if self.is_agent_active(agent_id) or self._invocation_waiters.get(agent_id, 0) > 0:
        self._release_reclaim(agent_id)
        return False
    return True

第二遍检查是标准的 TOCTOU 防护。这个函数写得比大多数教科书例子都干净。

还要注意 _invocation_waiters 的存在意义:它防的是**“压缩刚拿到锁,一堆对话在门口排队,压缩慢慢跑,大家干等”**。有 waiter 就不拿锁,让对话先走。这是很细的优先级判断。

至于触发时机,有两个:删除对话时 schedule_store_reclaim() 显式排队;以及启动时 schedule_idle_reclaim_sweep() 扫一遍——后者用 RECLAIM_MIN_FREELIST_BYTES 做阈值,只有空洞大到一定程度才值得压。

七、边界:harness 那边是什么

AgentManager 每个方法都在调 self._harness_manager,这个边界值得单独看一眼。

harness 侧的结构出奇地简单,就两个类:

class AgentEntry:
    """Registry record for a managed agent."""

    def __init__(self, *, agent_id, agent, config, metadata, tags, created_at):
        self.agent_id = agent_id
        self.agent = agent                    # 真正的实例
        self.config = config
        self.metadata = metadata
        self.tags = tags
        self.created_at = created_at


class AgentRegistry:
    """``agent_id → AgentEntry`` map with add/get/remove/list."""

    def __init__(self) -> None:
        self._entries: dict[str, AgentEntry] = {}

    def add(self, entry: AgentEntry) -> None:
        if entry.agent_id in self._entries:
            raise ValueError(f"Agent '{entry.agent_id}' already exists in the registry.")
        self._entries[entry.agent_id] = entry

一个 dict,连锁都没有(靠上层保证)。 这正是 Octop 侧要上三层防重的原因——注册表自己不做并发保护。

再往里,HarnessAgent 的 docstring 交代了本质:

A production-ready agent built on deepagents.create_deep_agent.

也就是说,Agent 的运行时就是 deepagents 的一个实例(当前装的是 0.7.28),HarnessAgent 只是把 backend、session logger、model router、内置技能这些东西组装成一个 CompiledStateGraph 再包一层。

这解释了启动那 230 毫秒花在哪:编译 LangGraph 图。acreate_agent 的实现就是一句话:

async def acreate_agent(self, config, *, metadata=None, tags=None, agent_id=None, init_workspace=True):
    """Off-loop wrapper around create_agent (graph compile blocks the event loop)."""
    return await asyncio.to_thread(self.create_agent, config, ...)

graph compile 会阻塞事件循环,所以必须 to_thread。这和上一篇讲的"单进程 + 重 CPU 阻塞"是同一件事的两个面。

这一节最后,我想把三条注释抄出来。它们不是设计文档,是事故记录,比任何架构图都值钱:

第一条,关 Agent 的顺序不能错。

def _quiesce_octop_memory(self, agent_id: str) -> None:
    """Stop memory GC before the harness closes the SQLite backend.

    ``octop-memory`` runs lifecycle GC on a daemon thread. Closing the
    store while ``list_candidates`` is in flight segfaults (Linux live CI
    and Windows unit tests with a real HarnessAgentManager).
    """

段错误。 因为 octop-memory 在守护线程上跑 GC,Python 侧把 store 关了,那边还在 list_candidates 扫——直接踩空。所以卸载 Agent 要先"静默"内存系统,再关 store。

第二条,同步 close 不能扔进线程。

async def aremove_agent(self, agent_id: str) -> None:
    """Drop one agent and await resource release on this event loop.

    Sync :meth:`close` must not run in ``to_thread``: aiosqlite is bound
    to this loop, and the worker-thread fallback (``asyncio.run`` on
    ``stop()`` / ``close()``) waits for a loop that is itself waiting
    for the worker — the hang seen when Octop reloads MCP mid-chat.
    """

自死锁:aiosqlite 绑定在主 loop 上,线程里 asyncio.run 又开一个新 loop 去等主 loop,主 loop 同时在等这个线程。“聊天到一半重载 MCP 会卡死"就是这么来的。

第三条,超时不等于失败。 前面 boot() 里那个 if self._octop_harness_or_none(...) is not None。

三条都指向同一件事:异步 + 线程 + 外部存储三者混在一起时,正确性靠的是顺序,而顺序没有类型系统帮你检查。 只能靠注释把血泪记下来。

总结

AgentManager 读下来,四件事各有各的难:

  1. 启动是全量 eager,不是懒加载。 boot() 遍历所有行逐个 _start_agent,跳过 last_state=stopped,60 秒超时且"超时但已注册"算成功。实测每 Agent 约 230ms,据此推算这个单实例的合理容量是几十到几百个 Agent,不是几千。
  2. 注册上了三层防重(per-agent 锁 + 幂等检查 + 异常兜底),因为"启动 / 热重载 / 手动重载"三条路会撞车。但第三层用异常文案做字符串匹配,是个应该上技术债清单的脆弱耦合。
  3. 执行按 (Agent, thread) 加锁,防的是 LangGraph checkpoint 交错写入;resume_hitl 和 cron 绕过 Dashboard 防抖锁,所以这层锁必须有。
  4. reclaim 不卸载 Agent,只压 SQLite 的 freelist。 Agent 一旦启动就常驻到进程退出。为此设计了一套四角色互斥(active / waiters / holds / backfills),_begin_invocation 先登记再等待、_try_acquire_reclaim 双重检查,是全篇写得最讲究的一段。

另外一个读源码才发现的细节,顺带记一下:_agent_lifecycle_locks 和 _thread_execution_locks 这两个字典只增不删。delete() 里清了 _bootstrap_known 和 _plugin_tool_labels,唯独没清锁字典——说明作者是注意过清理这事的。单个 asyncio.Lock 很小,但 _thread_execution_locks 的 key 是 (agent_id, thread_id),量级跟着会话数走:聊过一万个 thread 就常驻一万个锁对象。对自托管长期运行的服务来说,这是笔慢泄漏,说大不大,说小也不小。

下一篇写 多用户隔离与配额:agents.user_id 的行级归属怎么落到每个路由、resource_policy 那套配额检查在哪几个口子上、以及"共享 Agent"这个设计为什么会让工作区变成共享的。

参考链接