agent-chat-sdk

React 智能体对话 SDK。内置 lll-web-agent Runtime、基础 Tools、Skills 注册、MCP 联网、IndexedDB 多会话历史，以及悬浮窗和页面内嵌两种 UI。

责任边界

SDK 负责：

• Runtime 创建、流式对话和重建。
• 基础 Prompt、当前时间和窗口上下文 Tools。
• 模型选择、自定义模型和联网开关的本地状态。
• IndexedDB 会话历史、localStorage 降级和旧数据迁移。
• 悬浮球、可拖拽/缩放对话窗和页面内嵌对话。

宿主业务负责：

• 按登录用户单独获取 API Key，并通过 AgentProvider.apiKey 注入。
• 从业务接口获取完整 Agent 配置，并通过 agentConfig 原样传入。
• 注册业务 Tools；未配置后端人设 Prompt 时可提供兜底 System Prompt。
• 获取 MCP Token，并通过 AgentProvider 传入 MCP 地址和 Token。
• 提供语音输入和页面导航适配。
• 提供主题、品牌资产和业务快捷 Prompt。

SDK 不内置任何业务平台的模型、Skill 或 MCP URL。 提供 webSearchMcpUrl 后 SDK 展示联网搜索开关；只有同时提供 URL 和 webSearchMcpToken 时才会直连 MCP。SDK 不依赖 nginx 转发。

安装

ESM（推荐）

ESM 包名为 agent-chat-sdk：

npm install agent-chat-sdk

当前预发布版本仅发布这个 ESM 包，适用于使用 import 的现代浏览器工程。

import 'agent-chat-sdk/styles.css'

CommonJS（稳定版兼容包）

CommonJS 包名为 agent-chat-sdk-cjs，与 ESM 包独立安装：

npm install agent-chat-sdk-cjs

const { AgentProvider, AgentSurfaceRoot } = require('agent-chat-sdk-cjs')
require('agent-chat-sdk-cjs/styles.css')

agent-chat-sdk-cjs 仅随稳定版发布；Alpha 等实验版本不构建、也不发布 CommonJS 兼容包。

基本接入

import {
	AgentProvider,
	AgentSurfaceRoot,
	type AgentChatHostAdapter,
	type AgentConfig,
} from 'agent-chat-sdk'

export function AppAgent({
	agentConfig,
	userId,
	userApiKey,
	webSearchMcpToken,
}: {
	agentConfig: AgentConfig | null
	userId: string
	userApiKey: string
	webSearchMcpToken: string
}) {
	const host: AgentChatHostAdapter = {
		runtime: {
			systemPrompt: '你是业务智能助手。',
			tools: ({ navigate }) => createBusinessTools({ navigate }),
		},
		navigate: (path) => router.navigate(path),
	}

	return (
		<AgentProvider
			host={host}
			agentConfig={agentConfig}
			apiKey={userApiKey}
			baseUrl={runtimeConfig.baseUrl}
			webSearchMcpUrl={runtimeConfig.webSearchMcpUrl}
			webSearchMcpToken={webSearchMcpToken}
			ownerId={userId}
			showToolExecutionDetails={false}
		>
			<AppRoutes />
			<AgentSurfaceRoot />
		</AgentProvider>
	)
}

agentConfig 直接使用后端 Agent 配置接口 data[] 中的一项，不要在业务层 拆分、重命名或重新组装模型、Skill 和工具栏字段。接口数据变化时传入新的 agentConfig 对象，Provider 会同步更新模型、Skills、工具栏和人设。

showToolExecutionDetails 默认为 true，用户可以展开查看工具调用的入参与返回值； 业务不希望暴露执行明细时传入 false，工具名称和执行状态仍会正常展示。

模型与 Skills

• 自动模式通过 agentConfig.autoModelIds.default 到 modelDefinitions 查找模型；fast/default/premium 是自动决策模型池，后续 可按任务难度扩展路由策略。调用模型时使用定义中的 name。
• 关闭自动模式后，SDK 按 manualModelIds 的顺序到 modelDefinitions 查找模型， 再与本地自定义模型合并展示。缺失的数组字段按 [] 处理。
• 用户在 SDK 模型设置中输入的自定义模型按 ownerId 保存到 IndexedDB，必须填写模型名称、Key 和 URL；重新打开页面后仍可选择和删除。 后端 manualModelIds 引用的模型不可删除。
• 工具栏通过 toolbar[].skillIds 引用 Skill；SDK 先按 skillId 读取 skillRefs 中的覆写 Prompt 和运行参数，再读取 skillDefinitions 中的 名称、描述、原始 Prompt、标签、触发词和版本等基础信息。
• effectivePrompt 为最终生效 Prompt；缺失时依次回退到 promptOverride 和 skillDefinitions[].prompt。
• 当前模型和自定义模型由 AgentChatSettings 管理。
• 默认 createBrowserAgentChatSettings 将配置保存在当前浏览器。
• 选择“智能匹配”时向 Runtime 注册当前 Agent 的全部 Skills； 选择某一 Skill 时只注册该 Skill。

Agent 配置不得承载 API Key。SDK 保留 modelDefinitions.endpoint 元数据但不将 它作为请求地址；自动模型和手动模型的 Key、URL 仍由宿主分别通过 AgentProvider.apiKey、AgentProvider.baseUrl 传入。只有用户自行添加的模型会 将对应 Key、URL 按用户保存在浏览器 IndexedDB，不会进入 localStorage。任一值 为空时 SDK 不创建对话 Runtime；值变化时会重建 Runtime。

内置结构化交互

SDK 默认注册 requestUserInputAdvanced，并把它的通用使用规则 自动与 runtime.systemPrompt 合并。业务方不需要重复定义 Tool 或 Prompt。 当 includeBuiltinTools: false 时，内置 Tool 及对应 Prompt 同时停用。 用户明确要求生成 HTML、Markdown/MD 或 TXT 文件时，SDK 会通过 create-text-file 创建真实文件，再通过 showGeneratedFile 展示文件卡片。 未配置 COS 时文件保存在当前浏览器；配置 COS 时沿用生成产物上传链路。

已内置的 UI 模式：

• id-select：{ id, label } 单选。
• plain-select：纯文本单选。
• action-select：跳转或关闭操作。
• form：单个结构化表单。
• batch：多个 select/radio 字段一次提交。
• file：HTML、PPT/PPTX、PDF、Word、Excel 和 Markdown 等文件产物卡片。

file 模式不会阻塞对话。SDK 可使用 downloadUrl 直接下载； 需要鉴权的下载、Markdown/Office 预览和上传到业务系统，由宿主回调承接：

const host: AgentChatHostAdapter = {
	// ...
	artifacts: {
		download: (file) => downloadWithAuth(file.id),
		preview: (file) => openBusinessPreview(file.id),
		upload: (file) => uploadToBusiness(file.id),
	},
}

消息历史只存储 AgentFileArtifact 的轻量元数据和资源 ID/URL， 不应传入 base64、Blob 或完整文件内容。

内嵌对话页

Provider 必须放在悬浮层和内嵌页面的共同上层：

<AgentProvider
	host={host}
	agentConfig={agentConfig}
	apiKey={userApiKey}
	baseUrl={runtimeConfig.baseUrl}
	ownerId={userId}
>
	<Routes>
		<Route path="/chat" element={<AgentEmbeddedChat />} />
		<Route path="*" element={<BusinessPages />} />
	</Routes>
	<AgentSurfaceRoot floating={false} />
</AgentProvider>

业务页只需渲染 AgentEmbeddedChat，无需传路由或形态参数。 仅使用网页内嵌对话时，在 AgentSurfaceRoot 上传入 floating={false} 可完全不挂载悬浮球和悬浮对话窗。默认值为 true；默认情况下， 进入内嵌页后悬浮球和弹窗自动隐藏，离开后自动恢复。两种形态共享 消息、流式状态、当前会话和 IndexedDB 历史。

AgentEmbeddedChat 不开放 width、height、className 或 style 等视觉参数，AgentRoot / AgentSurfaceRoot 也不开放悬浮窗宽高参数。 内嵌页和悬浮窗的尺寸、间距、边框等样式统一由主题生成器管理，避免 JSX 局部覆盖与主题 CSS 产生两套配置来源。

主题与品牌

const host: AgentChatHostAdapter = {
	// ...
	ui: {
		assistantName: 'My Assistant',
		idleSubtitle: '随时为您提供帮助',
		welcomeMessage: '有什么需要帮忙的？',
		branding: {
			logoSrc: '/assets/agent-logo.svg',
			loadingIndicatorSrc: '/assets/agent-loading.gif',
			sendIconSrc: '/assets/agent-send.svg',
		},
		theme: {
			primaryColor: '#2457ff',
		},
	},
}

host.ui.theme 只提供 primaryColor 快捷配置。复杂视觉样式请在 Demo 的“主题生成器”中调整并下载完整 CSS，用生成文件替换 agent-chat-sdk/styles.css。全部样式变量均使用 --agent-* 命名空间， 不依赖宿主的全局主题变量。悬浮窗宽高使用主题项 floatingPanelWidth / floatingPanelHeight，内嵌页尺寸使用 embeddedPanelWidth / embeddedPanelHeight。外部图片资源仍通过 host.ui.branding 注入。

语音输入

SDK 只定义最小语音协议，不内置任何 ASR 供应商：

<AgentProvider
	host={host}
	agentConfig={agentConfig}
	apiKey={userApiKey}
	baseUrl={runtimeConfig.baseUrl}
	ownerId={userId}
	speechInputComponent={BusinessSpeechInput}
>
	{children}
</AgentProvider>

BusinessSpeechInput 需要实现 AgentSpeechInputComponent 协议。

消息内容区自定义头部

业务可在消息列表上方注入一个固定的自定义区域：

const BusinessMessageContentHeader: AgentMessageContentHeaderComponent = ({
	activeSessionId,
	messages,
}) => (
	<BusinessContextBar
		sessionId={activeSessionId}
		messages={messages}
		messageCount={messages.length}
	/>
)

<AgentProvider
	host={host}
	agentConfig={agentConfig}
	apiKey={userApiKey}
	baseUrl={runtimeConfig.baseUrl}
	messageContentHeaderComponent={BusinessMessageContentHeader}
>
	{children}
</AgentProvider>

SDK 只向头部组件传入当前 activeSessionId 和消息窗口实际展示的全部 messages，暂不暴露其他会话和输入框操作能力。头部组件宽度自动继承消息内容区， 按自身内容占高；消息列表使用剩余高度并独立滚动。

存储隔离

namespace 用于隔离不同业务系统的模型配置、联网开关、悬浮球位置和 默认会话库。ownerId 用于隔离同一业务内的用户会话。生产接入时建议 两者都显式传入。

开发验证

独立启动 SDK 验收页：

pnpm --filter agent-chat-sdk dev

默认地址为 http://localhost:3100。演示页必须使用真实的本地模型 URL 和 API Key，请求会完整经过 lll-web-agent Runtime、 SDK Tool 注册层和业务 Tool execute。

演示页可验证：

• 业务 Models、Skills 和 Prompt 的异步加载。
• 基础 Tools 与业务 Tools 的合并注册和真实执行。
• 悬浮球、对话窗拖拽/缩放、页面内嵌形态与会话共享。
• 主题色、面板圆角、模型与 Web Search MCP 地址入参。

复制 .env.example 为 .env.local 后配置：

AGENT_DEMO_MODEL_API_KEY=your-local-only-key
AGENT_DEMO_MODEL_URL=https://example.com/v1/chat/completions
AGENT_DEMO_WEB_SEARCH_MCP_URL=https://example.com/mcp
AGENT_DEMO_WEB_SEARCH_MCP_TOKEN=your-local-only-mcp-token

.env.local 已被仓库忽略，参数只用于本地演示构建。也可使用 AGENT_DEMO_ENV_FILE=/absolute/path/to/file pnpm --filter agent-chat-sdk dev 指定其他配置文件。

模型列表与连接参数职责分开：Demo 在 demo/mock/agent-config.json 中按 /api/agent/config/list 的返回结构 模拟 Models、Skills 和 Toolbar；.env.local 只提供本机 API Key、 LLM URL、MCP URL 和 MCP Token。SDK 创建 Runtime 时再组合， Key 和 URL 都不会进入模型列表或模型选择的本地存储。 MCP URL 和 Token 也由宿主单独传入，Token 仅用于 SDK 创建 MCP 连接时的 Bearer 鉴权。

pnpm --filter agent-chat-sdk lint
pnpm --filter agent-chat-sdk typecheck
pnpm --filter agent-chat-sdk test
pnpm --filter agent-chat-sdk build

发布 Alpha

发布凭证使用仅授权 agent-chat-sdk 的 Granular Access Token。Token 保存在 macOS 钥匙串的 agent-chat-sdk-npm-token 条目中，不写入仓库；项目 .npmrc 只引用运行时的 ${NPM_TOKEN}。

pnpm --filter agent-chat-sdk release:alpha

脚本会从钥匙串读取 Token，校验版本号包含 -alpha.，执行完整构建与检查， 并仅更新 npm 的 alpha 标签，不修改 latest。

SDK 当前为 Alpha API，在 0.2.x 稳定前可能调整宿主协议。

发布稳定版

稳定版使用同一版本号同时发布两个包：

• agent-chat-sdk：ESM 主包，更新 npm latest 标签。
• agent-chat-sdk-cjs：CommonJS 兼容包，仅稳定版发布。

pnpm --filter agent-chat-sdk release:stable

脚本会在发布前完成 ESM/CJS 构建、主题 CSS 一致性校验和全量测试。