# EVA Client SDK

## 让设备听得懂、看得见、自然地回应

EVA Client SDK 是一套运行在端侧的自然语音与视觉交互 Agent 方案。它依托 EVA Gateway 的云端模型推理服务，并结合端侧模型推理与媒体处理能力，覆盖 VAD、ASR、LLM、TTS、回声消除和摄像头多模态输入，为应用提供端云一体的音视频交互体验。

开发者无需分别处理录音、语音识别、大模型调用、语音合成、音频播放和打断逻辑，即可在浏览器、桌面应用、移动 App 和智能硬件上构建自然对话产品。

## 适合哪些产品

- **AI 语音助手**：为网页、桌面或移动应用加入自然语音问答和连续对话。

- **智能客服与接待**：让用户直接开口咨询，并在回答过程中随时追问或打断。

- **数字人和虚拟角色**：结合流式文本、语音合成与视觉输入，打造更自然的实时互动。

- **智能眼镜与可穿戴设备**：通过语音和摄像头理解用户当前所见，提供随身信息服务。

- **机器人与智能硬件**：为机器人、ESP32 等设备提供统一的听、说、理解和交互链路。

EVA Client SDK 面向多种端侧环境提供对应实现。当前包含 TypeScript 版本，Flutter、C\+\+ 和 Python 版本正在规划与开发中。

## 为什么选择 EVA Client SDK

- **完整 Agent 链路**：一个 SDK 串起录音、VAD、ASR、LLM、TTS 和播放，减少多套服务之间的接线与状态管理。

- **自然打断**：用户说话时停止当前回复和语音播放，减少机械式等待，让多轮对话更接近真人交流。

- **端侧感知与处理**：在设备侧完成 VAD、媒体采集和回声消除等处理，降低无效数据传输并改善响应体验。

- **语音与视觉结合**：除语音和文本外，还可将当前摄像头画面加入对话，让 Agent 回答“我现在看到的是什么”。

- **模型能力统一接入**：通过 EVA Gateway 使用 ASR、LLM 和 TTS 模型，无需为不同模型分别维护调用链路。

- **过程可观察、状态可控制**：应用可以获得实时转写、流式回复、播放、打断、错误和延迟信息，并按需控制麦克风、TTS 与摄像头。

## 持续演进的 Agent 能力

自然语音对话是 EVA Client SDK 当前提供的核心模式。未来，SDK 会在同一套端云一体架构上继续扩展：

- **更多处理模式**：扩展会议纪要、实时翻译等处理模式，让开发者按产品场景选择合适的 Agent 工作方式。

- **更多端侧模型推理**：逐步将适合本地运行的模型能力带到端侧，降低网络依赖，并改善响应速度、数据边界和弱网体验。

- **更多语言与平台实现**：在 TypeScript 之外继续提供 Flutter、C\+\+ 和 Python SDK，让不同设备复用一致的 Agent 能力与交互语义。

以上能力会随各平台 SDK 逐步发布；具体支持范围以对应版本的发布说明为准。

## 使用条件

接入 EVA Client SDK 前，请确认：

- 设备已联网。

- 已获取 EVA Gateway API Key 并授权。

- 设备具备产品所需的麦克风、扬声器或摄像头，并允许应用访问相关权限。

## 选择 SDK 版本

满足上述条件后，请根据目标开发平台选择对应版本。

### TypeScript

**状态：已发布**

适用于 Web 应用、Electron 桌面应用以及具备 Web Audio 和媒体能力的 JavaScript/TypeScript 运行环境。构建环境要求 Node\.js `>=20`。

浏览器中的麦克风和摄像头需要 secure context；生产环境请使用 HTTPS，本地开发可使用 `localhost`。

安装 SDK：

```Bash
npm install @autoark-ai/eva-client-sdk-ts
```

#### 运行官方 Demo

你可以直接运行 [EVA SDK Examples](https://github.com/AutoArk/eva-sdk-examples) 中的 TypeScript 浏览器 Demo：

```Bash
git clone https://github.com/AutoArk/eva-sdk-examples.git
cd eva-sdk-examples/client-sdk/ts/browser-conversation-agent
npm ci
npm run dev
```

打开终端输出的本地地址，点击“启动会话”，再输入 EVA Gateway API Key。API Key 仅保存在当前页面内存中，刷新页面后会被清除。

这个 Demo 展示了语音与文本输入、实时转写、流式回复、多轮上下文、自然打断、TTS、麦克风控制和可选的摄像头多模态问答。

#### 相关链接

- [npm package](https://www.npmjs.com/package/@autoark-ai/eva-client-sdk-ts)

- [Quickstart：浏览器对话 Demo](https://github.com/AutoArk/eva-sdk-examples/tree/main/client-sdk/ts/browser-conversation-agent)

### Flutter

**状态：即将推出**

面向 iOS 和 Android 应用，提供与 EVA Agent 契约一致的移动端语音交互能力。适合正在构建移动语音助手、智能客服、数字人或设备控制 App 的团队。

### C\+\+

**状态：敬请期待**

面向资源受限的嵌入式设备和智能硬件，可运行在 ESP32 等平台，让机器人、玩具、家居设备及其他端侧产品也能接入 EVA 的自然语音交互能力。

### Python

**状态：规划中**

面向桌面应用、Linux 设备和支持 Python 运行时的边缘计算环境，适合快速构建语音助手、设备交互原型及行业应用。

## Q\&A

### 是否支持摄像头和多模态问答？

支持。SDK 可以按需启用摄像头，在当前语音轮次采集一张图片，并将图片与用户语音识别结果一起交给多模态 LLM。摄像头默认关闭，应用可以根据产品需要开启或释放。

### 我要切换模型，应该怎么做？

创建 Agent 时可以分别配置 `asr.model`、`llm.model`、`tts.model` 和 `tts.voice`。实际可选的模型与组合以当前 EVA Gateway 环境为准。

### 只支持语音对话这一种使用方式？

当前已发布版本以自然语音对话为核心。后续将扩展会议纪要、实时翻译等处理模式。这些能力会复用同一套媒体、模型接入和事件机制，开发者无需重新搭建整条处理链路。

### SDK 可以完全离线运行吗？

是否可以完全离线运行，取决于目标设备的硬件算力、可用资源以及所选模型的推理需求。EVA Client SDK 会逐步提供更多本地模型推理能力，并针对主流硬件给出明确的能力范围、配置要求和支持说明；不适合在端侧运行的模型仍可通过 EVA Gateway 使用云端推理能力。具体支持情况以对应平台和版本的发布说明为准。

### 用户可以在 Agent 说话时打断吗？

可以。当检测到用户重新说话或提交新的文本时，Agent 会停止当前回复和 TTS 播放，并开始处理新的对话轮次。

### 浏览器里可以安全保存 API Key 吗？

浏览器中的凭证对页面使用者始终可观察。不要把长期、全权限 API Key 写入公开源码或静态 bundle；建议使用可轮换、限额且权限最小化的凭证，并在应用层设计合适的发放与撤销策略。

### 目前支持哪些平台？

TypeScript SDK 已发布；Flutter、C\+\+ 和 Python 版本正在规划与开发中。各版本对应的运行平台见上方“选择 SDK 版本”，后续会在本页开放安装方式和 Quickstart。