agent-chat-sdk

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

责任边界

SDK 负责：

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

宿主业务负责：

• 按登录用户单独获取 API Key，并通过 AgentProvider.apiKey 注入。
• 异步提供模型清单和 Skills 清单。
• 注册业务级 System Prompt 和 Tools。
• 提供 MCP 联网地址、请求头、语音输入和页面导航适配。
• 提供主题、品牌资产和业务快捷 Prompt。

SDK 不内置任何业务平台的模型、Skill 或 MCP URL。

安装

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,
	createBrowserAgentChatSettings,
	type AgentChatHostAdapter,
} from 'agent-chat-sdk'

const settings = createBrowserAgentChatSettings({
	namespace: 'my-product-agent',
	initialModel: {
		provider: 'openai',
		model: runtimeConfig.model,
		url: runtimeConfig.baseUrl,
	},
})

const host: AgentChatHostAdapter = {
	namespace: 'my-product-agent',
	settings,
	runtime: {
		systemPrompt: () => fetchBusinessSystemPrompt(),
		tools: ({ navigate }) => createBusinessTools({ navigate }),
	},
	models: {
		list: async () =>
			(await fetchAgentModels()).map((item) => ({
				id: item.modelCode,
				label: item.modelName,
				provider: item.provider,
				url: item.endpoint,
			})),
	},
	skills: {
		list: async () =>
			(await fetchAgentSkills()).map((item) => ({
				name: item.code,
				description: item.name,
				instructions: item.prompt,
				version: item.version,
				allowedTools: item.allowedTools,
			})),
	},
	prompts: {
		list: () => businessPromptPresets,
	},
	webSearch: {
		endpoint: () => runtimeConfig.webSearchMcpUrl,
		headers: () => ({ Authorization: `Bearer ${runtimeConfig.token}` }),
	},
	navigate: (path) => router.navigate(path),
}

export function AppAgent({
	userId,
	userApiKey,
}: {
	userId: string
	userApiKey: string
}) {
	return (
		<AgentProvider host={host} apiKey={userApiKey} ownerId={userId}>
			<AppRoutes />
			<AgentSurfaceRoot />
		</AgentProvider>
	)
}

models.list()、skills.list() 和 prompts.list() 由 Provider 统一加载并共享， 不会由面板和设置弹窗重复请求。模型或 Skills 数据源发生变化时， 可通过 Provider 的 subscribe(listener) 通知 SDK 重新加载。

模型与 Skills

• 业务接口只负责返回可用模型清单。
• 当前模型和自定义模型由 AgentChatSettings 管理。
• 默认 createBrowserAgentChatSettings 将配置保存在当前浏览器。
• Skills 来自业务接口，选择“智能匹配”时向 Runtime 注册全部 Skills； 选择某一 Skill 时只注册该 Skill。

models.list() 不得返回 API Key。Key 由宿主的用户授权接口 单独获取，通过 AgentProvider.apiKey 传入，不会进入模型选择或 localStorage。Key 变化时 Provider 会重建 Runtime。

内置结构化交互

SDK 默认注册 requestUserInputAdvanced，并把它的通用使用规则 自动与 runtime.systemPrompt 合并。业务方不需要重复定义 Tool 或 Prompt。 当 includeBuiltinTools: false 时，内置 Tool 及对应 Prompt 同时停用。

已内置的 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} apiKey={userApiKey} ownerId={userId}>
	<Routes>
		<Route path="/chat" element={<AgentEmbeddedChat />} />
		<Route path="*" element={<BusinessPages />} />
	</Routes>
	<AgentSurfaceRoot />
</AgentProvider>

业务页只需渲染 AgentEmbeddedChat，无需传路由或形态参数。 进入内嵌页后悬浮球和弹窗自动隐藏，离开后自动恢复。两种形态共享 消息、流式状态、当前会话和 IndexedDB 历史。

主题与品牌

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-* 命名空间， 不依赖宿主的全局主题变量。外部图片资源仍通过 host.ui.branding 注入。

语音输入

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

<AgentProvider
	host={host}
	apiKey={userApiKey}
	ownerId={userId}
	speechInputComponent={BusinessSpeechInput}
>
	{children}
</AgentProvider>

BusinessSpeechInput 需要实现 AgentSpeechInputComponent 协议。

消息内容区自定义头部

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

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

<AgentProvider
	host={host}
	apiKey={userApiKey}
	messageContentHeaderComponent={BusinessMessageContentHeader}
>
	{children}
</AgentProvider>

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

存储隔离

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

开发验证

独立启动 SDK 验收页：

pnpm --filter agent-chat-sdk dev

默认地址为 http://localhost:3100。演示页必须使用真实的本地模型 URL、MODEL 和 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_PROVIDER=openai
AGENT_DEMO_MODEL_API_KEY=your-local-only-key
AGENT_DEMO_MODEL_ID=your-model
AGENT_DEMO_MODEL_LABEL=Model display name
AGENT_DEMO_MODEL_URL=https://example.com/v1/chat/completions
AGENT_DEMO_WEB_SEARCH_MCP_URL=https://example.com/mcp

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

模型列表与密钥的职责分开：模型列表提供模型名称、展示名和 URL， .env.local 只提供本机 API Key。SDK 加载模型列表后将两者组合成 Runtime 模型配置，Key 不会进入模型列表。

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 一致性校验和全量测试。