Client SDK · 开发文档 · Fellow

状态：Preview（Interaction） — @fellow.work/client 是 TypeScript / Web / Node 的 Interaction 参考实现；HTTP 服务端事实以 Gateway 为准。Fellow StreamEvent SSE 是当前原生 wire，AG-UI 仅是客户端侧适配目标。

@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`

设计边界

SDK 覆盖 Chat/Run，不覆盖 workspace 全量 API、HARP 安装、Console 运维
SDK 只接意图与监督，不接硬实时控制环（飞控等留在设备侧）
Gateway 原生协议是 Fellow StreamEvent SSE；AG-UI 映射与 fellow.* 扩展位于客户端 / Interfaces adapter 边界