OpenAgentPack Kit
SDK

Client 请求

createKitClient 的配置、身份、数据面 API、附件与错误处理

显式接入自己的后端

新项目使用 createKitClient({ request, operations }) 配置实际接口;这是 Web 示例使用的同一入口。 operations 表示可选的接口调用映射,不是后端内部操作系统。每项包含 buildRequest 和 mapResponse, Request 负责 HTTP 与错误映射;Client 复用现有 DTO 和方法签名。supports(name) 用于能力判断, 缺少的配置不会自动请求 Kit Server。旧 { baseUrl } 方式仍保留 Kit 固定路由兼容。

以下示例采用另一组 URL、POST 搜索与 { result } 响应;请求头、路径和参数由应用配置:

import { type ClientOperations, createKitClient } from "@openagentpack/kit-sdk/providers/kit";
import type { RequestClient } from "@openagentpack/kit-sdk/request";

// 只配置后端支持的功能。未配置的操作不会调用 Kit 路由。
export function createDataClient(request: RequestClient) {
	const result = async <T>(response: Response): Promise<T> => (await response.json()).result;
	const json = (value: unknown) => ({
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify(value),
	});
	const operations: ClientOperations = {
		agents: { buildRequest: () => ({ path: "/catalog" }), mapResponse: result },
		agent: { buildRequest: ([slug]) => ({ path: `/catalog/${encodeURIComponent(slug)}` }), mapResponse: result },
		sessionAgents: { buildRequest: () => ({ path: "/conversation-groups" }), mapResponse: result },
		sessions: {
			buildRequest: ([query]) => ({ path: "/conversations/search", init: json(query ?? {}) }),
			mapResponse: result,
		},
		session: { buildRequest: ([id]) => ({ path: `/conversations/${encodeURIComponent(id)}` }), mapResponse: result },
		createSession: { buildRequest: ([input]) => ({ path: "/conversations", init: json(input) }), mapResponse: result },
		renameSession: {
			buildRequest: ([id, title]) => ({
				path: `/conversations/${encodeURIComponent(id)}/title`,
				init: json({ title }),
			}),
			mapResponse: result,
		},
		sessionPlan: {
			buildRequest: ([id, action]) => ({
				path: `/conversations/${encodeURIComponent(id)}/preview`,
				init: json({ action }),
			}),
			mapResponse: result,
		},
		archiveSession: {
			buildRequest: ([id, confirmation]) => ({
				path: `/conversations/${encodeURIComponent(id)}/archive`,
				init: json(confirmation),
			}),
			mapResponse: result,
		},
		deleteSession: {
			buildRequest: ([id, confirmation]) => ({
				path: `/conversations/${encodeURIComponent(id)}/remove`,
				init: json(confirmation),
			}),
			mapResponse: result,
		},
		uploadFile: {
			buildRequest: ([file]) => {
				const form = new FormData();
				form.append("attachment", new Blob([file.bytes as BlobPart], { type: file.mimeType }), file.name);
				return { path: "/attachments", init: { method: "POST", body: form } };
			},
			mapResponse: result,
		},
		fileStatus: {
			buildRequest: ([id]) => ({ path: `/attachments/${encodeURIComponent(id)}/status` }),
			mapResponse: result,
		},
		downloadFile: {
			buildRequest: ([id, input]) => ({
				path: `/attachments/${encodeURIComponent(id)}/content?conversation=${encodeURIComponent(input?.sessionId ?? "")}`,
			}),
			mapResponse: (response) => response,
		},
		usageLimits: { buildRequest: () => ({ path: "/account/limits" }), mapResponse: result },
	};
	return createKitClient({ request, operations });
}

目录、上传、首次发送及产物组件绑定见 组件交互与后端调用。

createKitClient 来自 @openagentpack/kit-sdk/providers/kit,提供可配置的数据面调用;{ baseUrl } 兼容模式封装 Kit Server API, 可独立于 React 和 UI 组件使用。它负责请求与响应转换;对话订阅和发送编排由 useChat 或 Controller 负责。

底层 HTTP 统一由 Request 执行,SSE 字节处理由 Stream 执行。Client 使用现有数据方法与 DTO;独立 Request 不包含 这些业务方法、Kit 协议头和控制帧策略。

何时使用

  • 在 React 之外调用 Kit Server:脚本、测试或自行编排订阅与发送的宿主。
  • 需要 hooks 未覆盖的数据面方法:事件历史、归档删除计划、文件上传下载。
  • 需要注入身份头、替换 fetch 实现,或排查协议版本与请求错误。

使用说明

初始化与运行时配置

configBaseUrl 由部署配置或宿主注入,指向提供 /api/config 的服务,不能假设它与页面同源。 先读取配置并校验协议主版本,再使用返回的 apiBaseUrl 创建业务 Client。

import { createKitClient, type KitClientOptions } from "@openagentpack/kit-sdk/providers/kit";

export async function createConfiguredClient(
  configBaseUrl: string,
  headersFor: (apiBaseUrl: string) => KitClientOptions["headers"],
) {
  // 公开配置请求不携带身份;只有确认最终目标后才选择该目标的令牌。
  const config = await createKitClient({ baseUrl: configBaseUrl }).config();
  const baseUrl = config.apiBaseUrl || configBaseUrl;
  return createKitClient({
    // 空串表示沿用配置服务的来源,跨域部署时不能退回页面来源。
    baseUrl,
    headers: headersFor(baseUrl),
  });
}

Client 自动添加 x-kit-protocol-version。当前 Session 流、消息和审批使用 Kit 协议 2.x, 主版本不兼容应停止初始化并同步升级前后端。

成员登录与恢复

体验页在 createMemberAuthController 配置中传入 createChatProvider(request), 通过公开 标准事件工厂 填写业务接口。 Controller 提供的 RequestClient 绑定本次登录的固定应用身份;返回的 Provider 出现在 useMemberAuth(controller).chatProvider,页面显式交给 useChat。 同一身份复用同一实例;退出、到期、HTTP/SSE 鉴权失败使旧 Provider 失效。 该配置可选,已有默认 Client 接入保持兼容。

默认 Kit Server 必须登录。client.auth.login({username,password}) 获取 8 小时有效的成员 令牌;client.auth.me() 校验当前身份;client.auth.logout() 撤销当前登录。直接调用这些 方法不会替你存储令牌或清理 UI,默认体验页使用 createMemberAuthController + useMemberAuth 管理整个身份生命周期。

宿主提供按完整 apiBaseUrl(包括路径前缀)隔离的 MemberSessionStorage;只保存 {access_token, expires_at},不保存密码。默认 Web 使用 sessionStorage。配置缺少 auth 时 按 member 模式处理,不能静默开放匿名访问。以下示例的 Controller 应在启动时创建一次, storage 由宿主实现。示例代码与 Skill 同源生成。

import {
	createMemberAuthController,
	type MemberAuthController,
	type MemberAuthOptions,
} from "@openagentpack/kit-sdk/auth";
import { useMemberAuth } from "@openagentpack/kit-sdk/auth/hooks";
import { KitProvider } from "@openagentpack/kit-sdk/providers/kit/react";
import type { FormEvent, ReactNode } from "react";

// 公开配置解析出最终 API URL 后调用一次。宿主存储按带路径前缀的完整 URL 隔离,
// 只保存会话令牌及有效期。
export function createLogin(options: MemberAuthOptions) {
	return createMemberAuthController(options);
}

export function MemberRoot({ controller, children }: { controller: MemberAuthController; children: ReactNode }) {
	const auth = useMemberAuth(controller);
	if (auth.status === "checking") return <p>正在恢复登录…</p>;
	if (auth.status === "error") {
		return (
			<section>
				<p role="alert">{auth.error}</p>
				<button type="button" onClick={() => void auth.retry()}>
					重试
				</button>
			</section>
		);
	}
	if (!auth.client) {
		const submit = async (event: FormEvent<HTMLFormElement>) => {
			event.preventDefault();
			const form = event.currentTarget;
			const data = new FormData(form);
			try {
				await auth.login({
					username: String(data.get("username") ?? ""),
					password: String(data.get("password") ?? ""),
				});
			} catch {
				// 控制器在快照中提供可安全展示的错误。
			} finally {
				const password = form.elements.namedItem("password");
				if (password instanceof HTMLInputElement) password.value = "";
			}
		};
		return (
			<form onSubmit={submit}>
				<label>
					用户名 <input name="username" autoComplete="username" required disabled={auth.pending} />
				</label>
				<label>
					密码{" "}
					<input name="password" type="password" autoComplete="current-password" required disabled={auth.pending} />
				</label>
				{auth.error && <p role="alert">{auth.error}</p>}
				<button type="submit" disabled={auth.pending}>
					登录
				</button>
			</form>
		);
	}
	return (
		<KitProvider key={auth.generation} client={auth.client}>
			<header>
				{auth.member?.display_name}
				{auth.member && (
					<button type="button" onClick={() => void auth.logout()}>
						退出登录
					</button>
				)}
			</header>
			{children}
		</KitProvider>
	);
}

status 包含 checking、signed-out、signed-in、anonymous 和 error。只在获得 client 后挂载 业务页面,并以 generation 为 key 重建页面。退出、过期、HTTP 401 或 SSE unauthorized 会取消旧身份请求和订阅;网络恢复失败 / 退出撤销失败显示重试,403 配额错误不会误退出。 React hook 管理 start / dispose;非 React 宿主自行调用 start、subscribe 并在卸载时 dispose。 dispose 取消客户端工作但不撤销登录;显式 logout 才撤销服务端令牌。 取消覆盖等待响应头与读取正文两个阶段:即使自定义 fetchImpl 忽略 signal,旧请求也会 结束,迟到响应的正文会被取消。这里不会额外增加网络超时或自动重试。

连接 React

初始化完成后,将同一个 Client 实例传给 KitProvider,不要在每次渲染时重新创建实例。 这里的 children 是你的业务页面,使用默认 Client 的 Hooks 在此 Provider 内运行。 自建后端可通过 ChatProvider 直接接入 useChat, 无需创建完整 KitClient,也无需 KitProvider;本页 Client 方法仍访问 Kit Server。

import type { ReactNode } from "react";
import type { KitClient } from "@openagentpack/kit-sdk/providers/kit";
import { KitProvider } from "@openagentpack/kit-sdk/providers/kit/react";

export function KitRoot({ client, children }: { client: KitClient; children: ReactNode }) {
  return <KitProvider client={client}>{children}</KitProvider>;
}

上传与挂载附件

上传成功只获得文件引用,等 fileStatus 返回 available: true 后再提交。默认 Kit Server 的体验会话支持两种用法:

  • 新建会话:将文件引用作为 files 传给 client.createSession({ agentSlug, files }), 服务端会在返回会话前挂载文件。
  • 已有会话:将文件引用作为 attachments 传给 chat.send(text, { attachments }), 服务端先挂载再发送;发送失败时尝试卸载本次新增的挂载。

可以用 useAttachments 统一上传和扫描,用 useComposer 处理首次发送与已有会话的发送。 见组件交互与后端调用。

文件选择、粘贴、移除和上传状态由调用方组合 Sender 与 Attachments 管理。 使用 await client.downloadFile(fileId, { sessionId }) 下载 Artifact,再由宿主保存 Response 中的字节;本人上传文件可以省略 sessionId。服务端检查文件归属,只允许挂载本人上传。 旧数据库升级时,会从历史会话挂载索引补齐唯一原身份的文件归属;存在跨身份歧义或没有 索引证据的旧文件需要重新上传。已有匿名附件不会自动归到新成员。 fileDownloadUrl() 只生成地址,不附加身份头;成员登录下不能把它直接当作可用的裸下载链接。 Provider 的预签名 URL 不下发给浏览器。

代码演示

上传状态、历史附件和宿主能力

上传受理后通过 fileStatus(fileId) 读取扫描状态;失败、超时或 available=false 时保留草稿并提供重试,服务端仍执行扫描与归属校验。轮询复用 packages/sdk/src/files/attachments.ts,页面通过公开的 useAttachments 管理上传状态。 历史会话的业务接口可返回 message_files, 通过 chat.setMessageFiles(entries) 补充附件气泡;不改变 SessionEvent 合同。

API导入入口用途
useAttachments(options?)@openagentpack/kit-sdk/files/hooks管理上传、扫描轮询、失败与待发送附件状态
resolveApiBaseUrl(queryApi?, config?)@openagentpack/kit-sdk/config按宿主注入、查询参数和运行时配置解析后端地址
uploadSizeRejectionReason(size) / uploadTypeRejectionReason(name)@openagentpack/kit-sdk/protocol上传前拒绝原因;最终限制由后端执行
sleep(ms, signal?)@openagentpack/kit-sdk/chat示例业务的可取消等待,不包含自动写请求重试策略

文件选择、保存、剪贴板和主题能力由应用提供。Web 示例在 apps/web/src/lib/host.ts 通过 resolveHostCapabilities() 读取壳注入与浏览器兜底实现,再用 createArtifactHost() 装配产物预览与保存能力。这些函数属于应用接入层;自建项目按 @openagentpack/kit-sdk/files 的 ArtifactHost 合同提供实现,传给 @openagentpack/kit-sdk/files/hooks 的 useArtifactActions({ host, ... })。

订阅与游标续传

client.stream(订阅与游标续传)

三个场景观察同一订阅入口:首订按 reset → event* → ready 重建,after=1:8 无 reset 续传, 游标失效触发 reset。不要写成 await client.stream(...); await client.sendMessage(...): 这会一直等到连接关闭;需要发送与订阅协同时,用 Controller。

API

createKitClient(options)

选项类型作用
baseUrlstringKit Server 地址;所有路径在此地址后拼接
headers() => Record<string, string> | Promise<Record<string, string>>每次 HTTP 请求和 SSE 建连时读取身份头
fetchImpltypeof fetch注入宿主 fetch、Cookie 策略或测试替身;默认 globalThis.fetch

成员令牌或 JWT 模式下,headers 可返回 { Authorization: "Bearer <Kit 身份令牌>" };它是终端用户 访问 Kit 的身份,不能填入 BAILIAN_API_KEY 或 Provider 凭据。跨域 Cookie 身份需要按部署 要求注入携带 credentials: "include" 的 fetch,并配置服务端 CORS;Client 不自动开启它。

数据面方法

方法用途
config()读取配置并检查协议主版本
auth.login(body) / auth.me() / auth.logout()成员登录、恢复当前身份、撤销当前令牌
agents() / agent(slug)查询当前身份可见的 Agent 目录与详情
plaza({ category?, q? })查询广场、精选与热门条目、分类和统计
quota() / quotaRequests()查询当前身份的月度用量、额度及提额申请历史
createQuotaRequest({ requestedCredits, reason? })显式提交提额申请;审批与额度生效需继续查询
sessions({ agentSlug?, limit?, pageToken? })查询会话索引,返回 sessions 和 nextPageToken
createSession({ agentSlug, title?, files? })新建会话,可在创建时挂载已上传附件
session(id) / renameSession(id, title)查询详情、修改标题
sendMessage(id, { text, client_message_id? })提交消息;返回提交结果,不等待完整回答
interrupt(id)请求停止 Provider 执行
toolApprovals(id) / submitToolApproval(id, decision)查询待办、提交单项审批决定
events(id, { afterId?, limit?, pageToken? })读取事件历史,返回 data 和 next_page_token
stream(id, options)订阅一次 SSE 连接;回调与游标见下方,自动重连由 Controller 负责
sessionPlan(id, action)获取 archive / delete 的计划与确认令牌
archiveSession(id, confirmation) / deleteSession(id, confirmation)显式确认后携带 plan_id、confirm_token 执行
uploadFile(file) / downloadFile(fileId, { sessionId?, signal? })带当前身份上传 / 下载文件;下载返回 Response
fileStatus(fileId)读取 { file_id, status, available },available=true 后才提交附件
usageLimits({ days? }, signal?)本地成员日/月 Token 和执行时长限额;非本地成员明确返回 null
fileDownloadUrl(fileId)仅生成代理 URL,不执行鉴权请求

直接调用 sendMessage 不会替你建立前端订阅或管理乐观消息。对话页面优先使用 useChat, 以便在订阅就绪后发送、维护输入状态并处理重连。Kit 管理端的 AdminClient、成员用量和 Operation 恢复属于 Console 应用接入层,不作为 SDK 导出;前端调用状态可复用 通用调用状态。管理身份与体验页成员身份独立,接口合同见接口总览。

stream(id, options)

订阅一次 SSE 连接:字节分帧由 Stream 完成,这里在原始帧之上交付 Kit 协议头、 控制帧与有效帧超时。stream 不自动重连,也不维护消息列表。

属性说明类型默认值
after续传上次成功消费的传输游标,视为不透明字符串string | null-
signal取消订阅;调用方处理取消产生的异常AbortSignal-
onEvent接收 SDK SessionEvent 累计快照及本次传输游标(event, cursor?) => void-
onReset开始重建事件集合() => void-
onReady回放完成({ sessionId, replayed, cursor? }) => void-
onDone流正常关闭,不替代业务执行状态({ status, lastEventId }) => void-
onPing收到保活时间戳(t: number) => void-

快照与游标

  • Kit Server 默认先订阅上游并缓冲实时事件,再回放完整分页历史:首次重建按 reset → event* → ready 交付,core 在 ready 原子切换历史并保留未确认的本地乐观消息。
  • 同一 event_id 的后续帧可能是更新后的完整快照:交给 Store 更新快照再渲染,不能见重复 ID 就丢弃,也不能重复追加累计文本。
  • 业务 event_id 与 SSE id 是两个字段:after 用 SSE id 续传,历史 API 的 afterId 用 业务事件游标。
  • 一轮结束以主会话 idle 且无 requires_action 确认;等待审批、子线程结束、单条消息完成或 浏览器断线都不代表 Turn 结束,UI 以归并后的 phase / turnRunning 为准。
  • Controller 对网络错误、意外 EOF、45 秒无有效帧与可重试流错误做带游标退避重连,游标失效走 reset 重建;认证、协议冲突等不可重试错误停止恢复。重连只恢复订阅,不重发用户消息与审批。
  • connection === "connected" 只描述浏览器到 Kit 的连接;上游恢复期间中间文本可能暂时变化, 最终以 Provider 完成快照收敛,不承诺逐 token 无损回放。

详细事件合同见仓库 docs/protocol.md。

错误与确认

HTTP 错误响应和流内错误使用 KitError(从 @openagentpack/kit-sdk/protocol 导入),含 code、message、status 和 retryable;网络层也可能抛出原生异常。调用方应捕获错误, 保留草稿并展示失败原因。retryable 不表示可以自动重发消息或审批。

归档、删除必须先取得 plan,向用户展示计划,再经 AlertDialog 显式确认后执行。 不要把 sessionPlan() 与 deleteSession() 串成无人工确认的自动调用。详细状态码与 确认约束见接口总览。

本地成员会话删除由服务端协调停止、用量采集和持久化。错误详情可区分停止、采集、删除与 本地收尾阶段;用量保存失败时会话保留,执行可能已经停止。deletion_uncertain=true 表示远端删除结果待核实,不能当作已经失败而继续发送;提示用户重新获取计划并确认重试。 该保护跨重试和服务重启保留。已发出中断但删除未完成时,也不能凭一次 idle 查询恢复发送; 删除报网络错误后 GET 仍存在不能证明旧 DELETE 已被拒绝。 该机制不新增 ChatProvider 方法,也不要求组件自己保存统计。

本页目录