接入应用 · 开发文档 · Fellow

状态：Stable（Management operator + Interaction 接入 @ ≥ 0.6.0） — App、API Key、Scope 与浏览器 Token 交换。具体字段、默认 Scope 与 Console 操作以部署版本为准。

接入应用（Integration App） 是智能体应用在实例上的治理身份：独立 App ID、API Key、Scope 与审计边界。它登记的是用 Fellow SDK 构建的软件，不是可安装宿主应用。

对外词	说明
智能体应用	用 Fellow SDK 构建、面向最终用户的软件产品
接入应用	该产品在本实例上的登记与凭证（本文）
宿主应用	按 HARP 安装的独立软件；见 Applications 与 HARP

与 HARP 安装包、Console 运维 Token、用户 Session 严格区分。Console 导航为应用；本页是该应用的授权与凭证，不是第二种产品。

核心概念

概念	前缀	说明
接入应用	`app_`	智能体应用的公开标识，可写入 SDK
API Key	`fkey_`	私密凭证，创建时展示一次
external_user_id	—	第三方用户标识，用于 thread 分区（非 Fellow 账号）
专家 binding	—	`agent_name` + harness `runtime_user_id`；Run 用 `agent_ref` 或白名单内的 `agent_name`

架构

第三方后端  Authorization: Bearer fkey_…
        │
        ▼
Gateway app-auth → integrationApp
        │
        ▼
Thread（App + external_user_id）/ Run（专家 → harnessUserId）

Embed 创建的 thread 不会出现在 Web Inbox（integrationAppId IS NULL 过滤）。

Scopes

Scope	能力
`threads:write`	创建 thread、上传文件
`threads:read`	读 thread、artifact、workspace 文件
`runs:write`	创建 run、cancel、inject、consent
`runs:read`	stream、run 状态与事件
`consent:read` / `consent:write`	人机确认

默认授予上述 scope。/api/workspaces CRUD 与 /api/console/* 不在 Integration App 开放范围内。

Scope 枚举与 SDK INTEGRATION_APP_SCOPES（@fellow.work/client/contracts）一致。

专家白名单（allowed_agents）

Console 可为 App 配置 allowed_agents：每项含 agent_name 与 harness runtime_user_id（Console 保存时会写全）、可选 label、default。

配置	Run 行为
未配置 / 空数组	legacy：App 内部 storage harness 下任意 agent slug；仍可用 `default_agent`
非空 roster	仅 roster 内专家；未传 `agent_name` 时用 default binding
越权 slug	`403` · `agent.not_allowed`

SDK 创建 Run：

agent_name — 同一 runtimeUserId 下的专家 slug（roster 校验）。
agent_ref — {runtime_user_id}/{agent_name}，用于跨 harness 账号 binding（Integration App roster 须包含该 binding）。

Integration 鉴权下 GET /api/agents 仅返回 roster 内专家，并带 runtime_user_id（wire）供 picker 使用。

external_user_id 仍只标识第三方访客的 thread 分区，不是 harness 账号。

Console 管理

在 接入应用 页面：

创建 App / 轮换 Key
配置 allowed_origins（浏览器 embed CORS）
设置 allowed_agents 白名单与 default 专家（按 harness 账号勾选）
查看用量与 embed 对话列表

Access Token

POST /api/apps/token
Authorization: Bearer fkey_…
{ "origin": "https://your-app.com", "external_user_id": "user-123" }

响应：{ access_token, token_type, expires_in, app_id }

多用户

同一 (integrationAppId, external_user_id) 会自动复用 active thread（归属 App + 访客，不随 Run 所选专家或主 Runtime 变化），适合 CRM 详情页等长期嵌入场景。