Agent

Agent 是 v2.0 的多轮对话与工具调用能力，适用于需要接入 AG-UI、工具注册、工具结果回传、Agent 状态管理的业务场景。

只需要单次流式生成时，请使用 Stream。

核心特征

主 API：send(params, options)
输出结构：messages[].parts
维护多轮消息历史
支持 AgentState 状态管理
支持 setTools() / setTool() 运行时注册工具
支持 Frontend 工具结果回传：toolExecuted → setMessages() → send({}, { type: 'tools' })

框架接入案例

框架	接入方式	示例
React	`useAgent`	React 示例
Vue 3	`useAgent`	Vue 3 示例
Vue 2	`AgentMixin`	Vue 2 示例
小程序	`AgentBehavior`	小程序示例

与 Stream 的核心差异

特性	Stream	Agent
对接场景	单次流式生成	多轮 Agent 对话
核心方法	`generate()`	`send()`
输出结构	`parts`	`messages[].parts`
消息历史	不维护	维护
工具注册	不支持	`setTools()` / `setTool()`
状态管理	无 `agentState`	`agentState`
React	`useStream`	`useAgent`
Vue 3	`useStream`	`useAgent`
Vue 2	`StreamMixin`	`AgentMixin`
小程序	当前未导出 `StreamBehavior`	`AgentBehavior`

快速使用

ReactVue3Vue2小程序

tsx

import { useAgent } from '@tencent/ssv-ai-sdk-react';
import { AGUIPlugin } from '@tencent/ssv-ai-sdk-plugin-agui';

const { messages, send, setTools, setMessages, on, off } = useAgent({
  api: {
    chatEndpoint: {
      url: 'https://your-api.com/agent',
    },
  },
  mode: 'stream',
  plugins: [new AGUIPlugin()],
});

await send({ input: '你好' });

vue

<script setup>
import { useAgent } from '@tencent/ssv-ai-sdk-vue';
import { AGUIPlugin } from '@tencent/ssv-ai-sdk-plugin-agui';

const { messages, send, setTools, setMessages, on, off } = useAgent({
  api: {
    chatEndpoint: {
      url: 'https://your-api.com/agent',
    },
  },
  mode: 'stream',
  plugins: [new AGUIPlugin()],
});
</script>

import { AgentMixin } from '@tencent/ssv-ai-sdk-vue2';
import { AGUIPlugin } from '@tencent/ssv-ai-sdk-plugin-agui';

export default {
  mixins: [
    AgentMixin({
      api: {
        chatEndpoint: {
          url: 'https://your-api.com/agent',
        },
      },
      mode: 'stream',
      plugins: [new AGUIPlugin()],
    }),
  ],
};

import { AgentBehavior } from '@tencent/ssv-ai-sdk-miniprogram';
import { AGUIPlugin } from '@tencent/ssv-ai-sdk-plugin-agui';

Component({
  behaviors: [
    AgentBehavior({
      api: {
        chatEndpoint: {
          url: 'https://your-api.com/agent',
        },
      },
      plugins: [new AGUIPlugin()],
    }),
  ],
});

Messages 与 Parts

Agent 的助手消息使用 parts 表示时序内容：

interface Message {
  id: string;
  role: 'user' | 'assistant' | 'system' | 'tool';
  content?: string;
  extraInfo: any;
  parts?: Part[];
  toolCallId?: string;
}

常见 Part：

interface TextPart {
  type: 'text';
  text: string;
  status: 'streaming' | 'done';
}

interface ReasoningPart {
  type: 'reasoning';
  reason: string;
  status: 'streaming' | 'done';
}

interface ToolCallPart {
  type: 'tool_call';
  id: string;
  name: string;
  rawArgs: string;
  args: any;
  status: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
  result?: any;
  rawResult?: string;
  error?: string;
}

渲染原则：按 message.parts 顺序逐段渲染，不要只读取 message.content。

工具注册

推荐在组件生命周期中注册工具，这样工具 handler 可以通过闭包访问组件状态。

setTools([
  {
    name: 'setThemeColor',
    description: 'Set the page theme color. Use hex format like #1890ff.',
    type: 'frontend',
    parameters: {
      type: 'object',
      properties: {
        color: { type: 'string', description: 'Hex color' },
      },
      required: ['color'],
    },
    handler: async ({ color }) => {
      setThemeColor(color);
      return { success: true, color };
    },
  },
]);

工具结果回传

Frontend 工具执行完成后会触发 toolExecuted。业务层负责把结果追加为 tool 消息，并调用 send({}, { type: 'tools' }) 继续 Agent Run。

on('toolExecuted', ({ toolCallId, toolCallName, result }) => {
  if (UI_ONLY_TOOLS.includes(toolCallName)) return;

  const toolMessage = {
    id: `tool-${Date.now()}`,
    role: 'tool',
    content: typeof result === 'string' ? result : JSON.stringify(result),
    toolCallId,
    extraInfo: {},
  };

  setMessages([...messages, toolMessage]);
  send({}, { type: 'tools' });
});

状态 State

interface AgentChatState {
  messages: Message[];
  error: AIErrorOptions | null;
  status: 'idle' | 'loading' | 'success' | 'failed' | 'stopped';
  assistantStatus: 'idle' | 'loading' | 'reasoning' | 'answering' | 'tool_calling';
  agentState: Record<string, any>;
}

方法 Action

方法	说明
`send(params, options)`	发送消息或工具结果
`stop()`	停止当前生成
`setMessages(messages)`	设置消息列表
`setTools(tools)`	批量注册工具
`setTool(tool)`	注册单个工具
`setAgentState(path, value)`	设置 Agent 状态
`getAgentState()`	获取 Agent 状态
`resetAgent()`	重置 Agent
`on(event, handler)`	监听事件
`off(event, handler)`	移除事件监听

事件 Events

事件名	说明
`toolCallStart`	工具调用开始
`toolCallArgs`	工具参数流式到达
`toolCallEnd`	工具参数接收完成
`toolCallResult`	后端工具结果到达
`toolExecuted`	前端工具执行完成
`runStarted`	Agent Run 开始
`runFinished`	Agent Run 结束
`runError`	Agent Run 出错
`stateSnapshot`	完整状态快照
`stateDelta`	状态增量更新

Agent #

核心特征 #

框架接入案例 #

与 Stream 的核心差异 #

快速使用 #

Messages 与 Parts #

工具注册 #

工具结果回传 #

状态 State #

方法 Action #

事件 Events #