嵌入指南

状态：Stable（Interaction 嵌入 @ ≥ 0.6.0） — Widget、短期 Access Token 与 Thread / Run 嵌入链路。Integration App 管理与 Operator API 见 Management（Stable）。请按部署版本验证字段和行为。

SDK：Next.js 开发模式（React Strict Mode）下 embed chat 需 @fellow.work/client ≥ 0.5.6，否则可能出现 run 已创建但不拉 SSE stream 的现象。

本指南面向 SDK Widget 嵌入（如官网客服、CRM 内嵌助手），架构如下：

浏览器
  │  FellowChatWidget + access_token
  ▼
你的后端  /api/.../access-token  (持 fkey_，仅服务端)
  │  POST /api/apps/token
  ▼
Fellow Gateway  (Integration App 鉴权 + CORS)
  │  Thread / Run
  ▼
runtimeUserId 的 harness

原则：fkey_ 只在你的服务端；浏览器只用短期 access_token。

1. Console · Integration App

本地开发额外添加：http://localhost:5174（或实际 dev 端口）。

专家白名单与 agent_ref

Console 配置 allowed_agents 后，创建 Run 时 Gateway 会校验专家是否在名单内。binding 指向默认 harness 用户时可用 agent_name；若 roster 里某 binding 绑定了其他 harness 用户，服务端应传 agent_ref（{runtime_user_id}/{agent_name}）。

import { createClient } from '@fellow.work/client';
import { formatIntegrationAgentRef } from '@fellow.work/client/contracts';

const client = createClient({
  baseUrl: process.env.FELLOW_API_URL!,
  apiKey: process.env.FELLOW_APP_API_KEY!,
});

// 默认专家（roster 内、同一 runtime 用户）
await client.run(threadId, { agentName: 'support' });

// 跨 harness 用户的 binding（须在 Console 白名单中）
await client.run(threadId, {
  agentRef: formatIntegrationAgentRef('usr_otherHarness', 'billing'),
});

Integration 鉴权下 GET /api/agents 只返回白名单内专家，并带 wire 字段 runtime_user_id，便于前端 picker 组装 agent_ref。

2. 环境变量（部署侧）

3. 后端 Token 交换

const { access_token } = await fellowClient.createAccessToken({
  origin: 'https://your-app.com',
  external_user_id: visitorId, // 同一访客复用 thread
});

将 access_token 返回给前端；不要返回 fkey_。

4. 前端挂载

import { FellowChatWidget } from '@fellow.work/client/react';

// baseUrl 来自服务端 token 交换响应中的 api_base_url（推荐），或直接传入 Gateway 地址
<FellowChatWidget
  baseUrl={apiBaseUrl}
  accessToken={token}
/>

Widget 默认在 Shadow DOM 内自带样式，不要在宿主页面 import @fellow.work/client/ui.css。

5. 部署前检查

• @fellow.work/client 已安装
• allowed_origins 含生产域名
• default_agent 在 runtime 用户下可用
• Gateway 公网可达
• 服务端 env 已配置 FELLOW_APP_API_KEY

6. Smoke Test

1. 打开页面 → Widget 按钮出现
2. 发消息 → Agent 正常回复
3. 刷新 → 同一 external_user_id 复用 thread
4. Network：access-token 200；Gateway 请求带 Bearer eyJ…
5. Console → 接入应用 → 对话列表可见 thread

常见问题

相关文档

• Client SDK
• 接入应用
• Console 运维