Skip to content

docs: Update README files for improved clarity and consistency in formatting, including TTS provider details and service region options #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 4, 2025
Merged

docs: Update README files for improved clarity and consistency in formatting, including TTS provider details and service region options #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
74690dd
docs: Update README files for improved clarity and consistency in for…
seymourtang Jun 4, 2025
4caacdd
docs: Update README to change domain area from CN to US for improved …
seymourtang Jun 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 43 additions & 41 deletions agora-rest-client-core/src/main/java/io/agora/rest/services/convoai/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,26 +8,25 @@ Agora's Conversational AI Engine redefines human-computer interaction, breaking

## Environment Setup

- Obtain Agora App ID -------- [Agora Console](https://console.agora.io/v2)
- Obtain Agora App ID -------- [Agora Console](https://console.agora.io/v2)

> - Click Create Application
>
> ![](../../../../../../../../../assets/imges/EN/create_app_1.png)
>
> - Select the type of application you want to create
>
> ![](../../../../../../../../../assets/imges/EN/create_app_2.png)
> - Click Create Application
>
> ![](../../../../../../../../../assets/imges/EN/create_app_1.png)
>
> - Select the type of application you want to create
>
> ![](../../../../../../../../../assets/imges/EN/create_app_2.png)

- Obtain App Certificate ----- [Agora Console](https://console.agora.io/v2)
- Obtain App Certificate ----- [Agora Console](https://console.agora.io/v2)

> In the project management page of the Agora Console, find your project and click Configure.
> ![](../../../../../../../../../assets/imges/EN/config_app.png)
> Click the copy icon under Primary Certificate to obtain the App Certificate for your project.
> ![](../../../../../../../../../assets/imges/EN/copy_app_cert.png)

- Enable Conversational AI Engine Service ----- [Enable Service](https://docs.agora.io/en/conversational-ai/get-started/manage-agora-account)
> ![](../../../../../../../../../assets/imges/EN/open_convo_ai.png)
> In the project management page of the Agora Console, find your project and click Configure.
> ![](../../../../../../../../../assets/imges/EN/config_app.png)
> Click the copy icon under Primary Certificate to obtain the App Certificate for your project.
> ![](../../../../../../../../../assets/imges/EN/copy_app_cert.png)

- Enable Conversational AI Engine Service ----- [Enable Service](https://docs.agora.io/en/conversational-ai/get-started/manage-agora-account)
> ![](../../../../../../../../../assets/imges/EN/open_convo_ai.png)

## API Definition

Expand All @@ -49,35 +48,36 @@ For more api details, please refer to the [API Documentation](https://docs.agora
credential(credential).
// Specify the region where the server is located. Options include CN, EU, AP, US.
// The client will automatically switch to use the best domain based on the configured region.
domainArea(DomainArea.CN).
domainArea(DomainArea.US).
// Specify the service region. Options include ChineseMainlandServiceRegion, GlobalServiceRegion.
// ChineseMainlandServiceRegion and GlobalServiceRegion are two different services.
serverRegion(ConvoAIServiceRegionEnum.CHINESE_MAINLAND).
serverRegion(ConvoAIServiceRegionEnum.GLOBAL).
build();

ConvoAIClient convoAIClient = ConvoAIClient.create(config);
```

### Create Conversational Agent
>

> Create a Conversational AI agent instance and join an RTC channel.

Parameters to set: LLM, TTS, and Agent related parameters.

Call the `join` method to create a conversational agent, using Bytedance TTS as an example:
Call the `join` method to create a conversational agent, using Microsoft TTS as an example:

```java
public static final String APP_ID = "<your appId>";
public static final String CNAME = "<your cname>";
public static final String AGENT_RTC_UID = "<your agent rtc uid>";
public static final String AGENT_RTC_TOKEN = "<your agent rtc token>";

public static final String LLM_URL = "<your llm url>";
public static final String LLM_API_KEY = "<your llm api key>";
public static final String LLM_MODEL = "<your llm model>";

public static final String TTS_BYTEDANCE_TOKEN = "<your bytedance tts token>";
public static final String TTS_BYTEDANCE_APP_ID = "<your bytedance tts app id>";
public static final String TTS_BYTEDANCE_CLUSTER = "<your bytedance tts cluster>";
public static final String TTS_BYTEDANCE_VOICE_TYPE = "<your bytedance tts voice type>";
public static final String TTS_MICROSOFT_TOKEN = "<your microsoft tts token>";
public static final String TTS_MICROSOFT_REGION = "<your microsoft tts region>";
public static final String TTS_MICROSOFT_VOICE_NAME = "<your microsoft tts voice name>";

// Start agent
String name = APP_ID + ":" + CNAME;
Expand Down Expand Up @@ -124,17 +124,15 @@ Call the `join` method to create a conversational agent, using Bytedance TTS as
.greetingMessage("Hello,how can I help you?")
.build())
.ttsPayload(JoinConvoAIReq.TTSPayload.builder()
.vendor(JoinConvoAIReq.TTSVendorEnum.BYTEDANCE)
.params(JoinConvoAIReq.BytedanceTTSVendorParams.builder().
token(TTS_BYTEDANCE_TOKEN).
cluster(TTS_BYTEDANCE_CLUSTER).
voiceType(TTS_BYTEDANCE_VOICE_TYPE).
appId(TTS_BYTEDANCE_APP_ID).
speedRatio(1.0F).
volumeRatio(1.0F).
pitchRatio(1.0F).
emotion("happy").
build())
.vendor(JoinConvoAIReq.TTSVendorEnum.MICROSOFT)
.params(JoinConvoAIReq.MicrosoftTTSVendorParams.builder()
.key(TTS_MICROSOFT_TOKEN)
.region(TTS_MICROSOFT_REGION)
.voiceName(TTS_MICROSOFT_VOICE_NAME)
.speed(1.0F)
.volume(70F)
.sampleRate(24000)
.build())
.build())
.vadPayload(JoinConvoAIReq.VADPayload.builder()
.interruptDurationMs(160)
Expand Down Expand Up @@ -169,7 +167,8 @@ Call the `join` method to create a conversational agent, using Bytedance TTS as
> Stop the conversational agent and leave the RTC channel.

Parameters to set:
- AgentId returned by the `join` interface

- AgentId returned by the `join` interface

```java
// Stop the agent
Expand All @@ -188,8 +187,9 @@ Parameters to set:
> Currently, only the Token information of a running conversational agent can be updated.

Parameters to set:
- AgentId returned by the `join` interface
- Token to be updated

- AgentId returned by the `join` interface
- Token to be updated

```java
// Update agent
Expand All @@ -214,7 +214,8 @@ Parameters to set:
> Query the status of the conversational agent.

Parameters to set:
- AgentId returned by the `join` interface

- AgentId returned by the `join` interface

```java
// Query agent
Expand All @@ -237,13 +238,13 @@ Parameters to set:
logger.info("Query the agent successfully, queryConvoAIRes:{}", queryConvoAIRes);
```


## Retrieves a list of agents

> Retrieves a list of agents that meet the specified criteria.

Parameters to set:
- AgentId returned by the `join` interface

- AgentId returned by the `join` interface

```java
// List agent
Expand All @@ -270,4 +271,5 @@ Parameters to set:
```

## Error Codes and Response Status Codes Handling

For specific business response codes, please refer to the [Business Response Codes](https://docs.agora.io/en/conversational-ai/rest-api/reference) documentation.
71 changes: 39 additions & 32 deletions agora-rest-client-core/src/main/java/io/agora/rest/services/convoai/README_ZH.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,40 @@
# 对话式 AI 引擎服务

[English](./README.md) | 简体中文
[English](./README.md) | 简体中文

## 服务概述

声网对话式 AI 引擎重新定义了人机交互界面，突破了传统文字交互，实现了高拟真、自然流畅的实时语音对话，让 AI 真正“开口说话”。适用于智能助手、情感陪伴、口语陪练、智能客服、智能硬件、沉浸式游戏 NPC 等创新场景。

## 环境准备

- 获取声网App ID -------- [声网Agora - 文档中心 - 如何获取 App ID](https://docs.agora.io/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#%E8%8E%B7%E5%8F%96-app-id)
- 获取声网 App ID -------- [声网 Agora - 文档中心 - 如何获取 App ID](https://docs.agora.io/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#%E8%8E%B7%E5%8F%96-app-id)

> - 点击创建应用
>
> ![](../../../../../../../../../assets/imges/CN/create_app_1.png)
>
> - 选择你要创建的应用类型
>
> ![](../../../../../../../../../assets/imges/CN/create_app_2.png)
> - 点击创建应用
>
> ![](../../../../../../../../../assets/imges/CN/create_app_1.png)
>
> - 选择你要创建的应用类型
>
> ![](../../../../../../../../../assets/imges/CN/create_app_2.png)

- 获取App 证书 ----- [声网Agora - 文档中心 - 获取 App 证书](https://docs.agora.io/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#%E8%8E%B7%E5%8F%96-app-%E8%AF%81%E4%B9%A6)
- 获取 App 证书 ----- [声网 Agora - 文档中心 - 获取 App 证书](https://docs.agora.io/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#%E8%8E%B7%E5%8F%96-app-%E8%AF%81%E4%B9%A6)

> 在声网控制台的项目管理页面，找到你的项目，点击配置。
> ![](../../../../../../../../../assets/imges/CN/config_app.png)
> 点击主要证书下面的复制图标，即可获取项目的 App 证书。
> ![](../../../../../../../../../assets/imges/CN/copy_app_cert.png)
> 在声网控制台的项目管理页面，找到你的项目，点击配置。
> ![](../../../../../../../../../assets/imges/CN/config_app.png)
> 点击主要证书下面的复制图标，即可获取项目的 App 证书。
> ![](../../../../../../../../../assets/imges/CN/copy_app_cert.png)

- 启用会话式AI引擎服务 ----- [启用服务](https://doc.shengwang.cn/doc/convoai/restful/get-started/enable-service)
> ![](../../../../../../../../../assets/imges/CN/open_convo_ai.png)
- 启用会话式 AI 引擎服务 ----- [启用服务](https://doc.shengwang.cn/doc/convoai/restful/get-started/enable-service)
> ![](../../../../../../../../../assets/imges/CN/open_convo_ai.png)

## API定义
## API 定义

更多API详情，请参考 [API文档](https://doc.shengwang.cn/api-ref/convoai/java/java-api/overview)
更多 API 详情，请参考 [API 文档](https://doc.shengwang.cn/api-ref/convoai/java/java-api/overview)

## API调用示例
## API 调用示例

### 初始化会话式AI引擎客户端
### 初始化会话式 AI 引擎客户端

```java
public static final String APP_ID = "<your appId>";
Expand All @@ -58,14 +58,16 @@
```

### 创建对话式智能体
>
> 创建对话式 AI 智能体实例并加入RTC频道。

需要设置的参数：LLM、TTS和代理相关参数。
> 创建对话式 AI 智能体实例并加入 RTC 频道。

调用`join`方法创建会话代理，以使用字节跳动TTS为例：
需要设置的参数：LLM、TTS 和代理相关参数。

调用`join`方法创建会话代理，以使用字节跳动 TTS 为例：

```java
public static final String APP_ID = "<your appId>";
public static final String CNAME = "<your cname>";
public static final String AGENT_RTC_UID = "<your agent rtc uid>";
public static final String AGENT_RTC_TOKEN = "<your agent rtc token>";

Expand Down Expand Up @@ -165,10 +167,11 @@

### 停止对话式智能体

> 停止对话式智能体并离开RTC频道。
> 停止对话式智能体并离开 RTC 频道。

需要设置的参数：
- `join`接口返回的AgentId

- `join`接口返回的 AgentId

```java
// Stop the agent
Expand All @@ -184,11 +187,12 @@

### 更新智能体配置

> 目前只能更新正在运行的智能体的Token信息。
> 目前只能更新正在运行的智能体的 Token 信息。

需要设置的参数：
- `join`接口返回的AgentId
- 要更新的Token

- `join`接口返回的 AgentId
- 要更新的 Token

```java
// Update agent
Expand All @@ -213,7 +217,8 @@
> 查询智能体的状态。

需要设置的参数：
- `join`接口返回的AgentId

- `join`接口返回的 AgentId

```java
// Query agent
Expand All @@ -236,12 +241,13 @@
logger.info("Query the agent successfully, queryConvoAIRes:{}", queryConvoAIRes);
```


## 检索智能体列表

> 按照条件检索智能体列表。

需要设置的参数：
- `join`接口返回的AgentId

- `join`接口返回的 AgentId

```java
// List agent
Expand All @@ -268,4 +274,5 @@
```

## 错误代码和响应状态代码处理

有关具体的业务响应代码，请参考 [业务响应代码](https://doc.shengwang.cn/doc/convoai/restful/api/response-code) 文档。
36 changes: 6 additions & 30 deletions examples/convoai/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,31 +21,6 @@ You can find the relevant parameters in the [Conversational AI Service Documenta

When choosing different TTS providers, you need to configure additional environment variables. The currently supported TTS providers are:

### bytedance

```bash
export CONVOAI_TTS_BYTEDANCE_TOKEN=<Your tts bytedance token>
export CONVOAI_TTS_BYTEDANCE_APP_ID=<Your tts bytedance app id>
export CONVOAI_TTS_BYTEDANCE_CLUSTER=<Your tts bytedance cluster>
export CONVOAI_TTS_BYTEDANCE_VOICE_TYPE=<Your tts bytedance voice type>
```

### tencent

```bash
export CONVOAI_TTS_TENCENT_APP_ID=<Your tts tencent app id>
export CONVOAI_TTS_TENCENT_SECRET_ID=<Your tts tencent secret id>
export CONVOAI_TTS_TENCENT_SECRET_KEY=<Your tts tencent secret key>
```

### minimax

```bash
export CONVOAI_TTS_MINIMAX_GROUP_ID=<Your tts minimax group id>
export CONVOAI_TTS_MINIMAX_GROUP_KEY=<Your tts minimax group key>
export CONVOAI_TTS_MINIMAX_GROUP_MODEL=<Your tts minimax group model>
```

### microsoft

```bash
Expand Down Expand Up @@ -73,11 +48,12 @@ make install
Then, in the current module, execute the following commands to experience different scenarios of the `ConvoAI` example:

```bash
mvn exec:java -Dexec.mainClass="io.agora.rest.examples.convoai.Main" -Dexec.args="--ttsVendor=<ttsVendor> --serviceRegion=<serviceRegion>"
mvn exec:java -Dexec.mainClass="io.agora.rest.examples.convoai.Main" -Dexec.args="--ttsVendor=<ttsVendor> --serviceRegion=global"
```

`ttsVendor` represents different TTS providers. Choose the appropriate TTS provider based on your requirements.
`serviceRegion` represents the chosen service region. The currently supported service regions are:
* `chineseMainland`
* `global`
`ttsVendor` represents different TTS providers.

- `microsoft`
- `elevenLabs`

Choose the appropriate TTS provider based on your requirements.
Loading