@sophonsai/agent-embed-vue2

@sophonsai/agent-embed-vue2

应用接入

传入服务地址 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-vue2 vue@^2.7

# pnpm
pnpm add @sophonsai/agent-embed-vue2 vue@^2.7

# yarn
yarn add @sophonsai/agent-embed-vue2 vue@^2.7

# bun
bun add @sophonsai/agent-embed-vue2 vue@^2.7

快速开始

<template>
  <div class="page">
    <AgentEmbed
      class="agent-embed"
      :endpoint="endpoint"
      :token="token"
      :appearance="appearance"
      @theme-change="handleThemeChange"
      @font-size-change="handleFontSizeChange"
      @init-error="handleInitError"
      @settled="handleSettled"
      @ready="handleReady"
    />

    <button :disabled="!agent" @click="sendHello">发送消息</button>
  </div>
</template>

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

export default Vue.extend({
  components: { AgentEmbed },
  data() {
    return {
      endpoint: 'https://agent.example.com',
      token: '应用接入Token',
      appearance: {
        theme: { preset: 'glacier-blue' },
        fontSize: 16,
        header: {
          historyButton: true,
          newConversationButton: true,
          themeSettingButton: false,
        },
      } as AgentAppearance,
      agent: null as AgentEmbedInstance | null,
    }
  },
  methods: {
    handleReady(instance: AgentEmbedInstance) {
      this.agent = instance
    },
    handleThemeChange(theme: AgentEmbedTheme) {
      this.appearance.theme = theme
    },
    handleFontSizeChange(fontSize: number) {
      this.appearance.fontSize = fontSize
    },
    handleInitError({ code, message }: { code: string; message: string }) {
      console.error('初始化失败', code, message)
    },
    handleSettled(result: unknown) {
      console.log('会话结束', result)
    },
    sendHello() {
      this.agent?.sendMessage({ text: '你好' })
    },
  },
})
</script>

<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: 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-vue2'

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

Vue 2 适配器会深度监听整个 appearance 对象。修改主题、字号或任意头部按钮后，会同步更新面板：

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

当主题或字号作为受控值传入时，应在 @theme-change / @font-size-change 中同步修改 appearance，否则宿主状态仍保留旧值。

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

获取和使用实例

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

ready 事件返回的 AgentEmbedInstance 提供：

this.agent?.addInputQuery({
  text: '请分析选中内容',
  context: selectedText,
})
this.agent?.focusInput()

组件执行 beforeDestroy 后会销毁 client，已保存的 instance 也会失效。建议父组件同步清空 instance 引用。

错误处理

初始化失败码：

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

智能体加载失败码：

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

失败对象同时包含可读的 message。初始化失败不会触发 ready。

会话事件

<AgentEmbed
  :endpoint="endpoint"
  :token="token"
  @session-context-ready="({ threadId }) => console.log(threadId)"
  @tool-call-failed="handleToolFailed"
  @settled="handleSettled"
/>

全部运行事件如下：

事件 payload 和上下文类型均由本包重导出。

布局说明

组件根节点默认使用 width: 100%、height: 100% 和 min-height: 0。父级应设置明确高度：

.agent-embed-container {
  height: calc(100vh - 64px);
}

模板中的 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）报告。