Client SDK

状态：Stable（Interaction 25-op @ ≥ 0.6.0） — @fellow.work/client 是 TypeScript / Web / Node 的参考实现；HTTP 以 Gateway 为准。Fellow StreamEvent SSE 为原生 wire；AG-UI 见 Interfaces（Stable @ ≥ 0.7.1）。

@fellow.work/client 是 Fellow 的 headless 接入 SDK：覆盖鉴权、Thread、Run 与 SSE 流式事件，并可适配为 AG-UI 语义。官方 Web 应用与第三方嵌入共用同一参考实现。

安装

npm install @fellow.work/client

需要 React Widget 时一并安装 react / react-dom。

服务端快速开始

在 Console 创建 Integration App，复制 API Key（fkey_…）。

import { createClient, EventType } from '@fellow.work/client';

const client = createClient({
  baseUrl: 'https://your-fellow-host/api',
  apiKey: process.env.FELLOW_APP_API_KEY!,
  appId: 'app_…', // 可选，多 App 时建议指定
});

const { id: threadId } = await client.createThread();
const { events } = await client.run(threadId, { content: 'Hello' }, { reconnect: true });

for await (const event of events) {
  if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
    process.stdout.write(event.delta);
  }
}

浏览器（Access Token）

切勿把 fkey_ 下发到浏览器。由你的后端换取短期 token：

// 后端
const { access_token } = await serverClient.createAccessToken({
  origin: 'https://your-app.com',
  external_user_id: userId,
});

// 前端
const client = createClient({
  baseUrl: 'https://your-fellow-host/api',
  accessToken: access_token,
});

React UI

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

<FellowChatWidget
  baseUrl="https://your-fellow-host/api"
  accessToken={token}
/>

页内 Lite 面板可设 styleIsolation（默认 Shadow DOM，无需 import CSS）：

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

<FellowChatLite
  baseUrl="https://your-fellow-host/api"
  accessToken={token}
  styleIsolation
/>

也可使用 FellowChat、useFellowConversation 构建自定义 UI。

核心 API

方法	说明
`createThread`	创建对话线程；可传 `externalUserId` 复用
`run`	发起 Run 并返回事件异步迭代器；可在客户端边界适配为 AG-UI
`streamEvents`	底层 SSE 订阅
`cancelRun` / `injectRun`	取消或注入跟进
`fetchPendingConsent` / `submitConsentDecision`	人机确认
`createAccessToken`	服务端换浏览器 token

REST 端点（Gateway）

方法	路径
`POST`	`/threads`
`POST`	`/threads/:id/runs`
`GET`	`/runs/:id/stream`
`POST`	`/runs/:id/inject`
`POST`	`/runs/:id/cancel`
`POST`	`/threads/:id/consent`

官方 Web / Desktop Workbench（client/packages/web）的数据面 HTTP 统一经 getGatewayClient()（createClient({ baseUrl: apiUrl('/api'), fetch: apiFetch })）。src/core/** 不直接调用 apiGet/apiPost；鉴权、本机 setup 状态、Desktop warmup 等仍走 lib/api.ts（monorepo：sdk/spec/operations/workbench-sdk-migration-plan.md）。

本地 monorepo 开发：client/packages/web 依赖 file:../../../sdk，改 SDK 后需在 sdk/ 执行 pnpm run build。

设计边界

SDK 覆盖 Chat/Run 及 Workbench 已接入的 catalog / files / connectors 等扩展面；Management operator 与 Console 运维 API 不挂 createClient 根（Desktop 运维见 Console）
SDK 只接意图与监督，不接硬实时控制环（飞控等留在设备侧）
Gateway 原生协议是 Fellow StreamEvent SSE；AG-UI 映射与 fellow.* 扩展位于客户端 / Interfaces adapter 边界

安装