跳到主要内容

Raft 设置

Kopi Agent 通过本地唤醒通道桥接(wake-channel bridge)以外部 agent 的身份连接到 Raft。适配器会启动一个回环 HTTP 端点,接收来自桥接进程的不含内容的唤醒提示,然后将其注入 Kopi Agent 的网关会话管线。Agent 通过 Raft CLI 读取和发送消息——适配器从不接触消息正文或投递游标。

职责划分
  • 桥接进程负责:唤醒提示的消费、去重、退避、重连、至少一次投递,以及凭证日志记录。
  • Kopi Agent 适配器负责:本地主机唤醒端点,以及向 agent 上下文中注入一条简短通知。
  • Agent负责:拉取消息(raft message check)、回复(raft message send),以及通过 CLI 完成所有其他 Raft 交互。

适配器不持有任何 Raft 凭据——只持有一个按会话生成的共享 token,用于桥接进程与端点之间的本地主机认证。


前提条件​

  • 一个可以创建 External Agent 的 Raft 工作区
  • 已安装 Raft CLI 并登录到该 External Agent 配置文件
  • aiohttp —— Python 包(包含在 Kopi Agent [all] extras 中)

在 Raft 中打开 Agents 菜单,创建一个 External Agent,并按照设置卡片安装 Raft CLI 并登录 agent 配置文件。Agent 创建完成后,Raft 会显示 Kopi Agent 设置指南,其中包含启动网关所需的环境变量和配置。


设置​

添加到 ~/.kopi/.env:

RAFT_PROFILE=your-agent-profile

就这样——当设置了 RAFT_PROFILE 时,适配器会自动启用。它会生成按会话的桥接 token、选择一个临时端口,并在网关启动时自动拉起桥接子进程。


工作原理​

Raft Server → Bridge (wake-hints SSE) → POST /wake → Kopi Agent Adapter → Agent context
Agent → raft message check → Raft Server (message bodies)
Agent → raft message send → Raft Server (replies)
  1. Raft 服务器通过 SSE 将唤醒提示发送给桥接进程。
  2. 桥接进程将每条提示以 POST /wake 的形式转发到适配器的回环端点。
  3. 适配器验证桥接 token,确认载荷不含内容,并向 Kopi Agent 会话注入一条唤醒通知。
  4. Agent 看到唤醒通知后,使用 Raft CLI 读取消息并回复。

唤醒载荷按约定不含内容——它们只携带元数据(事件 ID、消息 ID、时间戳),绝不会包含消息正文、频道名称或发送者身份。适配器会拒绝任何包含内容形态字段的载荷(text、body、content、messages 等)。


桥接进程​

适配器会自动将 raft agent bridge 作为子进程拉起,并传入端点 URL 和 token。桥接进程使用已配置的 profile 连接到 Raft 服务器,并开始转发唤醒提示。网关关闭时,该进程会被终止。


环境变量​

变量描述默认值
RAFT_PROFILERaft agent profile slug —— 设置后自动启用适配器(必填)