---
title: AI 助手方案 - t-agent-plugin-aistream
summary: t-agent-plugin-aistream 插件文档，t-agent 对接小程序 AI 智能体平台的核心插件，替代已废弃的 t-agent-plugin-assistant。涵盖 withAIStream 配置参数（agentId、enableTts、earlyStart、historySize、clientType、deviceId、tokenOptions 等）、withBuildIn 内置功能（智能家居控制、知识库搜索、推荐行动、工作流引导）、核心功能（TTS 语音合成、ASR 语音识别 createAsrAgent）、Hook 机制（onMessageParse、onSkillCompose、onSkillsEnd、onTTTAction、onCardsReceived）及 Mock 开发调试机制。
---

# t-agent-plugin-aistream

## 概述

t-agent-plugin-aistream 是 t-agent 的核心插件，提供了对接小程序 AI 智能体平台的能力。该插件替代了已废弃的 `@ray-js/t-agent-plugin-assistant`，提供了更强大的功能，包括流式对话、语音识别和多模态支持等。

**⚠️ 重要提示**：`@ray-js/t-agent-plugin-assistant` 已被废弃，请使用 `@ray-js/t-agent-plugin-aistream` 替代。

想了解更多详细信息，请访问[官方文档](https://developer.tuya.com/material/library_oHEKLjj0/component?code=TAgent#t-agent-plugin-aistream)。

## 核心概念

### withAIStream

`withAIStream` 是该插件的主要入口函数，用于创建与小程序 AI 智能体平台的连接。它支持流式对话、语音识别等功能。

主要配置参数：

- `agentId`：智能体 ID（必填）
- `clientType`：客户端类型，默认为 APP (2)
- `deviceId`：设备 ID，当 clientType 为 DEVICE (1) 时必填
- `wireInput`：是否将输入块传递给智能体，默认为 true
- `historySize`：历史消息大小，默认为 1000
- `indexId`：索引 ID，默认为 'default'
- `homeId`：家庭 ID，不填默认当前家庭
- `earlyStart`：是否在 onAgentStart 阶段就建立连接
- `tokenOptions`：获取 agent token 的参数
  - `api`：API 接口名
  - `version`：接口版本
  - `extParams`：额外参数

使用示例：

```tsx
const agent = createChatAgent(
  withUI(),
  withAIStream({
    agentId: 'your-agent-id',
    earlyStart: true,
    historySize: 500,
  })
);
```

### withBuildIn

`withBuildIn` 提供了一系列内置的功能，包括智能家居控制、知识库搜索等。必须在应用 withAIStream 插件后使用。

主要功能：

- **智能家居**：设备控制、场景管理
- **知识库搜索**：关联文档展示
- **推荐行动**：智能推荐用户操作
- **按钮交互**：动态按钮响应
- **工作流引导**：流程化操作指导
- **智能卡片**：丰富的卡片展示

使用示例：

```tsx
const agent = createChatAgent(
  withUI(),
  withAIStream({ agentId: 'your-agent-id' }),
  withBuildIn()
);
```

## 核心功能

### 语音识别 (ASR)

内置 AsrAgent 语音识别代理，支持实时语音转文字。

```tsx
import { createAsrAgent } from '@ray-js/t-agent-plugin-aistream';

const asrAgent = createAsrAgent({
  agentId: 'your-agent-id',
  onMessage: message => {
    if (message.type === 'text') {
      console.log('识别结果：', message.text);
    }
  },
});
```

### Hook 机制

提供了丰富的 Hook 来自定义行为：

- `onMessageParse`：消息解析时触发
- `onSkillCompose`：收到技能数据时触发
- `onSkillsEnd`：所有技能处理完成时触发
- `onTTTAction`：tile 使用 sendAction 时触发
- `onCardsReceived`：收到卡片数据时触发

### Mock 机制

为了方便开发，提供了 mock 机制：

```tsx
import { mock } from '@ray-js/t-agent-plugin-aistream';

// Mock AI Stream 响应
mock.hooks.hook('sendToAIStream', context => {
  if (context.options.blocks?.some(block => block.text?.includes('hello'))) {
    context.responseText = 'Hello! How can I help you?';
  }
});

// Mock ASR 语音识别
mock.hooks.hook('asrDetection', context => {
  context.responseText = 'Hello world! I am a virtual assistant.';
});
```

## 总结

t-agent-plugin-aistream 是 t-agent 的核心插件，相比已废弃的 assistant 插件，提供了更强大的功能和更好的开发体验。它支持流式对话、语音识别、多模态交互等现代 AI 应用所需的核心功能。

该插件与 t-agent 核心库和 t-agent-ui-ray 组件库无缝集成，让开发者能够轻松构建功能丰富的智能对话应用。通过丰富的配置选项和 Hook 机制，开发者可以根据具体需求进行深度定制。

更多详细信息和 API 说明，请访问[官方文档](https://developer.tuya.com/material/library_oHEKLjj0/component?code=TAgent#t-agent-plugin-aistream)。