@sophonsai/agent-embed-sdk 0.1.0 → 0.2.0

package/README.md

@@ -2,17 +2,13 @@
 
 ## 应用接入
 
-传入服务地址 `endpoint` 和 Agent 的应用接入 `token`；可选 `baseUrl` 默认是 `/e/v1/embed`。
-最终 iframe 地址是 `endpoint + baseUrl + '/' + encodeURIComponent(token)`。
+传入 SAAP 服务地址 `endpoint` 和智能体的应用接入凭证 `token`。
 
 ```ts
 const client = createAgentEmbed({ endpoint: 'https://agent.example.com', token: '应用接入Token' })
 await client.mount(document.getElementById('agent-embed')!)
 ```
 
-不再接收完整 `url`、旧 `initConfig`、Agent ID 或平台用户凭证。
-`threadId`、外观配置、实例命令和事件回调继续支持。
-
 ## 安装
 
 ```bash
@@ -82,15 +78,13 @@ client.destroy()
 
 | 配置                | 类型                    | 必填 | 说明                                            |
 | ------------------- | ----------------------- | ---- | ----------------------------------------------- |
-| `endpoint`          | `string`                | 是   | Gateway / Extension 服务地址，包含 HTTP(S) 协议 |
+| `endpoint`          | `string`                | 是   | SAAP 服务地址，包含 HTTP(S) 协议                 |
 | `token`             | `string`                | 是   | Agent 应用接入凭证                              |
-| `baseUrl`           | `string`                | 否   | 嵌入页面路径，默认 `/e/v1/embed`                |
 | `threadId`          | `string`                | 否   | 初始会话 ID                                     |
 | `runtime_variables` | `AgentRuntimeVariables` | 否   | 新会话绑定的运行时变量，值必须为 JSON           |
 | `appearance`        | `AgentAppearance`       | 否   | 主题、字号与 Header 按钮                        |
 
-`endpoint` 可包含反向代理路径前缀；`baseUrl` 必须是以 `/` 开头的路径。
-凭证只写入 iframe 路径，bridge 初始化消息不再传递凭证或 Agent ID。
+`endpoint` 可包含反向代理路径前缀。
 配置与回调在创建 client 时保存为快照；切换接入地址、token、会话或回调时，销毁并重新创建 client。
 外观可以使用 `updateTheme`、`updateFontSize`、`updateHeader` 更新。
 
@@ -108,7 +102,7 @@ const appearance: AgentAppearance = {
 }
 ```
 
-`header.themeSettingButton` 默认值为 `false`，只有显式设置为 `true` 时才显示主题设置按钮。
+`header.themeSettingButton` 默认值为 `true`，显式设置为 `false` 时隐藏主题设置按钮。
 
 ### 可用主题
 
@@ -247,6 +241,8 @@ agent.focusInput()
 
 ## 会话事件
 
+SDK 自动以 `clientTools` 的键声明本次运行支持的客户端工具；未提供或为空时不注入客户端工具，子智能体也不注入。
+
 可以在 `createAgentEmbed()` 中传入以下全部运行事件回调：
 
 | 回调                        | 参数                                                            | 说明                                        |
@@ -254,7 +250,7 @@ agent.focusInput()
 | `onConcurrentSend`          | 无                                                              | 回复生成期间再次发送消息                    |
 | `onEvent`                   | `AgentServerEvent`                                              | 接收原始服务端事件                          |
 | `onSessionContextReady`     | `AgentSessionContext`                                           | 会话上下文可用，包含 `threadId` 和 `turnId` |
-| `onToolCallCreated`         | `AgentToolCallCreatedEvent`, `AgentSessionEventContext`         | 创建一个工具调用                            |
+| `onToolCallReady`         | `AgentToolCallReadyEvent`, `AgentSessionEventContext`         | 创建一个工具调用                            |
 | `onToolApprovalRequested`   | `AgentToolApprovalRequestedEvent`, `AgentSessionEventContext`   | 一组工具调用需要确认                        |
 | `onToolCallStarted`         | `AgentToolCallStartedEvent`, `AgentSessionEventContext`         | 工具调用开始                                |
 | `onToolCallProgressUpdated` | `AgentToolCallProgressUpdatedEvent`, `AgentSessionEventContext` | 工具调用进度更新                            |
@@ -262,6 +258,7 @@ agent.focusInput()
 | `onToolCallSucceeded`       | `AgentToolCallSucceededEvent`, `AgentSessionEventContext`       | 工具调用成功                                |
 | `onToolCallFailed`          | `AgentToolCallFailedEvent`, `AgentSessionEventContext`          | 工具调用失败                                |
 | `onToolCallCancelled`       | `AgentToolCallCancelledEvent`, `AgentSessionEventContext`       | 工具调用取消                                |
+| `onClientToolRequest` | `AgentToolCallStartedEvent`, `AgentSessionEventContext` | 客户端工具执行请求；需领取并回传结果，或使用 SDK `clientTools` 自动执行 |
 | `onClientActionRequest`     | `AgentClientActionRequestEvent`, `AgentSessionEventContext`     | 智能体请求宿主执行客户端动作                |
 | `onUserFeedbackConsumed`    | `AgentUserFeedbackConsumedEvent`, `AgentSessionEventContext`    | 用户反馈已被处理                            |
 | `onUserSteerConsumed`       | `AgentUserSteerConsumedEvent`, `AgentSessionEventContext`       | 用户 steer 指令已被处理                     |

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AgentAppearance as AgentAppearance$1, AgentEmbedHeaderAppearance, AgentEmbedInitError, AgentEmbedInstance, AgentEmbedTheme as AgentEmbedTheme$1, AgentEvents, AgentRuntimeVariables } from "@sophonsai/agent-embed-core";
+import { AgentAppearance as AgentAppearance$1, AgentEmbedHeaderAppearance, AgentEmbedInitError, AgentEmbedInstance, AgentEmbedTheme as AgentEmbedTheme$1, AgentEvents, AgentRuntimeValue, AgentRuntimeVariables, AgentSessionEventContext } from "@sophonsai/agent-embed-core";
 export * from "@sophonsai/agent-embed-core";
 //#region src/theme-presets.d.ts
 declare const AgentEmbedThemePreset: {
@@ -29,7 +29,10 @@ interface AgentEmbedOptions extends AgentEvents {
   onFontSizeChange?: (fontSize: number) => void;
   onInitError?: (error: AgentEmbedInitError) => void;
 }
+type AgentClientToolHandler = (arguments_: Record<string, unknown>, context: AgentSessionEventContext) => AgentRuntimeValue | Promise<AgentRuntimeValue>;
 interface CreateAgentEmbedOptions extends AgentEmbedOptions {
+  /** Host implementations keyed by the platform client tool name; returned values are sent to the Agent. */
+  clientTools?: Record<string, AgentClientToolHandler>;
   /** Gateway / Extension service address, including HTTP or HTTPS scheme. */
   endpoint: string;
   /** Shared Agent access token. */
@@ -51,4 +54,4 @@ interface AgentEmbedClient {
 declare const DEFAULT_AGENT_EMBED_BASE_URL = "/e/v1/embed";
 declare const createAgentEmbed: (options: CreateAgentEmbedOptions) => AgentEmbedClient;
 //#endregion
-export { AgentAppearance, AgentEmbedClient, AgentEmbedTheme, AgentEmbedThemePreset, CreateAgentEmbedOptions, DEFAULT_AGENT_EMBED_BASE_URL, createAgentEmbed };
+export { AgentAppearance, AgentClientToolHandler, AgentEmbedClient, AgentEmbedTheme, AgentEmbedThemePreset, CreateAgentEmbedOptions, DEFAULT_AGENT_EMBED_BASE_URL, createAgentEmbed };

package/dist/index.mjs

@@ -27,6 +27,8 @@ const cloneAppearance = (appearance) => {
 };
 var AgentEmbedClientImpl = class {
 	constructor(options) {
+		this.toolClientId = `client-${globalThis.crypto.randomUUID()}`;
+		this.handledToolCalls = /* @__PURE__ */ new Set();
 		this.instanceId = createInstanceId();
 		this.mounted = false;
 		this.initialized = false;
@@ -80,6 +82,13 @@ var AgentEmbedClientImpl = class {
 				this.failInitialization(message.args?.[0]);
 				return;
 			}
+			if (message.callback === "onClientToolRequest" && this.clientTools) this.executeClientTool(message.args?.[0], message.args?.[1]).catch((error) => {
+				this.events.onError?.({
+					status: "failure",
+					context: null,
+					error
+				});
+			});
 			const callback = this.events[message.callback];
 			try {
 				callback?.(...message.args ?? []);
@@ -101,6 +110,9 @@ var AgentEmbedClientImpl = class {
 		this.targetOrigin = endpoint.origin;
 		this.appearance = cloneAppearance(options.appearance);
 		this.events = pickAgentEvents(options);
+		this.clientTools = options.clientTools ? { ...options.clientTools } : void 0;
+		this.toolAccessToken = options.token;
+		this.toolApiUrl = new URL("/webapi/v1/agent/client-tools", options.endpoint).toString();
 		this.onReady = options.onReady;
 		this.onThemeChange = options.onThemeChange;
 		this.onFontSizeChange = options.onFontSizeChange;
@@ -230,6 +242,7 @@ var AgentEmbedClientImpl = class {
 			type: "init",
 			config: {
 				mode: "url",
+				client_tool_names: Object.keys(this.clientTools ?? {}),
 				threadId: this.threadId,
 				appearance: this.appearance,
 				...this.runtimeVariables === void 0 ? {} : { runtime_variables: this.runtimeVariables }
@@ -267,6 +280,49 @@ var AgentEmbedClientImpl = class {
 			this.onInitError?.(failure);
 		} catch {}
 	}
+	async postTool(path, body) {
+		const response = await fetch(`${this.toolApiUrl}/${path}`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${this.toolAccessToken}`
+			},
+			body: JSON.stringify(body)
+		});
+		const envelope = await response.json();
+		if (!response.ok || envelope.code !== 200) throw new Error(envelope.msg ?? `Client tool request failed (${response.status}).`);
+		return envelope.data;
+	}
+	async executeClientTool(event, context) {
+		const handler = this.clientTools && Object.hasOwn(this.clientTools, event.toolName) ? this.clientTools[event.toolName] : void 0;
+		if (!handler) return;
+		const key = `${context.turnId}:${event.toolCallId}`;
+		if (this.destroyed || this.handledToolCalls.has(key)) return;
+		this.handledToolCalls.add(key);
+		const call = {
+			turn_id: context.turnId,
+			tool_call_id: event.toolCallId,
+			client_id: this.toolClientId
+		};
+		if (await this.postTool("claim", call) !== true) return;
+		let result;
+		try {
+			const value = await handler(event.arguments, context);
+			result = {
+				status: "success",
+				result: typeof value === "string" ? value : JSON.stringify(value)
+			};
+		} catch (error) {
+			result = {
+				status: "error",
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+		await this.postTool("result", {
+			...call,
+			...result
+		});
+	}
 };
 const createAgentEmbed = (options) => new AgentEmbedClientImpl(options);
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sophonsai/agent-embed-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-independent browser SDK for integrating Sophon Agent Embed.",
   "type": "module",
   "keywords": [
@@ -25,7 +25,7 @@
     "dist"
   ],
   "dependencies": {
-    "@sophonsai/agent-embed-core": "0.1.0"
+    "@sophonsai/agent-embed-core": "0.2.0"
   },
   "devDependencies": {
     "jsdom": "^27.4.0",