@sophonsai/agent-panel-vue

@sophonsai/agent-panel-vue 是 SophonsAI 智能体平台提供的 Agent 面板快速接入组件，帮助 Vue 3 应用以简单、统一的方式集成完整的智能体交互能力。

安装

# npm
npm install @sophonsai/agent-panel-vue vue@^3.3

# pnpm
pnpm add @sophonsai/agent-panel-vue vue@^3.3

# yarn
yarn add @sophonsai/agent-panel-vue vue@^3.3

# bun
bun add @sophonsai/agent-panel-vue vue@^3.3

快速开始

<script setup lang="ts">
import { reactive, shallowRef } from 'vue'
import {
  AgentPanel,
  type AgentAppearance,
  type AgentPanelInstance,
  type AgentPanelTheme,
} from '@sophonsai/agent-panel-vue'

const initConfig = {
  endpoint: 'https://agent.example.com',
  agentId: 'agent-id',
  auth: { type: 'platform.user.credential', credential: 'access-token' },
}

const appearance = reactive<AgentAppearance>({
  theme: { preset: 'glacier-blue' },
  fontSize: 16,
  header: {
    historyButton: true,
    newConversationButton: true,
    themeSettingButton: false,
  },
})

const agent = shallowRef<AgentPanelInstance | null>(null)

const handleThemeChange = (theme: AgentPanelTheme) => {
  appearance.theme = theme
}

const handleFontSizeChange = (fontSize: number) => {
  appearance.fontSize = fontSize
}
</script>

<template>
  <div class="page">
    <AgentPanel
      class="agent-panel"
      :init-config="initConfig"
      :appearance="appearance"
      @theme-change="handleThemeChange"
      @font-size-change="handleFontSizeChange"
      @auth-failed="({ code, message }) => console.error('鉴权失败', code, message)"
      @agent-load-failed="({ code, message }) => console.error('智能体加载失败', code, message)"
      @settled="(result) => console.log('会话结束', result)"
      @ready="(instance) => (agent = instance)"
    />

    <button :disabled="!agent" @click="agent?.sendMessage({ text: '你好' })">发送消息</button>
  </div>
</template>

<style scoped>
.page {
  height: 640px;
}

.agent-panel {
  min-height: 480px;
}
</style>

组件 Props

| Prop | 类型 | 必填 | 说明 | | ------------ | ----------------- | ---- | ---------------------------------------- | | initConfig | AgentPanelInit | 是 | 服务地址、智能体 ID、token 和可选会话 ID | | appearance | AgentAppearance | 否 | 主题、字号和头部按钮配置 |

组件事件

组件使用标准 Vue 事件，不接受 onXxx 回调 Props。

| 事件 | 参数 | 说明 | | -------------------- | ---------- | -------------------- | | @ready | instance | 面板初始化完成 | | @theme-change | theme | 面板内部主题变化 | | @font-size-change | fontSize | 面板内部字号变化 | | @identity-resolved | identity | 外部用户身份解析成功 | | @auth-failed | failure | 鉴权失败 | | @agent-load-failed | failure | 智能体信息加载失败 |

全部运行事件见“会话事件”章节。

初始化配置

const initConfig = {
  endpoint: 'https://agent.example.com',
  agentId: 'agent-id',
  auth: { type: 'platform.user.credential', credential: 'access-token' },
  threadId: 'optional-conversation-id',
}

| 字段 | 说明 | | ---------- | ----------------------------------------------------------- | | endpoint | Sophon 智能体平台服务端点 | | baseUrl | 已弃用的 endpoint 兼容别名，下一个版本移除 | | basePath | Extension 应用部署路径，默认 /app/extension；根路径传 / | | agentId | 要加载的智能体 ID | | auth | 平台用户凭证或扩展用户身份鉴权配置 | | token | 已弃用的 token 模式兼容写法 | | threadId | 可选，要打开的已有会话 ID |

endpoint 与 baseUrl 至少提供一个；同时提供时优先使用 endpoint。

扩展用户身份模式可传 auth: { type: 'extension.user.identity', appId, externalUser: { id, name? } }；身份仅通过 bridge 发送，不进入 iframe URL。解析成功后触发 @identity-resolved。

初始化配置是一次性快照

组件在挂载时读取 initConfig。需要更换智能体、token 或会话时，请改变组件 key，让 Vue 卸载旧组件并创建新组件：

<AgentPanel :key="panelRevision" :init-config="{ endpoint, agentId, token }" @ready="handleReady" />

外观与受控状态

const appearance = reactive<AgentAppearance>({
  theme: { preset: 'studio-white' },
  fontSize: 16,
  header: {
    historyButton: true,
    newConversationButton: true,
    themeSettingButton: true,
  },
})

header.themeSettingButton 默认值为 false，只有显式设置为 true 时才显示主题设置按钮。

可用主题：

可以使用 AgentPanelThemePreset 枚举式常量设置主题：

import { AgentPanelThemePreset } from '@sophonsai/agent-panel-vue'

const appearance = {
  theme: { preset: AgentPanelThemePreset.GlacierBlue },
}

| 主题名 | preset | 类型 | | ------ | ----------------- | -------- | | 曜石紫 | obsidian-violet | 深色主题 | | 石墨青 | graphite-cyan | 深色主题 | | 午夜靛 | midnight-indigo | 深色主题 | | 深海蓝 | deep-ocean | 深色主题 | | 森野绿 | forest-emerald | 深色主题 | | 影棚白 | studio-white | 浅色主题 | | 珍珠紫 | pearl-violet | 浅色主题 | | 冰川蓝 | glacier-blue | 浅色主题 | | 暖杏色 | warm-cream | 浅色主题 | | 薰衣草 | lavender-mist | 浅色主题 |

Vue 3 适配器会分别监听：

• appearance.theme，深度监听；
• appearance.fontSize；
• appearance.header，深度监听。

因此下面的修改会自动同步到面板：

appearance.theme = { preset: 'warm-cream' }
appearance.fontSize = 18
appearance.header!.themeSettingButton = false

当主题或字号作为受控状态传入时，应在 @theme-change / @font-size-change 中更新响应式状态，否则外部状态仍会保留旧值。

将 theme、fontSize 或 header 改为 undefined 会撤销对应的宿主控制，让面板恢复内部默认值。

获取和使用实例

面板初始化完成后，ready 事件会返回 AgentPanelInstance。在此之前，获取不到 AgentPanelInstance 实例对象，无法操作面板执行行为。

推荐使用 shallowRef 保存实例：

const agent = shallowRef<AgentPanelInstance | null>(null)

const handleReady = (instance: AgentPanelInstance) => {
  agent.value = instance
  instance.focusInput()
}

AgentPanelInstance 方法：

| 方法 | 说明 | | ----------------------------------- | ------------------------------------------- | | sendMessage({ text }) | 立即提交消息；生成期间调用会使用 steer 行为 | | addInputQuery({ text, context? }) | 写入输入框和可选上下文，不立即提交 | | abortResponse() | 终止当前回复 | | openHistoryPanel() | 打开历史会话面板 | | openThemeSettingsPanel() | 打开主题设置面板 | | newConversation() | 新建会话 | | focusInput() | 聚焦输入框 | | scrollToBottom() | 滚动到底部 |

agent.value?.addInputQuery({
  text: '请解释这段内容',
  context: selectedText.value,
})
agent.value?.focusInput()

组件卸载时会销毁 client，之前保存的 instance 随之失效。父组件应在切换实例时同步清理引用。

错误处理

<AgentPanel :init-config="initConfig" @auth-failed="handleAuthFailed" @agent-load-failed="handleAgentLoadFailed" />

鉴权失败码：

• missing_token：缺少 token；
• invalid_token：token 无效或过期；
• forbidden：无访问权限；
• request_failed：鉴权请求失败。

智能体加载失败码：

• not_found：未找到智能体；
• forbidden：无权访问智能体；
• request_failed：智能体请求失败。

失败对象还包含可读的 message。上述失败发生时不会触发 ready。

会话事件

<AgentPanel
  :init-config="initConfig"
  @session-context-ready="handleContextReady"
  @tool-call-failed="handleToolFailed"
  @settled="handleSettled"
/>

全部运行事件如下：

| 事件 | 参数 | 说明 | | ----------------------------- | --------------------------------------------------------------- | ------------------------------------------- | | @concurrent-send | 无 | 回复生成期间再次发送消息 | | @event | AgentServerEvent | 接收原始服务端事件 | | @session-context-ready | AgentSessionContext | 会话上下文可用，包含 threadId 和 turnId | | @tool-call-created | AgentToolCallCreatedEvent, AgentSessionEventContext | 创建一个工具调用 | | @tool-approval-requested | AgentToolApprovalRequestedEvent, AgentSessionEventContext | 一组工具调用需要确认 | | @tool-call-started | AgentToolCallStartedEvent, AgentSessionEventContext | 工具调用开始 | | @tool-call-progress-updated | AgentToolCallProgressUpdatedEvent, AgentSessionEventContext | 工具调用进度更新 | | @tool-call-backgrounded | AgentToolCallBackgroundedEvent, AgentSessionEventContext | 工具调用转为后台执行 | | @tool-call-succeeded | AgentToolCallSucceededEvent, AgentSessionEventContext | 工具调用成功 | | @tool-call-failed | AgentToolCallFailedEvent, AgentSessionEventContext | 工具调用失败 | | @tool-call-cancelled | AgentToolCallCancelledEvent, AgentSessionEventContext | 工具调用取消 | | @client-action-request | AgentClientActionRequestEvent, AgentSessionEventContext | 智能体请求宿主执行客户端动作 | | @user-feedback-consumed | AgentUserFeedbackConsumedEvent, AgentSessionEventContext | 用户反馈已被处理 | | @user-steer-consumed | AgentUserSteerConsumedEvent, AgentSessionEventContext | 用户 steer 指令已被处理 | | @user-steer-cancelled | AgentUserSteerCancelledEvent, AgentSessionRunEventContext | 用户 steer 指令已取消 | | @user-input-submitted | AgentUserInputSubmittedEvent, AgentSessionEventContext | 用户输入已提交 | | @session-turn-started | AgentSessionTurnStartedEvent, AgentSessionEventContext | Turn 开始执行 | | @session-turn-succeeded | AgentSessionTurnSucceededEvent, AgentSessionEventContext | Turn 执行成功 | | @session-turn-failed | AgentSessionTurnFailedEvent, AgentSessionEventContext | Turn 执行失败 | | @session-turn-cancelled | AgentSessionTurnCancelledEvent, AgentSessionEventContext | Turn 已取消 | | @session-run-started | AgentSessionRunStartedEvent, AgentSessionRunEventContext | Run 已开始 | | @session-run-idled | AgentSessionRunIdledEvent, AgentSessionRunEventContext | Run 已空闲 | | @session-run-ended | AgentSessionRunEndedEvent, AgentSessionRunEventContext | Run 已结束 | | @system-message-consumed | AgentSystemMessageConsumedEvent, AgentSessionEventContext | 系统消息已被处理 | | @success | AgentSessionSuccess | 本轮会话成功结束 | | @error | AgentSessionFailure | 本轮会话失败 | | @cancelled | AgentSessionCancelled | 本轮会话取消 | | @settled | AgentSessionSettlement | 本轮会话以任意状态结束 |

事件 payload、会话上下文和工具调用类型均由本包重导出。

布局说明

组件根节点默认样式为：

width: 100%;
height: 100%;
min-height: 0;

父容器需要设置明确高度：

<template>
  <main class="agent-page">
    <AgentPanel :init-config="initConfig" />
  </main>
</template>

<style>
.agent-page {
  height: calc(100vh - 64px);
}
</style>

模板中传入的 class 和 style 会作用于根元素。