33 KiB
AgentHub
多 Agent 协作控制面:把本地进程、Docker 容器、云端实例里的各种 Agent 统一纳管起来, 用一条 Gateway 通信,用一套 Playbook 编排协作。nanobot 是第一个被纳管的 Agent,但不是唯一一个 ——DeepSeek Harness、codex / claude / WorkBuddy 这类无头 CLI、OpenClaw、任何 OpenAI 兼容服务都能接进来。
规划文档见 docs/PLAN.md;跨 Agent 类型的注册与身份规范见
docs/AGENT_REGISTRATION.md。soucecode/(nanobot、agent-town 的参考 clone)
已 .gitignore,不参与构建。
浏览器 ── ▶ 控制台 (Next.js, :3100)
│ REST + WebSocket/SSE(API Key)
▼
AgentHub Hub (FastAPI, :8100)
├ Registry 登记 / 身份 / 能力 / 凭证
├ Gateway Frame 协议 + 事件总线 + 帧审计
├ Tasks 单 Agent 任务(流式事件)
├ Collab 团队 / Playbook / Run / 黑板 / 交接
└ Deploy 接入片段渲染 + 签发存档
│ 唯一一条通道:Gateway 的 Frame 协议(JSON 帧 + 流式事件)
┌──────────────┴──────────────┐
▼ 外拨(push) ▼ 直拨(direct)
Agent 自己连 hub hub 拨 Agent 的 HTTP/WS
nanobot 渠道 / dsh 插件 / 桥接 nanobot serve / OpenAI 兼容 / OpenClaw
只有 Gateway 一个通信进程:建档、派活、流式事件、心跳、探测、取消、指令全走同一套 Frame 协议,
两种形态的差别只在「谁发起这条连接」。帧类型:
agent.hello/hub.hello/heartbeat/ping/probe/event/command/describe/deregister/changed、
task.run/cancel/changed、run.changed、hub.event(s)、frame.audit。
Agent 侧走 WS /api/v1/gateway/ws?agent_token=ag_…,控制台事件流走 WS /api/v1/stream。
| 形态 | connection_mode |
谁发起连接 | Agent 侧改动 | 什么时候用 |
|---|---|---|---|---|
| 外拨(推荐) | embedded / connector |
Agent 进程里的接入件往外拨 WS | 装接入件 + 写一段 config | 能改 Agent 的镜像 / 依赖;NAT 后、只有出网权限的容器和云主机 |
| 直拨 | direct |
hub 直接拨 Agent 的 HTTP/WS | 0 改动 | hub 能直达 Agent。「接入」向导不提供这一类,只能手工登记 |
driver_for() 对 connection_mode in ("connector", "embedded") 一律返回 connector 驱动:
embedded 和 connector 在 hub 侧是同一条通道,driver 只说明背后跑的是什么。
快速开始
./scripts/dev.sh # 一键起 hub + 控制台,缺依赖自动补装
./scripts/dev.sh --seed # 顺便灌一份演示 Agent / 团队
./scripts/dev.sh --reload # 后端带 --reload
HUB_PORT=8200 CONSOLE_PORT=3200 ./scripts/dev.sh
脚本会检查端口占用(被 launchd 托管时说明为什么杀不掉),并把控制台用的 API Key 打在终端上。
Ctrl-C 一起停两个进程。容器版在 deploy/docker-compose.yml。
手工两步:
# 1) 后端(Python 3.11+)
cd backend && python -m venv .venv && source .venv/bin/activate
pip install -e . # 国内可加 -i https://pypi.tuna.tsinghua.edu.cn/simple
agenthub init # 建表 + 生成 <data_dir>/hub-credentials.json
agenthub serve # http://127.0.0.1:8100 ,API 文档 /docs
# 2) 前端(Node 20+,pnpm)
cd frontend && pnpm install && pnpm dev # http://127.0.0.1:3100
控制台右上角「配置 API KEY」粘贴 hub 的 API Key(首次启动写在 data/hub-credentials.json),Key 只存浏览器 localStorage。
接入:三步向导
只有两类接入:插件 / 渠道(Agent 里本来就有可以装东西的地方)和桥接(Agent 只有一套 CLI, 旁边跑一个进程替它拨 hub)。向导就三步,按钮只有下一步 / 上一步 / 完成:
| 步骤 | 内容 |
|---|---|
| ① 选择类型 | 插件 / 渠道 · 桥接 |
| ② 选择 Agent | DeepSeek Harness、nanobot、OpenClaw / codex、claude、WorkBuddy;填「Agent 名字」。只有桥接多问两个:工作目录 + 权限(readonly / write) |
| ③ 生成凭证 | 走到这一步就已经签好了:直接显示 ag_… 明文和那段配置原文,各自带 COPY。想换一把点右侧小号「重新签发」;点「完成」回到第 ① 步 |
页面顶部只有一行 Hub 地址 <url> + COPY —— Agent 侧那一格 server 就抄它。
名字已在册时不报错拦人:hub 返回 409 时向导自动改成给原来那一行换一把新凭证(同一台 Agent 重新接一次就是这个场景)。
签发一次实际发三个请求:
POST /api/v1/agents { …建档, issue_credential: true } → ag_…
POST /api/v1/agents/{name}/credentials (仅同名 409 时)
POST /api/v1/deploy/plan { kinds:[kind], agent_ref, agent, agent_token, record: true }
四种片段
POST /deploy/plan 返回 { agent, hub_url, files:[{kind, filename, content}], next_steps, note };
KINDS = ("bridge","nanobot","dsh","claw"),文件名分别是 bridge.sh、nanobot-config.json、
cordis.patch.yml、openclaw-agenthub.json。不管哪一类,Agent 侧要填的都只有两格:
哪个 hub(server)+ 我是谁(agent_token)。没有 hub id、也没有 agent id 可抄——
凭证就是身份,socket 起来之后 hub 把自己的那份 id 告诉 Agent。
# cordis.patch.yml(dsh)——接进 ~/.dsh/profiles/<profile>/cordis.patch.yml 顶层数组
- insert:
- id: dsh-agenthub
name: '@nex/dsh-agenthub'
config:
server: http://127.0.0.1:8100
name: dsh-web
displayName: dsh-web
agentToken: ag_xxxxxxxx
// nanobot-config.json → ~/.nanobot/config.json 的 channels.agenthub
{ "channels": { "agenthub": { "enabled": true, "server": "http://127.0.0.1:8100",
"name": "alpha", "display_name": "alpha", "agent_token": "ag_xxxxxxxx" } } }
// openclaw-agenthub.json → OpenClaw 的 agenthub 渠道配置
{ "agenthub": { "enabled": true, "server": "http://127.0.0.1:8100",
"name": "claw-1", "display_name": "claw-1", "agent_token": "ag_xxxxxxxx" } }
# bridge.sh —— 在有这套 CLI 的机器上跑,它自己往外拨 hub
python3 <本仓库>/deploy/cli-bridge/bridge.py --hub http://127.0.0.1:8100 --token ag_xxxxxxxx \
--name codex-1 --cli codex --workdir ~/code/目标仓库 --mode readonly
桥接的工作目录与权限存在这一行的 config 里(_LANDED_KEYS = ("profile","cli","workdir","mode")),
所以按 agent_ref 重新生成片段时能还原出当时贴出去的那条命令。DSH 的 profile 后端仍支持,
但向导已不再问这一格:给已在册的 DSH 重生成 next_steps 时回落 web profile。
签发记录
向导下面的「签发记录」面板是每次签发的存档本身,不是连入的 Agent 列表:
一行一次签发,平时只看到「签给谁 + 类型 + 时间」,点开才是当时那把 token(明文)和那段配置原文。
同一 Agent 的旧记录标 已失效。
| 项 | 实现 |
|---|---|
| 表 | credential_issuances(id/agent_id/agent_name/kind/hub_url/payload_cipher/active/created_at) |
| 落盘 | security.seal(secret_key, {agent_token, files}),读时 unseal;换过 secret_key 解不开就给空,不猜内容 |
| 读 | GET /api/v1/deploy/issuances?limit=50(token 是明文) |
| 写 | POST /deploy/plan 带 record: true,要求 admin key(read key → 403)。向导走的就是这条,所以存档和贴出去的片段不可能漂移 |
凭证回看与轮换
签过的凭证随时能查回来,不必为看一眼明文而轮换:
- 控制台:Agents 详情页的「凭证」面板(状态 / 查看凭证 / 签发或轮换凭证 / 轮换宽限秒数),或接入页的「签发记录」。
- API:
GET /api/v1/agents/{ref}/credentials(管理员 key;库里为此另存一份 seal 的可读副本token_cipher,认证仍只读哈希)。 - CLI:
agenthub config --name X --kind bridge|nanobot|dsh|claw(已在册的直接印真值,未建档留<agent_token>占位)。
签在「可回看」之前的老凭证读不回明文(库里只有哈希),点「重新签发」换一把之后就能反复查看。
命令行等价(绕开向导时用):
agenthub agent add --name codex-1 --connection connector --driver connector --show-token
agenthub agent rotate codex-1 # 立即失效;API 侧还能给 grace_seconds
接入件
接入件随 Agent 走:每种 Agent 一个专门的接入件,hub 不替它们做部署。协议同一套,所以凭证可以互相替换。
内嵌 SDK:把 Gateway 客户端塞进 Agent 进程
deploy/nanobot-gateway/channel/agenthub/agenthub_client.py 是那个单文件客户端(标准库 + websockets)。
接自己的 Agent 就 import 它写十几行:
import os
from agenthub_client import GatewayClient, GatewayConfig
async def on_task(task, emit) -> str: # task 里有 prompt / session_key / context
async with my_agent.turn(task["prompt"]) as turn:
async for chunk in turn:
await emit("delta", text=chunk) # status / delta / reasoning / tool / log
return turn.answer
async def describe() -> dict: # 可选:能力自述,控制台会显示
return {"streaming": True, "runtime": "my-agent"}
client = GatewayClient(
GatewayConfig(
hub_url="http://127.0.0.1:8100",
agent_token=os.environ["AGENTHUB_AGENT_TOKEN"], # 密钥只从环境读,不进代码也不进镜像
name="my-agent",
deployment_kind="docker",
),
on_task,
describe=describe,
)
await client.run() # 断线重连 + 心跳 + 取消,都在里面
身份不落盘:配置里那一把 agent_token 就是它的全部身份,进程重建之后填的还是同一把,agent_id 自然不变。
delta / reasoning / status / tool / completed 原样回到 hub 的事件流。取消也是真的:
客户端收到 task.cancel 调 runner.cancel(),事件流以 cancelled 收场(DSH 插件走 agent.cancel)。
nanobot 渠道
deploy/nanobot-gateway/channel/agenthub/ 是一个 nanobot channel 包。nanobot 只扫
nanobot.channels.__path__,没有外部插件目录,所以装一次进安装树:
cp -R deploy/nanobot-gateway/channel/agenthub \
"$(python -c 'import nanobot.channels as p; print(list(p.__path__)[0])')/agenthub"
// ~/.nanobot/config.json —— 和 telegram、websocket 同级的普通渠道
{ "channels": { "agenthub": {
"enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha",
"display_name": "阿尔法",
"agent_token": "ag_xxxxxxxx" // 只有这一格是凭证
}}}
nanobot gateway --foreground # 渠道拨上 hub 就上线,nanobot 的代码和启动方式都不改
- 字段全在
channels.agenthub下:enabled/server/name/display_name/description/agent_token/deploymentKind/labels; 只有AGENTHUB_AGENT_TOKEN这一把 env 优先级最高(compose 注入用),其余 env 只在没写配置文件时兜底; 旧字段名(hubUrl等)一个版本内仍可读。 describe()回{streaming, model, runtime:"nanobot"},模型由 Agent 自省上报,不在渠道配置里配。- 现成容器:
cd deploy/nanobot-gateway && ./bootstrap.sh→ 写.env(AGENT_TOKEN_ALPHA/AGENT_TOKEN_BETA、DASHSCOPE_API_KEY、NANOBOT_MODEL,模型 key 默认从~/.nanobot/config.json取)→ buildnanobot:agenthub→ 起agenthub-gw-alpha/agenthub-gw-beta(阿尔法 / 贝塔,role writer/editor)。 - 那份 compose 没有任何 ports,healthcheck 打容器内
127.0.0.1:18790(nanobot 自己的健康端点)。 hub 地址用HUB_URL覆盖(默认http://host.docker.internal:8100;host 网络下写127.0.0.1, 同网络写http://hub:8100),落到渠道的AGENTHUB_SERVER(旧名AGENTHUB_HUB_URL仍可读), 再加AGENTHUB_NAME/DISPLAY_NAME/AGENT_TOKEN/DEPLOYMENT_KIND/DEPLOYMENT_REF/LABELS/DESCRIPTION。
DeepSeek Harness 插件(plugins/dsh-agenthub)
DSH 是「一切皆插件」的 Harness,所以接入方式是给它写一个插件,而不是让 hub 去理解它内部: 插件与 DSH 同进程,往 hub 拨一条出站 socket。
hub ◀── 出站 WS ── @nex/dsh-agenthub(DSH 插件,Host 半)
├ task.run → ctx.agents.resume/create + agent.followup(createUserMessage)
├ 过程事件 ← agent/assistant-stream + session/event(tool/call, turn/end)
├ task.cancel → agent.cancel({kind:'user'})
└ 设置面板 ← POST /api/agenthub/status(Client 半:身份 / 连接 / 最近任务)
# 装插件必须用 dsh 自己的命令(手改 profile 的 package.json 不算装)
dsh plugin --profile web add -w link:/绝对路径/nex_agenthub/plugins/dsh-agenthub
# 离线自检:打桩 hub + 伪 Cordis ctx,不需要 DSH 运行时,也不需要真 hub
node plugins/dsh-agenthub/selfcheck.mjs
两个真机坑:profile 必须是 web 模板建的(默认只有 dsh-base,跑一条任务就退出,没有常驻进程去拨 hub);
cordis.patch.yml 里要先删掉占位的 [] 再接片段(两个根节点,YAML 直接解析失败)。
web profile 是 patchReload: live,改 config 存盘即生效,改插件代码要重启 dsh web(Node ESM 缓存模块);
热重载会把同一 entry 应用两遍,插件内按进程做了单例。配置项与会话语义见
plugins/dsh-agenthub/README.md。
无头 CLI:桥接(codex / claude / WorkBuddy)
不动 CLI 一行代码,在它所在机器上跑一个桥接进程(bridge.py 只需要 Python 3,不装任何依赖;
旁边 adapters/ 里一个 CLI 一个适配器,新增一家就加一个文件)。
agenthub agent add --name codex-1 --connection connector --driver connector --show-token
python3 deploy/cli-bridge/bridge.py --hub http://127.0.0.1:8100 --token ag_… \
--name codex-1 --cli codex --workdir ~/code/目标仓库 --mode readonly
| 能力 | codex | claude | workbuddy |
|---|---|---|---|
| 派活 / 事件流 / 续话 / 取消 / describe | ✅ | ✅ | ✅ |
agent.command(会话内下达指令) |
✅ codex queue |
❌ 明确回 delivered:false |
❌ 同左 |
参数:--hub --token --name --cli --workdir --mode --max-concurrency --verbose --state,
分别可用 AGENTHUB_URL、AGENTHUB_TOKEN、AGENTHUB_AGENT、AGENTHUB_CLI、AGENTHUB_WORKDIR、
AGENTHUB_MODE、AGENTHUB_STATE 兜底;state 默认 ~/.agenthub/cli-bridge-<name>.json。
细节与两个真机坑(claude/workbuddy 的 --add-dir 是变长参数)见
deploy/cli-bridge/README.md。
派完活想回到那套 CLI 的原生会话里接着看:
./scripts/attach.sh tsk_8b4337cc… # 本机直接进;跨机器自动走 ssh
./scripts/attach.sh -n tsk_xxx # 只打印命令不执行
HUB_URL=http://10.0.0.5:8100 HUB_KEY=agp_xxx ./scripts/attach.sh tsk_xxx
会话记录存在 Agent 那台机器的磁盘上(~/.codex/sessions/、~/.claude/projects/<cwd>/…)且按工作目录归档,hub 只有事件流。
直拨(direct)
hub 拨 Agent,Agent 零改动、零凭证。向导不提供这一类,手工登记:
agenthub agent add --name nanobot-1 --driver nanobot --connection direct \
--base-url http://127.0.0.1:8900/v1 # 需要鉴权就配 auth
agenthub agent add --name local-llm --driver openai_compatible --connection direct --base-url …
AgentHub 的 nanobot driver 按真实实现对齐,并且有一组互测直接跑上游 create_app()
(backend/tests/test_interop_nanobot.py)保证没有跑偏:
| nanobot 的约定 | 真实行为 | AgentHub 的处理 |
|---|---|---|
| 启动 | nanobot serve --host 0.0.0.0 --port 8900;绑定非本机地址时 ~/.nanobot/config.json 必须有 {"api":{"api_key":"…"}},否则拒绝启动 |
接入时填 Bearer Key |
| 健康 | GET /health → {"status":"ok"},不鉴权 |
probe 与在线状态走它 |
| 模型 | GET /v1/models 只列它自己配的那一个;请求里的 model 不匹配就 400 |
driver 先探测并缓存,探不到就不传 model;控制台显示的模型一律由 Agent 自省上报(心跳里的 capabilities.model) |
| 消息 | messages 只允许一条 user 消息,多条直接 400 |
协作指令和队友上下文折叠进同一条 user 消息,prompt 放最后 |
| 会话 | session_id 对应服务端会话 api:<session_id> |
任务的 session_key 原样传下去,同一轮协作复用 nanobot 自己的记忆 |
curl -X POST http://127.0.0.1:8100/api/v1/tasks -H "X-API-Key: $KEY" -H 'content-type: application/json' \
-d '{"agent_id":"nanobot-1","prompt":"只回一句话:你好","session_key":"demo-1"}'
真实 nanobot 互测(可选;没有 nanobot 环境时整组自动 skip,也可用 AGENTHUB_NANOBOT_PYTHON=/path/to/python
指向任何能 import nanobot 的解释器):自备一份 nanobot 源码 →
NANOBOT_SKIP_WEBUI_BUILD=1 uv pip install --python .nanobot-venv/bin/python "/tmp/nanobot-build[api]"
→ cd backend && .venv/bin/python -m pytest tests/test_interop_nanobot.py -q。
nanobot_ws:走 WebUI 那条 WebSocket
nanobot gateway 自带一条 WebSocket 渠道(默认 127.0.0.1:8765),官方 WebUI 只是它的一个客户端:
一条 socket 多会话,派活是一个 {"type":"message","chat_id":…,"content":…} 信封,回复按
delta / stream_end / reasoning_delta / message(kind=tool_hint) / file_edit / turn_end 流回来。
nanobot_ws driver 复用的就是这条通道,没有第二套协议。
nanobot gateway # ws://127.0.0.1:8765/ ;要 token 就配 channels.websocket.token
curl -X POST http://127.0.0.1:8100/api/v1/agents -H "X-API-Key: $KEY" -H 'content-type: application/json' \
-d '{"name":"nano-ws","driver":"nanobot_ws","agent_type":"nanobot","connection_mode":"direct",
"base_url":"http://127.0.0.1:8765","auth":{"token":"wyc-secret"}}'
base_url写成http://host:8900/v1也认得,默认端口按 8765 推;路径不同给config.path,TLS/反代给config.ws_url。session_key就是 nanobot 会话:driver 把它换成agenthub-<key>形态的chat_id(非法字符或超长取哈希), 同一个 key 永远落进同一个 session,「工作台」里连续追问能续上上下文。- 轮次终点认
turn_end(带 usage / outcome),不是「一段时间没消息」;outcome=failed让任务失败并带回failure_message。 - nanobot 的渠道协议没有中止信封,所以
nanobot(HTTP)和nanobot_ws的cancel()老实返回 false: 控制台取消会把任务停在cancelled,但不会假装已打断 Agent 那一轮。外拨接入件才有真取消。
Agent 类型与像素小人
agent_type 和 driver(怎么通信)、deployment_kind(跑在哪)是三个正交维度。办公室里的像素小人按它取配色和头饰:
| 类型 | 值 | 形象 | 典型 driver |
|---|---|---|---|
| nanobot | nanobot |
金色工装 + 头顶天线 | nanobot(HTTP)、nanobot_ws(WebSocket) |
| DeepSeek Harness | deepseek_harness |
靛蓝工装 + 青色护目镜 | DSH 插件(connection_mode=embedded) |
| OpenClaw | openclaw |
钢蓝工装 + 鸭舌帽 | openclaw(gateway 帧 RPC,实验) |
| Hermes | hermes |
琥珀工装 + 羽翼头环 | 待接入(先占类型与形象) |
| 其它 | custom |
沿用按 driver 取色的老规则 | mock / openai_compatible / connector |
留空=跟随 driver,换 driver 类型自动跟着变;显式选了钉住不动。GET /api/v1/agents?agent_type=hermes 按类型过滤。
老库升级不用手工迁移:启动/agenthub init 时自动增量 ALTER TABLE。
控制台
Next 16.1.6 / React 19.2.3 / Tailwind 4 + lucide-react + @tanstack/react-virtual(全在 devDependencies)。
脚本:dev(next dev -p 3100)/ build / start / lint / typecheck / format / format:check。
| 页面 | 用途 |
|---|---|
| 总览 | Agent/任务状态分布、最近 Run、Presence 判定来源、最后一帧 |
| 办公室 | 像素办公室:一 Agent 一工位,屏幕写正在跑的 prompt,走位对应状态,墙上一块看板(左在岗状态、右任务队列),机柜告警闪红灯。产出只在右边控制台,画面里不重复;点工位可直接下指令。画布按「显示宽度 × devicePixelRatio」渲染,布局 lib/office-layout.ts、配色 lib/office-palette.ts |
| 工作台 | 通用派活面板:左边全部 Agent(本地/容器/远端一视同仁),右边一条按 session_key 延续的对话,reasoning / 工具调用 / 产出同一条 SSE,在跑的能取消 |
| Agents | 只管管理:搜索 name/driver/host、按状态与接入方式筛选、主动探测、删除登记、逐行详情。没有登记入口——建档与签发都在「接入」页 |
| Agent 详情 | 凭证(查看 / 签发 / 轮换 + 宽限秒数)、指令 command、probe、describe、这个 Agent 的任务列表 |
| 任务 | 单 Agent 任务列表与流式事件(delta / reasoning / tool / log) |
| 团队 | 成员与角色、Playbook、Run 时间线、共享黑板、Agent 间消息;/runs/{id} 是 Run 详情 |
| 接入 | 顶部一行 Hub 地址 + COPY;三步向导;下面「签发记录」 |
| 设置 | Hub、Gateway、API 密钥(控制台面)+吊销、Gateway 帧窗口、审计日志、最近帧原始 JSON |
暗 / 亮主题在右上角(默认暗色),记在 localStorage,首帧由 app/layout.tsx 内联脚本写好 data-theme,刷新不闪。
四种 Playbook:sequential(A→B→C)、parallel(并行后汇总)、round_robin(N 轮讨论)、
handoff(Agent 输出交接块决定下一步交给谁)。Agent 侧零改造:hub 把 hub 地址、run id、
短期 run grant、「你是这队伍里的哪一个」写进 prompt,Agent 想协作时按提示 curl 一下 /collab/* 即可。
交给自己的交接块会被忽略并结束本次 Run,避免原地打转。
控件规格
- 尺寸只有两档:
md= 32px(页面/卡片主操作、表单行),sm= 26px(工具条、表格行内动作、chip)。 边框 2px、圆角 6px、ArkPixel 字体(11px / 10px)、焦点环 2px 金色;token 在app/globals.css的--ctl-*。 - 页面只用原语:
Panel PixelButton LinkButton Dot Badge Input Select Textarea SearchInput Field Tabs Chip Modal Empty ErrorNote CopyButton JsonBlock Spinner KV usePaged/Pager(都在components/ui.tsx), 没有裸<button>和裸类名。lib/:api format office-layout office-palette sse theme theme-keys types useAsync useHubSocket。 - 提示窗体只有两种:要用户点头的用
useConfirm()(危险动作默认焦点在「取消」,确认按钮红色), 只报结果用useToast()(右下角,错误 8s / 成功 3.2s)。代码里不允许window.confirm/alert/prompt。 - 弹窗外壳统一:
size="sm|md|lg"(420 / 640 / 920px),动作右对齐——取消在左、危险动作居中、主操作最右。
配置
全部走 AGENTHUB_ 前缀环境变量(也支持 backend/.env):
| 变量 | 默认值 | 说明 |
|---|---|---|
AGENTHUB_HOST / AGENTHUB_PORT |
127.0.0.1 / 8100 |
监听地址 |
AGENTHUB_HUB_PUBLIC_URL |
同监听地址 | 写进接入片段与协作 briefing 的对外地址 |
AGENTHUB_DATA_DIR |
<仓库根>/data |
SQLite 文件与 hub-credentials.json 位置;默认值锚定仓库位置,与启动目录无关 |
AGENTHUB_DATABASE_URL |
由 data_dir 推导 | 换库只改这里 |
AGENTHUB_DB_POOL_SIZE / AGENTHUB_DB_ECHO |
5 / false |
连接池 |
AGENTHUB_API_KEY / AGENTHUB_SECRET_KEY |
自动生成 | secret_key 也是凭证与签发存档的 seal 密钥 |
AGENTHUB_AUTH_ENABLED |
true |
控制台面鉴权 |
AGENTHUB_DEV_DISABLE_AUTH |
false |
仅本地调试 |
AGENTHUB_GRANT_TTL_S |
21600 |
协作 run grant 的存活秒数 |
AGENTHUB_HEARTBEAT_INTERVAL_S / _TIMEOUT_S |
15 / 45 |
外拨 Agent 心跳 |
AGENTHUB_PRESENCE_INTERVAL_S / AGENTHUB_PRESENCE_ENABLED |
5 / true |
presence 扫描 |
AGENTHUB_DIRECT_PROBE_INTERVAL_S |
60 |
直拨 Agent 的定期探活 |
AGENTHUB_TASK_TIMEOUT_S / AGENTHUB_MAX_CONCURRENT_TASKS |
300 / 16 |
任务闸门 |
AGENTHUB_CONNECTOR_RPC_TIMEOUT_S |
60 |
走 Gateway 的 RPC 超时 |
AGENTHUB_EVENT_BUFFER_SIZE / AGENTHUB_FRAME_AUDIT_LIMIT |
2000 / 500 |
事件与帧审计环形窗口 |
AGENTHUB_PERSIST_TASK_EVENTS |
true |
事件是否落库 |
AGENTHUB_CORS_ORIGINS |
* |
生产建议收敛到控制台域名 |
Key 有两种 scope:admin / read。控制台面写操作和 POST /deploy/plan {record:true} 都要 admin。
前端两个构建期变量:NEXT_PUBLIC_HUB_URL(hub 地址,默认 http://127.0.0.1:8100)、
CSP_CONNECT_SRC(hub 不在 localhost 时补 CSP 的 connect-src)。next.config.ts 用 output: "standalone",
并把 NEXT_PUBLIC_HUB_URL 的 origin 自动并进 connect-src。
CLI
agenthub serve [--host --port --reload]
agenthub init | seed [--no-team] | status | agents | doctor | presence
agenthub probe <agent> | task <agent> <prompt> | run <team> <objective>
agenthub agent add --name X [--driver --type --connection --kind --base-url --role --labels K=V --show-token]
agenthub agent rotate <agent>
agenthub config --name X [--kind bridge|nanobot|dsh|claw] [--driver]
init/doctor/status/config/agent add/agent rotate 都能脱机跑(不依赖 HTTP 服务)。没有 agenthub token 子命令。
数据与凭证
12 张表:agents, tasks, task_events, teams, team_members, runs, run_steps, blackboard_entries, inter_agent_messages, api_keys, credential_issuances, audit_logs。启动/agenthub init 时按增量列清单自动
ALTER TABLE,老库不用手工迁移。
- Agent 凭证库里存哈希(认证只读哈希),另存一份 seal 过的可读副本
token_cipher用于回看; 签发存档credential_issuances.payload_cipher同样是seal(secret_key, …)。换过secret_key后这些副本读不回明文, 哈希认证不受影响。 - 模型只用跨库安全的类型(JSON / String / DateTime + UTC),换库基本是改 URL:
pip install -e ".[postgres]" # 或 ".[mysql]"
export AGENTHUB_DATABASE_URL="postgresql+asyncpg://hub:hub@127.0.0.1:5432/agenthub"
# mysql+aiomysql://hub:hub@127.0.0.1:3306/agenthub
agenthub init && agenthub serve
HTTP 面都在 /api/v1 下:/agents(CRUD、credentials 签发与回看、probe、describe、command、tasks、presence)、
/tasks(+ events/stream/cancel/raw)、/teams /playbooks /runs /blackboard /messages、
/deploy/{templates,plan,issuances}、/gateway/{heartbeat,deregister,status,frames,ws,stream,purge}、
/meta /stats /keys /audit /presence、/collab/{blackboard,messages,context}。
Docker 部署
cd deploy
docker compose up -d --build # hub + console
docker compose exec hub cat /var/lib/agenthub/hub-credentials.json # 取 API Key
hub(agenthub:latest,8100,AGENTHUB_HUB_PUBLIC_URL + AGENTHUB_DATA_DIR=/var/lib/agenthub +
volume agenthub-data)+ console(3100,build args NEXT_PUBLIC_HUB_URL / CSP_CONNECT_SRC)。
只有这两个服务,没有 --profile。再纳管 Agent 走各自的接入件(nanobot 用
deploy/nanobot-gateway/docker-compose.yml)。容器里的 Agent 用 http://hub:8100 连 hub,浏览器仍用 http://127.0.0.1:8100。
开发与测试
cd backend && .venv/bin/python -m pytest -q # 142 passed
cd frontend && pnpm typecheck && pnpm lint && pnpm build
| 测试 | 锁住的行为 |
|---|---|
test_db_portability.py |
建表/索引语句在 sqlite / postgresql / mysql 三种方言下都能编译(类型、索引长度、约束命名可移植;不需要装 asyncpg / aiomysql) |
test_gateway_ws.py |
真实 WebSocket 帧格式:派活、探活、一次取消只下发一条 task.cancel、控制台断线用 ?since= 补发 |
test_api_teams.py |
Run 取消会打断正在跑的 step(step 在建任务时就绑定 task_id)。test_cancelling_a_run_stops_the_step_in_flight 偶发 flaky |
test_driver_plugins.py |
外部包用 entry-point agenthub.drivers 注册驱动即可被派活;坏插件不拖垮内置驱动;未知 driver 只让该任务失败 |
test_cli.py |
init/doctor/status/config/agent add/agent rotate 脱机可跑 |
test_snippets.py |
接入向导的字面量契约:app/connect/page.tsx 的 STEPS、AccessType、TARGETS 与 hub 侧片段 kinds 必须对得上(改向导文案会红);片段的文件名/占位符/next_steps;签发存档的 active 语义;并且扫 README.md 与 docs/*.md,不许把已删的接入机制当现状重新写回来 |
test_interop_nanobot.py |
对着真实 nanobot 包的 create_app() 跑 |
test_driver_nanobot_ws.py |
脚本化 nanobot WebSocket peer 锁协议:ready→message→delta/reasoning_delta/tool_hint/stream_end/turn_end、session_key→chat_id |
test_driver_openclaw.py |
脚本化 gateway peer 锁帧:connect.challenge→connect→req/res、流式 agent 事件、chat 终态、chat.abort 取消 |
驱动:mock、openai_compatible、nanobot、nanobot_ws、connector、openclaw,外加 entry-point group
agenthub.drivers。成熟度:connector / nanobot / nanobot_ws / openai_compatible 稳定,
mock 只用于打通链路(delay_s 模拟耗时),openclaw 是实验——上游 PyPI 包只发 CLI 二进制,
测试里起不了真网关,所以用脚本化 peer 锁协议;method_send / method_abort / session_key / protocol
都可在 Agent config 里覆盖,换网关版本不用改代码。
目录结构
backend/ FastAPI + SQLAlchemy(async) 控制面 + registry/gateway/tasks/deploy;CLI:agenthub
frontend/ Next 16 + React 19 + Tailwind 4 控制台(AgentTown 像素 HUD)
deploy/ Dockerfile.backend / .console / .nanobot + docker-compose.yml
nanobot-gateway/ nanobot 渠道 + 两容器样例(零桥接进程、零入站端口)
cli-bridge/ bridge.py + adapters/(codex / claude / workbuddy)
plugins/ dsh-agenthub(@nex/dsh-agenthub),不进后端构建
scripts/ dev.sh(一键起 hub+console)· attach.sh(按 task_id 进原生 CLI 会话)
data/ agenthub.db + hub-credentials.json(已 .gitignore,默认位置与启动目录无关)
docs/ PLAN.md(功能规划、API 契约、里程碑)+ AGENT_REGISTRATION.md(注册与身份规范)
soucecode/ 参考 clone(nanobot、agent-town),已 gitignore,不参与构建
常见坑
- 控制台一片
TypeError: Failed to fetch:请求没离开浏览器。curl -sI http://127.0.0.1:3100/ | grep -i content-security看connect-src里有没有 hub 的 origin (改过NEXT_PUBLIC_HUB_URL要重新pnpm build);再确认右上角 API Key 是当前data/hub-credentials.json里那把。 - 改了
NEXT_PUBLIC_HUB_URL没生效:它是构建期常量,dev要重启、build要重新构建。 pnpm start提示 standalone:生产跑node .next/standalone/server.js(先pnpm build)。- Agent 连不上(外拨):看它自己日志有没有
dialing …/已上线;hub 侧看GET /api/v1/gateway/status的 connections。凭证被轮换过就 401/403——agenthub agent rotate <name>重新签一把填回去。 POST /deploy/plan403this hub key is read-only:这把 key 是readscope。签发记录走record:true,必须 admin key。- 换目录启动后 Agent 全没了 / API Key 变了:
AGENTHUB_DATA_DIR被显式设成了相对路径。默认值锚定仓库根的data/。 - DSH 装完插件起不来:cordis.patch.yml 里那行占位
[]没删(两个根节点,YAML 直接失败); 或者 profile 是默认模板建的,只有dsh-base,没有常驻进程去拨 hub。 - 派活立刻失败
no live connector session:外拨 Agent 不在线,等它重连。 - nanobot 回 400
Only a single user message…/Only configured model …:这个 Agent 被登记成了openai_compatible,带上了 system 消息或写死的模型名。换成nanobotdriver:它把上下文折叠成一条 user 消息,并从/v1/models取模型。