@sophonsai/agent-embed-vue

@sophonsai/agent-embed-vue

应用接入

传入服务地址 endpoint 和 Agent 的应用接入 token；可选 baseUrl 默认是 /e/v1/embed。 最终 iframe 地址是 endpoint + baseUrl + '/' + encodeURIComponent(token)。

<AgentEmbed endpoint="https://agent.example.com" token="应用接入Token" style="height:600px" />

不再接收完整 url、旧 initConfig、Agent ID 或平台用户凭证。 threadId、外观配置、实例命令和事件回调继续支持。

安装

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

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

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

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

快速开始

<script setup lang="ts">
import { reactive, shallowRef } from 'vue'
import {
  AgentEmbed,
  type AgentAppearance,
  type AgentEmbedInstance,
  type AgentEmbedTheme,
} from '@sophonsai/agent-embed-vue'

const endpoint = 'https://agent.example.com'
const token = '应用接入Token'

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

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

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

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

<template>
  <div class="page">
    <AgentEmbed
      class="agent-embed"
      :endpoint="endpoint"
      :token="token"
      :appearance="appearance"
      @theme-change="handleThemeChange"
      @font-size-change="handleFontSizeChange"
      @init-error="({ 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-embed {
  min-height: 480px;
}
</style>

组件 Props

组件事件

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

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

初始化配置

<AgentEmbed
  endpoint="https://agent.example.com"
  token="应用接入Token"
  base-url="/e/v1/embed"
  thread-id="可选初始会话ID"
/>

baseUrl 可以省略。接入配置只在挂载时读取；需要切换服务、token 或会话时，修改组件 key 重新挂载。 appearance 会随外观配置更新。

外观与受控状态

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

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

可用主题：

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

import { AgentEmbedThemePreset } from '@sophonsai/agent-embed-vue'

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

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 事件会返回 AgentEmbedInstance。在此之前，获取不到 AgentEmbedInstance 实例对象，无法操作面板执行行为。

推荐使用 shallowRef 保存实例：

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

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

AgentEmbedInstance 方法：

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

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

错误处理

<AgentEmbed :endpoint="endpoint" :token="token" @init-error="handleInitError" />

初始化失败码：

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

智能体加载失败码：

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

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

会话事件

<AgentEmbed
  :endpoint="endpoint"
  :token="token"
  @session-context-ready="handleContextReady"
  @tool-call-failed="handleToolFailed"
  @settled="handleSettled"
/>

全部运行事件如下：

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

布局说明

组件根节点默认样式为：

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

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

<template>
  <main class="agent-page">
    <AgentEmbed :endpoint="endpoint" :token="token" />
  </main>
</template>

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

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

运行时变量

runtime_variables 是可选的 JSON 对象，名称须与智能体声明的运行时变量一致。仅创建新会话时发送，已有会话沿用已绑定的变量；同一面板新建会话时复用初始化值。参数在初始化时生成快照，改变值需要重建面板。数据通过 iframe 消息传递，不写入接入 URL。

<AgentEmbed :endpoint="endpoint" :token="token" :runtime_variables="{ customer_id: 'customer-1' }" />

初始化错误使用 onInitError（Vue: @init-error），包含 code 和 message，同次初始化只触发一次。失败时 whenReady() reject，聊天运行错误继续通过 onError（Vue: @error）报告。