> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 快速开始

本指南将介绍如何创建首个对话式智能体。这将为构建适合业务场景的对话工作流打下基础。

> **Tip**
>
> 使用 [ElevenLabs agents skill](https://github.com/elevenlabs/skills/tree/main/agents)，通过 AI 编程助手构建和管理语音智能体：
>
> ```bash
> npx skills add elevenlabs/skills --skill agents
> ```
>
> 你还可以将[托管 MCP 服务器](/docs/zh/eleven-agents/operate/hosted-mcp)连接到 Claude 或其他 MCP 客户端，通过自然语言创建和管理智能体。

## 开始使用

可通过 [ElevenAgents 控制台](https://elevenlabs.io/app/agents)、[ElevenLabs API](/docs/zh/api-reference/introduction)、[Agents CLI](/docs/zh/eleven-agents/operate/cli)或[托管 MCP 服务器](/docs/zh/eleven-agents/operate/hosted-mcp)管理 ElevenLabs Agents。

![ElevenLabs Agents](/docs/_fern-img/62ad20de44cee44a439b138d56764c801c4eb939cf3b0f167f594d5c6a6895fb.webp)

## 创建首个智能体

本快速入门指南将通过 API 或网页控制台创建智能体。接下来，你可以将智能体嵌入网站，或通过 ElevenLabs 控制台进行测试。

#### 通过网页控制台构建智能体

本指南将创建一个对话式支持助手，能够回答有关产品、文档或服务的问题。可将该助手嵌入网站或应用，为客户提供实时支持。

![ElevenLabs Agents](/docs/_fern-img/62ad20de44cee44a439b138d56764c801c4eb939cf3b0f167f594d5c6a6895fb.webp)

#### 登录 ElevenLabs

前往 [elevenlabs.io](https://elevenlabs.io/app/sign-up)，登录或创建账户。

#### 创建新助手

在 **ElevenLabs 控制台**中，输入名称并选择 `Blank template` 选项，创建新助手。

![控制台](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/61b0e1df291ea587a8ff3e116579a47f66d48c74b24f44cfcd4804a568eb0a9d/assets/images/conversational-ai/assistant-create-flow.gif)

#### 配置助手行为

前往 **Agent** 标签页，配置助手行为。设置以下内容：

#### 首条消息

这是用户开始对话时，助手首先会朗读的消息。

**`首条消息`**

```plaintext 首条消息
Hi, this is Alexis from <company name> support. How can I help you today?
```

#### 系统提示词

此提示词用于指导助手的行为、任务和个性。

请根据公司信息自定义以下示例：

**`系统提示词`**

```plaintext 系统提示词
You are a friendly and efficient virtual assistant for [Your Company Name]. Your role is to assist customers by answering questions about the company's products, services, and documentation. You should use the provided knowledge base to offer accurate and helpful responses.

Tasks:
- Answer Questions: Provide clear and concise answers based on the available information.
- Clarify Unclear Requests: Politely ask for more details if the customer's question is not clear.

Guidelines:
- Maintain a friendly and professional tone throughout the conversation.
- Be patient and attentive to the customer's needs.
- If unsure about any information, politely ask the customer to repeat or clarify.
- Avoid discussing topics unrelated to the company's products or services.
- Aim to provide concise answers. Limit responses to a couple of sentences and let the user guide you on where to provide more detail.
```

#### 添加知识库

前往 **Knowledge Base** 部分，为助手提供有关业务的背景信息。

可在此上传相关文档和外部资源链接：

* 添加文档、常见问题和其他资源，帮助助手回复客户咨询。
* 保持知识库更新，确保助手提供准确且最新的信息。

接下来为助手配置音色。

#### 选择音色

在 **Voice** 标签页中，从[声音库](https://elevenlabs.io/voice-library)选择最适合助手的音色：

![音色设置](/docs/_fern-img/14aad328f468daafa9ec95d3b7a55489a8cb1a34869368020e05b207c9b0360a.webp)

> **Note**
>
> 使用更高质量的音色、模型和 LLM 可能会延长响应时间。请根据助手的预期使用场景，平衡质量与延迟，以获得最佳客户体验。

#### 测试助手

点击 **Test AI agent** 按钮，开始与助手对话。

配置评估标准和数据收集，以分析对话并提升助手表现。

#### 配置评估标准

在助手设置中前往 **Analysis** 标签页，定义用于评估对话的自定义标准。

![分析设置](/docs/_fern-img/fee8bc444d5436c71eae3829b9ec8d5cdb6a57c4d4efe6483d7bfed2b066e438.webp)

每份对话记录都会传递给 LLM，以验证是否达成特定目标。结果将为 `success`、`failure` 或 `unknown`，并附有说明结果选择依据的理由。

添加一个名为 `solved_user_inquiry` 的评估标准：

**`提示词`**

```plaintext 提示词
The assistant was able to answer all of the queries or redirect them to a relevant support channel.

Success Criteria:
- All user queries were answered satisfactorily.
- The user was redirected to a relevant support channel if needed.
```

#### 配置数据收集

在 **Data collection** 部分，配置要从每段对话中提取的详细信息。

点击 **Add item** 并进行以下配置：

1. **数据类型：** 选择“string”
2. **标识符：** 为此数据点输入唯一标识符：`user_question`
3. **说明：** 向 LLM 提供详细指引，说明如何从记录中提取特定数据：

**`提示词`**

```plaintext 提示词
Extract the user's questions & inquiries from the conversation.
```

> **Tip**
>
> 以客户身份测试助手。提出问题、评估回复，并调整提示词，直到你满意其表现。

#### 查看对话历史

在 **Call history** 标签页中查看每段对话的评估结果和收集的数据。

![对话历史](/docs/_fern-img/fd517a080ba2c0d678c1ce34ea79afbd0dad764a19da43ca045a1c29b693ee48.webp)

> **Tip**
>
> 定期查看对话历史，识别常见问题和模式。

新创建的智能体可通过多种方式测试，最快的方式是使用 [ElevenLabs 控制台](https://elevenlabs.io/app/agents)。

> **Info**
>
> 网页控制台底层使用 [React SDK](/docs/zh/eleven-agents/libraries/react) 来处理实时对话。

如果想在自己的网站中快速测试智能体，可以使用 Agent 小组件。只需将以下 HTML 代码段粘贴到网站中，并将 `agent-id` 替换为智能体 ID。

```html
<elevenlabs-convai agent-id="agent-id"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
```

#### 通过 CLI 构建智能体

#### 安装 CLI

**`Homebrew（macOS）`**

```bash title="Homebrew（macOS）"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop（Windows）`**

```powershell title="Scoop（Windows）"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> 正在使用 AI 编程助手？在项目中运行 `elevenlabs generate-skills`，即可将每个命令组的
> `SKILL.md` 写入 `skills/`，无需粘贴文档，助手就能了解 CLI 的完整功能。使用 `--output-dir`
> 可将其放到其他位置。该命令会读取 CLI 内置的 API 定义，因此无需 API 密钥且可离线运行——还能始终与已安装的 CLI 版本保持同步。

#### 初始化新项目

```bash
elevenlabs agents init
```

这会创建包含配置目录和注册表文件的项目结构。

#### 通过 ElevenLabs 身份验证

[在控制台中创建 API 密钥](https://elevenlabs.io/app/settings/api-keys)，用于安全地[使用 CLI](/docs/zh/api-reference/authentication)。

然后运行以下命令，通过 ElevenLabs 身份验证：

```bash
elevenlabs auth login
```

这将打开浏览器窗口，通过 OAuth 完成身份验证。CLI 会验证凭据并安全存储。

#### 创建智能体

使用助手模板创建首个智能体：

```bash
elevenlabs agents add "My Assistant" --template assistant
```

#### 推送到 ElevenLabs 平台

```bash
elevenlabs agents push
```

这会将本地智能体配置上传至 ElevenLabs 平台。

#### 测试智能体

新创建的智能体可通过多种方式测试，最快的方式是使用 [ElevenLabs 控制台](https://elevenlabs.io/app/agents)。在控制台中选择智能体，然后点击 **Test AI agent** 按钮。

> **Info**
>
> 网页控制台底层使用 [React SDK](/docs/zh/eleven-agents/libraries/react) 来处理实时对话。

如果想在自己的网站中快速测试智能体，可以使用 Agent 小组件。使用 CLI 生成 HTML 代码段：

```bash
elevenlabs agents widget embed <agent_id>
```

推送时，智能体 ID 会记录在 `agents.json` 中，`elevenlabs agents status` 也会列出该 ID。此命令会输出 HTML 代码段，可直接粘贴到网站中。

#### 通过 API 构建智能体

#### 创建 API 密钥

[在控制台中创建 API 密钥](https://elevenlabs.io/app/api/api-keys)，用于安全地[访问 API](/docs/zh/api-reference/authentication)。

将密钥作为受管理的机密信息存储，并根据偏好，通过 `.env` 文件将其作为环境变量传递给 SDK，或直接写入应用配置。

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

#### 安装 SDK

#### SDK

我们还会使用 `dotenv` 库从环境变量加载 API 密钥。

```python
pip install elevenlabs
pip install python-dotenv
```

```typescript
npm install @elevenlabs/elevenlabs-js
npm install dotenv
```

#### CLI

安装 ElevenLabs CLI。推荐使用 Homebrew（macOS）和 Scoop（Windows）。

**`Homebrew（macOS）`**

```bash title="Homebrew（macOS）"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop（Windows）`**

```powershell title="Scoop（Windows）"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> 正在使用 AI 编程助手？在项目中运行 `elevenlabs generate-skills`，即可将每个命令组的
> `SKILL.md` 写入 `skills/`，无需粘贴文档，助手就能了解 CLI 的完整功能。使用 `--output-dir`
> 可将其放到其他位置。该命令会读取 CLI 内置的 API 定义，因此无需 API 密钥且可离线运行——还能始终与已安装的 CLI 版本保持同步。

然后进行身份验证——这会打开浏览器以授权 CLI：

```bash
elevenlabs auth login
```

#### 创建智能体

根据所用语言，创建名为 `create_agent.py` 或 `createAgent.mts` 的新文件，并添加以下代码：

```python maxLines=0
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
import os
load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

prompt = """
You are a friendly and efficient virtual assistant for [Your Company Name].
Your role is to assist customers by answering questions about the company's products, services,
and documentation. You should use the provided knowledge base to offer accurate and helpful responses.

Tasks:
- Answer Questions: Provide clear and concise answers based on the available information.
- Clarify Unclear Requests: Politely ask for more details if the customer's question is not clear.

Guidelines:
- Maintain a friendly and professional tone throughout the conversation.
- Be patient and attentive to the customer's needs.
- If unsure about any information, politely ask the customer to repeat or clarify.
- Avoid discussing topics unrelated to the company's products or services.
- Aim to provide concise answers. Limit responses to a couple of sentences and let the user guide you on where to provide more detail.
"""

response = elevenlabs.conversational_ai.agents.create(
    name="My voice agent",
    tags=["test"], # List of tags to help classify and filter the agent
    conversation_config={
        "tts": {
            "voice_id": "aMSt68OGf4xUZAnLpTU8",
            "model_id": "eleven_flash_v2"
        },
        "agent": {
            "first_message": "Hi, this is Rachel from [Your Company Name] support. How can I help you today?",
            "prompt": {
                "prompt": prompt,
            }
        }
    }
)

print("Agent created with ID:", response.agent_id)
```

```typescript maxLines=0
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

const prompt = `
    You are a friendly and efficient virtual assistant for [Your Company Name].
    Your role is to assist customers by answering questions about the company's products, services,
    and documentation. You should use the provided knowledge base to offer accurate and helpful responses.

    Tasks:
    - Answer Questions: Provide clear and concise answers based on the available information.
    - Clarify Unclear Requests: Politely ask for more details if the customer's question is not clear.

    Guidelines:
    - Maintain a friendly and professional tone throughout the conversation.
    - Be patient and attentive to the customer's needs.
    - If unsure about any information, politely ask the customer to repeat or clarify.
    - Avoid discussing topics unrelated to the company's products or services.
    - Aim to provide concise answers. Limit responses to a couple of sentences and let the user guide you on where to provide more detail.
`;

const agent = await elevenlabs.conversationalAi.agents.create({
    name: "My voice agent",
    tags: ["test"], // List of tags to help classify and filter the agent
    conversationConfig: {
        tts: {
            voiceId: "aMSt68OGf4xUZAnLpTU8",
            modelId: "eleven_flash_v2",
        },
        agent: {
            firstMessage: "Hi, this is Rachel from [Your Company Name] support. How can I help you today?",
            prompt: {
                prompt,
            }
        },
    },
});

console.log(`Agent created with ID: ${agent.agentId}`);
```

> **Note**
>
> 上述创建的智能体会带有 `"test"` 标签，可用于分类和筛选智能体。例如，可区分测试智能体与生产智能体。

#### 运行代码

```python
python create_agent.py
```

```typescript
npx tsx createAgent.mts
```

上述代码会生成一个具有基础设置的智能体，并在控制台中输出智能体 ID。将在后续步骤中自定义该智能体。

#### 测试智能体

新创建的智能体可通过多种方式测试，最快的方式是使用 [ElevenLabs 控制台](https://elevenlabs.io/app/agents)。在控制台中选择智能体，然后点击 **Test AI agent** 按钮。

> **Info**
>
> 网页控制台底层使用 [React SDK](/docs/zh/eleven-agents/libraries/react) 来处理实时对话。

如果想在自己的网站中快速测试智能体，可以使用 Agent 小组件。只需将以下 HTML 代码段粘贴到网站中，并将 `agent-id` 替换为智能体 ID。

```html
<elevenlabs-convai agent-id="agent-id"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
```

查看 SDK 标签页，了解如何使用提供的 SDK 将智能体嵌入网站或应用。

## 后续步骤

完成本快速入门指南后，可通过集成以下功能提升智能体效果：

* [知识库](/docs/zh/eleven-agents/customization/knowledge-base)，为其提供特定领域的信息。
* [工具](/docs/zh/eleven-agents/customization/tools)，让它能够代表你执行任务。
* [身份验证](/docs/zh/eleven-agents/customization/authentication)，限制对特定对话的访问。
* [成功评估](/docs/zh/eleven-agents/customization/agent-analysis/success-evaluation)，分析对话并提升其表现。
* [数据收集](/docs/zh/eleven-agents/customization/agent-analysis/data-collection)，收集对话数据并提升其表现。
* [对话保留](/docs/zh/eleven-agents/customization/privacy/retention)，查看对话历史并提升其表现。