架构

面向 AI Agent：本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/architecture/index.md，文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

Ankole 是一套配备公司大脑的企业级 Agent Harness。Ankole 部署在企业基础设施中，为企业 Agent 提供公司知识、权限控制、长任务恢复和结果反馈。

Agent 可以连续工作数小时，使用共享的公司大脑，通过浏览器、终端、文件和外部系统执行任务。Agent 交付的判断附带可供人工检查的证据，并由后续结果检验。

Harness 识别每个行动主体，执行访问规则，恢复中断的长任务，根据新信息更新上下文，并将人工纠正用于后续决策。

系统总图

每个私有部署实例包含一个逻辑控制面，并可连接一台或多台 Agent Computer Worker。控制面管理身份、状态和调度。Worker 提供 Agent 的执行环境。

SignalsGateway 接收外部聊天、Webhook 和计划任务。身份提供商提供人员与组织目录。AIGateway 统一处理模型、Embedding、Rerank、图像和 Web 工具调用。

控制面与 Agent Computer Worker

控制面保存状态并提交决策

控制面使用 Elixir/OTP，负责 Console、主体与权限、系统配置、信号路由、Actor 会话、Brain、后台 Agent 任务、AIGateway 和 Control Plane Plugin。

所有会改变用户可见结果的状态都先写入 PostgreSQL，再驱动执行或对外投递。进程重启后，已接收的消息、任务状态、记忆和审计记录仍然保留。

OTP 监督树为 Agent、连接和后台任务划分独立故障域。某个执行分支卡住或崩溃时，控制面只恢复该分支，其他部分继续运行。

Worker 提供 Agent 工作环境

Agent Computer Worker 运行模型循环、工具、Skill、浏览器、终端和文件操作，也运行 Automation Job 脚本。控制面创建并提交需要持久保存的业务状态。Worker 接受控制面调度，并将执行结果提交给控制面。

一台 Worker 可以运行多个 Agent，每个 Agent 使用独立的轻量沙盒。需要加强隔离时，可为 Agent 分配专用 Worker。增加 Worker 可以提高并发量，也可以将安全要求不同的任务调度到不同节点。

RuntimeFabric 通过 ZeroMQ 连接控制面与 Worker，传递唤醒、引导、取消、进度和执行结果。RuntimeFabric 负责低延迟实时通信。连接中断后，控制面根据 PostgreSQL 中的状态恢复任务。

一条消息如何变成可恢复的工作

SignalsGateway 接收外部事件

聊天适配器、Webhook 和计划任务先将外部事件转换为统一信号。信号路由规则指定接收信号的 Agent 和会话，以及回复的目标频道或话题。

群聊可以只处理明确提及 Agent 的消息，也可以记录未提及 Agent 的对话，或允许 Agent 判断是否主动介入。可用模式取决于聊天平台和信号路由规则。

SignalsGateway 先保存收到的消息及其来源，再唤醒 Agent。回复在发送前进入可追踪的投递状态，再由适配器发送到聊天平台。系统分别记录回复内容和投递结果。

触发器可以唤醒 Agent，也可以运行脚本

Cron、Checkback 和 Webhook 端点都可以作为触发器。触发器默认唤醒 Agent 会话。绑定 Automation Job 后，触发器运行 Agent 编写的确定性脚本。

脚本静默执行确定性检查，每次运行都留下可查询的记录。需要 Agent 判断时，脚本通过 emitEvent 将事件发送到发起任务的会话，再由 Agent 复核并执行操作。模型无需持续轮询。参见 Automation Job。

Actor Runtime 管理长时会话

每个活跃会话都是可寻址的 Virtual Actor，包含信箱、生命周期和恢复点。新消息或计划任务可以唤醒 Actor。Actor 在执行期间可以接收补充信息、取消请求和人工引导。

Actor Runtime 管理长任务身份，并为每个回合创建新的执行实例和提交隔离标识。Worker 只能提交当前获得授权的回合。恢复或重试后，过期 Worker 无法覆盖较新的结果。

流式内容表示执行进度。控制面确认并持久化的消息、工具结果和状态迁移构成已提交记录。控制面将「界面显示工作进度」与「工作已经完成」作为两种状态分别记录。

Brain 维护当前世界模型

Brain 将聊天、Source 和 Agent 写入的内容整理为可更新的世界模型。新证据可以补充、修正或取代已有 Claim。证据发生冲突时，Dreaming 保留冲突并提交人工复核，原有 Claim 继续保留来源和历史。

知识可以来自 Agent 参与的对话、未明确提及 Agent 但符合学习条件的群聊消息，以及已注册的文件或 URL Source。

同一实例中的所有 Agent 共用一个知识空间。每个受保护的正文段落、Claim 和时间线事件都使用以下一种可见范围：world、权限组或单个 Principal。Source 或 Channel 记录出处。学习所得知识的访问权限由可见范围决定。

运行中的 Agent 通过统一的召回接口获得当前任务需要的长期上下文。离线 Dreaming 整理新证据、发现模式、评估到期预测，并标记等待复核的冲突。

Brain 负责维护当前世界状态。Skill Lessons 保存 Agent 从重复工作中学到的规则。Skill Lesson 随对应 Skill 提供，保留 Skill 的来源，并在失效后停用。

Brain 为 Agent 提供长期记忆，并负责存储、Dreaming 和写入权限。

后台 Agent 任务运行长时工作

主 Agent 可以将调研、数据分析、文件处理、代码修改和 Deep Research 等边界明确的工作交给后台 Agent 任务。后台任务运行期间，主会话仍可继续与用户交流。

后台任务的生命周期保存在控制面中，Worker 负责实际执行。如果 Worker 中断，控制面会重新派发任务，并从已保存的状态继续执行。

主 Agent 与后台任务可以继续通信。后台任务可以请求用户补充信息、返回失败信息和最终结果，也可以按要求静默运行。等待用户输入时，后台任务释放执行资源，并在收到回答后恢复。

Deep Research 使用这套机制。Agent Plugin 提供工作区模板，Skill 提供研究方法，后台任务负责持久执行，Agent Home 保存研究资料与交付物。

参见 后台 Agent 任务 和 Deep Research。

AIGateway 统一模型调用边界

AIGateway 是模型调用的统一边界。主 Agent、后台任务、Brain 和外部 API 客户端都通过 AIGateway 使用 LLM、Embedding、Rerank、图像、Web Search 和 Web Fetch 服务。

Agent 的模型档案指定执行所用的模型。Brain 使用 AppConfigure 中的五项实例级模型设置。控制面加密保存 Provider 凭证，AIGateway 使用这些凭证请求上游服务。Agent 与 Worker 只能访问获准使用的模型和调用结果。

AIGateway 支持不保存历史的单次调用和可继续的有状态会话。AIGateway 负责请求转换、流式事件、工具结果、上下文压缩、用量记录和最终结果提交，并统一处理各 Provider 的生命周期。

工具数量较多时，模型可以通过 Tool Search 按需检索工具，也可以提交程序，在受限沙盒中批量调用工具并返回结果。原生支持这些能力的 Provider 直接处理请求，其他 Provider 由 AIGateway 提供对应实现。一个 Provider 可以配置多个凭证组成凭证池，其中包括 ChatGPT 订阅等账号凭证。系统按单个凭证记录失败、重试和用量。

参见 AIGateway 和 添加 LLM Provider。

企业身份、权限与扩展

Ankole 将人员、Agent 和系统服务统一表示为主体（Principal）。身份提供商（IdP）负责 Console 的 SSO 登录，并同步员工、通讯录和组织目录。聊天渠道负责收发消息。身份提供商和聊天平台可以不同。

AuthZ 根据主体、权限组、资源、动作和条件，在运行时作出授权决定。AuthZ 判定由运行时执行，提示词和模型输出不能授予权限。

Control Plane Plugin 将 IdP、聊天渠道和其他控制面能力接入实例。Agent Plugin 为 Agent 增加工具和工作区模板。Skill 描述完成某类工作的步骤，并可限定在主 Agent 或后台任务中使用。

外部 MCP 服务器通过 Skill 接入。Skill 声明连接，Worker 为每次执行生成配置，并在执行结束后删除配置。模型只会看到当前 Skill 声明的 MCP 工具。

参见 主体与权限组、信号路由规则、Agent 能力库 和 MCP 服务器参考。

持久化边界

PostgreSQL 保存身份、权限、配置、消息、会话、任务、记忆、投递状态和审计记录等权威领域状态。需要判断一项工作是否已经提交时，以这些记录为准。

Agent Home 保存工作区文件、工具产生的中间文件和最终交付物。单机部署可以使用本地磁盘或虚拟磁盘。多 Worker 的 Kubernetes 部署需要 NFS 等支持 ReadWriteMany 的共享卷。

RuntimeFabric、Worker 进程内状态和流式预览都可以重建。任务恢复以 PostgreSQL 和 Agent Home 中的状态为准。

三种部署形态

三种部署方式使用相同的逻辑边界。每个实例包含一个控制面，并可按需增加 Worker。完整步骤见 快速开始。

支撑运行时的五项技术选择

Agent 可以连续工作数小时，并在运行中接收新信息。运行时可以独立恢复失败的执行分支，并为每项已提交的工作保留审计记录。

更完整的运行时论证见 《为什么 OTP 是更好的多智能体编排运行时》。