> 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.

# 自由格式流程

## 概述

自由格式流程使用简明自然的语言描述一项任务。智能体会理解指令，并根据具体情况调整措辞和顺序。自由格式流程可以调用工具（包括结束通话等系统工具）、查询知识库文档，以及串联其他流程。

## 何时使用自由格式流程

当智能体可以根据具体情况调整措辞和顺序，而你希望用自然语言快速编写时，请使用自由格式流程。有关它与结构化流程、workflow 和系统提示词的区别，请参阅[何时使用流程](/docs/zh/eleven-agents/customization/procedures#when-to-use-procedures)。

## 流程结构

以下是编辑器中的退款流程：

![退款流程
示例](/docs/_fern-img/e1264b7a4f94403453087d30ef0894e72d412ba69378e6b8cb1b675e53e887b7.webp)

一个流程包含两个主要部分：触发条件和内容。两者都可以包含对其他资源的内联引用，在上方截图中显示为带扳手图标的标签。每个流程还有一个显示在控制台中的名称。

### 名称

用于在控制台中识别流程的简短标签。名称永远不会发送给 LLM，因此不会影响智能体行为。

### 触发条件

描述智能体何时应使用此流程，例如 *当用户要求退款订单时*。

仅在创建[子流程](#sub-procedures)时将触发条件留空。

### 内容

以 Markdown 编写的流程正文。内容描述智能体应执行的操作：提问、查询订单、调用工具或结束通话。它可以是一系列编号步骤，也可以是针对该情况的通用指引。每个步骤或指引可以是一句话（*询问用户的订单 ID*），也可以是一段简短文字，说明做什么及原因。

对有顺序的操作使用编号步骤，在单个步骤内的要求或子项目使用项目符号。

### 内联引用

流程可以内联引用不同类型的资源：

* 工具（例如查询订单、扣款、结束通话、转接人工客服）
* 知识库文档
* 其他流程

只要某个步骤需要智能体使用工具、知识库文档或其他流程，就应使用内联引用。引用会自动将资源附加到流程中，供智能体使用。普通文字提及（例如 *在这里使用计算器工具*）同样有效，但前提是资源已附加到智能体。

在触发条件或内容中输入 `/`，然后从斜杠菜单中选择资源，即可插入引用。引用会在编辑器中显示为可点击标签。点击标签可打开对应资源并确认其配置。

通过 API 编写自由格式内容时，请使用以下语法插入引用：

```text focus={1-5}
[tool id="tool_abc123"]
[kb id="kb_abc123"]
[procedure id="agtprc_abc123"]
[system_tool id="end_call"]
{{customer_id}}
```

内联流程引用必须使用同一智能体中的流程。有关智能体范围和重复行为，请参阅[限制](/docs/zh/eleven-agents/customization/procedures#limitations)。

触发条件中的引用可让流程根据资源输出触发，例如 \_当 `get_user` 返回层级 'gold' 时 \_。内容中的引用则会指示智能体在该步骤调用或查询资源。

流程中引用的知识库文档始终使用 `auto` [使用模式](/docs/zh/eleven-agents/customization/knowledge-base#how-your-agent-uses-knowledge)：当智能体启用 RAG 时，智能体会检索相关段落，而不是将完整文档放入提示词。如果该文档也附加到了智能体，则会改为使用智能体为该文档设置的使用模式；因此，如需将完整文本保留在提示词中，请以 `prompt` 使用模式将其附加到智能体。

![流程编辑器中的斜杠菜单](/docs/_fern-img/8625ffec0f5584619e6ccb97720fd86f2e8d3cd0061308ad87b57f176e5535e3.webp)

如果之后删除了引用的资源，或者账户失去了访问权限，标签将显示为损坏。编辑器顶部的 **错误** 徽章会列出这些引用：如果资源已不存在，则标记为 *无效*；如果资源存在但账户无权访问，则标记为 *不可用*。打开徽章可查看受影响的步骤，并修复或移除引用。

![列出无效
引用的错误对话框](/docs/_fern-img/e9ec6b19be2992da80a726883baf53265a5d5b38621373cd7e60375c944674cd.webp)

## 子流程

子流程的触发条件为空。智能体只能从引用它的其他流程中运行它。

使用子流程可在同一智能体内[共享步骤](#composing-procedures)，并减少同时可用的流程数量。为入口流程设置触发条件，在其内容中引用相关子流程，并将子流程的触发条件留空。

升级子流程可以包含将对话转交给人工客服的步骤。可从退款和取消流程中引用它，并将其触发条件留空。智能体可以作为任一流程的步骤进行升级，但在这些流程之外，该子流程仍不可用。

## 从文档导入

你可以基于现有标准操作流程（SOP）快速开始。在流程列表的 **+** 菜单中选择 **从 SOP 导入**，然后上传文件。

支持格式：`PDF`、`DOCX`、`TXT`、`MD`、`HTML`、`EPUB`。文件必须不超过 20 MB。

导入器会分析文档，识别最多 10 个不同流程，并为每个流程创建草稿，其中包含生成的名称、触发条件和内容。打开每个草稿进行完善。如果文档包含超过 10 个 SOP，请在上传前将其拆分为较小文件。

![上传 SOP 对话框](/docs/_fern-img/716601fc90dea757e23971e5aabe063e6a66fc0f75878247dc9f1fc3011f5197.webp)

## 管理自由格式流程

#### 通过控制台创建

在[控制台](https://elevenlabs.io/app/agents)中打开智能体，然后选择 **流程**。
使用 **+** 创建自由格式流程。添加触发条件，并在内容编辑器中编写指令，
然后发布智能体更改。

#### 通过 API 管理

自由格式流程在 `content` 中存储 Markdown。

### 前提条件

* 在 `ELEVENLABS_API_KEY` 环境变量中设置 ElevenLabs API 密钥。
* 目标 `agent_id` 和 `branch_id`。有关分支操作，请参阅[智能体版本控制](/docs/zh/eleven-agents/operate/versioning)。
* `elevenlabs` Python 包或 `@elevenlabs/elevenlabs-js` JavaScript 包的版本为 `2.60.0` 或更高。

流程草稿按[用户和 分支](/docs/zh/eleven-agents/operate/versioning#drafts)区分。发布会将流程
更改保存为该分支上的新智能体版本，不会影响其他用户的草稿。

### 创建草稿

```python focus={1,5-15}
from elevenlabs import CreateProcedureRequestModel, ElevenLabs

elevenlabs = ElevenLabs()

procedure = elevenlabs.conversational_ai.agents.procedures.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
    request=CreateProcedureRequestModel(
        name="Refund request",
        type="free_form",
        trigger="When the user asks to refund, return, or get money back for an order",
        content="Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].",
    ),
)

print(procedure.procedure_id)
```

```typescript focus={5-15}
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const procedure = await elevenlabs.conversationalAi.agents.procedures.create(
  "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
  {
    name: "Refund request",
    type: "free_form",
    trigger: "When the user asks to refund, return, or get money back for an order",
    content: "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].",
  }
);

console.log(procedure.procedureId);
```

```bash focus={1-8}
curl -X POST "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t/procedures" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund request",
    "type": "free_form",
    "trigger": "When the user asks to refund, return, or get money back for an order",
    "content": "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"]."
  }'
```

响应中包含新的 `procedure_id`。要更新草稿，请调用
`PATCH /procedures/{procedure_id}/draft`，并传入 `name`、`content`、`type` 和明确的
`trigger`。

对入口流程使用非空 `trigger`。对于
[子流程](#sub-procedures)，使用空字符串。

### 发布更改

更新分支上的智能体，将自由格式流程草稿发布为新版本。
请求无需正文参数；发布会按当前草稿内容执行。

```python focus={5-8}
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
)
```

```typescript focus={5-7}
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  branchId: "agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
});
```

```bash focus={1-5}
curl -X PATCH \
  "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6?branch_id=agtbranch_0901k4aafjxxfxt93gd841r7tv5t" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

有关删除草稿和丢弃行为，请参阅[管理流程](/docs/zh/eleven-agents/customization/procedures#manage-procedures)；
有关完整端点架构，请参阅
[流程 API 参考文档](/docs/zh/api-reference/agents/procedures/)。

## 最佳实践

> **Tip**
>
> 智能体需要根据触发条件选择正确的流程，并遵循其中内容。随着流程数量增加，能力更强的
> 模型能更可靠地完成这些操作。有关选项，请参阅
> [模型](/docs/zh/eleven-agents/customization/llm)。

要写好流程，需要同时写好两部分：在应触发时运行流程的触发条件，以及智能体能够遵循的内容。

### 迭代优化流程

建议从小处开始，并使用[智能体测试](/docs/zh/eleven-agents/customization/agent-testing)，在进行下一项更改前检查每次更改。

#### 编写简短流程

编写触发条件和简短内容。仅当测试显示智能体
需要更多指令时，再扩展内容。

#### 添加触发条件测试

为应启动流程的请求，以及不应启动流程的类似请求
创建模拟测试。大多数失败都来自触发条件，因此此类测试应多于完整
模拟测试。

#### 添加完整模拟

创建一个运行完整流程并检查结果的模拟测试。

#### 运行测试并修复失败

测试失败时，修复触发条件或内容，然后重新运行所有测试。

> **Tip**
>
> 若要快速迭代触发条件，可创建一个模拟测试，让其[聊天 历史](/docs/zh/eleven-agents/customization/agent-testing#simulation-testing)以用户的
> 请求结束，并将 **最大对话轮数** 设为 `1`。智能体只回复一次，这足以
> 判断请求是否启动了正确流程，并且每次运行都很短。将成功
> 标准写为 *智能体启动了退款流程*。如果没有聊天历史，带有首条
> 消息的智能体会把唯一一轮用在问候上，测试就不会检查任何内容。

当测试或实际对话失败时，请寻找背后的错误类型。如果智能体说错了话，添加 *不要这样说* 只能修复一次对话。请搜索过去的对话中是否有类似失败，并编写一条能涵盖所有情况的指令。原因也可能出在知识库或智能体配置中。[Architect](/docs/zh/eleven-agents/operate/architect) 可以完成此搜索：打开失败的对话，选择 **Architect**，并要求它查找类似失败并提出修复方案。Architect 还可以将对话转为测试。

### 编写触发条件

#### 让触发条件具体且互不重叠

重叠或模糊的触发条件会导致运行错误流程。相比 *当用户询问账户问题时*，应优先使用 \_当用户要求
取消订阅时 \_。

#### 从用户视角编写

描述用户的请求，而不是智能体应做什么。以智能体
操作为表述的触发条件可靠性较低。相比 \_取消
用户的订阅 \_，应优先使用 \_当用户要求取消订阅时 \_。

#### 涵盖用户的实际表达方式

当用户换一种表达方式时，过于狭窄的触发条件可能会遗漏真实请求。请包含
用户可能说出的变体。相比 *当用户请求退款时*，*当用户要求退款、退货或取回订单款项时*
的运行可靠性更高。通过[搜索过去 对话](/docs/zh/eleven-agents/customization/agent-analysis/smart-search)了解用户如何
表达请求。

#### 在相关流程之间交接

用户有时会在流程进行到一半时改变请求，仅靠触发条件可能无法
启动正确流程。对于过去对话中经常出现的切换，请在第一个流程内容中添加
对另一个流程的内联引用。例如，编写 \_如果用户想要
退款而非换货，则运行 \_，后接退款流程的内联引用。如果大多数流程都需要交接，
应让触发条件更有区分度。

### 编写内容

#### 使用祈使句

将步骤写成对智能体的指令：*查询客户的上一笔订单*，而不是 \_你
应该查询客户的上一笔订单 \_。直接指令比
建议更容易遵循。

#### 说明步骤为何重要

推理可以泛化到流程未列举的边缘情况。一句简短的 *因为需要
订单 ID 才能退款* 有助于智能体处理步骤未预料到的情况。
如果一句解释即可达到同样效果，请避免全大写的“必须”和僵硬脚本。

#### 说明该做什么，而非避免什么

描述你想要的行为。*如果找不到订单，请让用户确认订单
ID* 比 *不要编造订单详情* 效果更好。对于代价高昂的错误，也请添加
[护栏](/docs/zh/eleven-agents/best-practices/guardrails)。

#### 顺序重要时使用步骤

当智能体必须按固定顺序执行操作时，编号步骤会有所帮助。对于需要判断的情况，几句
指引通常效果更好，尤其是搭配能力更强的模型时。

#### 将事实放在知识库中

流程描述智能体在某种情况下应做什么。价格、套餐详情或营业时间等
具体信息应放在[知识 库](/docs/zh/eleven-agents/customization/knowledge-base)中。请从需要这些信息的
流程中引用该文档。例如，不要在流程中列出每个套餐的价格，
而应编写 *引用以下文档中的价格*，后接定价文档的内联引用。

### 组合流程

#### 每种情况编写一个流程

如果一种情况被拆分为多个狭窄流程，智能体需要从更多触发条件中
选择，也更容易启动错误流程。如果两个流程会因相同
请求启动，请将它们合并。超过约 3,000 个字符的内容通常涵盖了不止一种
情况。

#### 将共享步骤提取为子流程

如果多个流程中出现相同步骤（验证客户身份、查询
订单、升级至人工客服），请将其提取为[子流程](#sub-procedures)，并通过斜杠菜单从
每个需要它的流程中引用。将共享步骤维护在同一位置，
可确保每个使用它们的流程保持一致。

#### 将子流程用于响应式操作

对于仅应在其他流程请求时运行的操作（如身份验证或升级），
请使用子流程。由于没有触发条件，它不会在对话开始时与入口
流程竞争。更少的触发条件选项可让路由更聚焦。

#### 从使用工具的流程中引用工具

应从使用工具的流程中引用它，而不是将它附加到整个智能体。这样，
该工具就不会出现在无关对话中。在自由格式流程中，工具
仅在该流程属于最近启动的 5 个流程之一时可用，因此也要在
触发条件中提及工具的任务，例如 *或当你需要查询订单时*。请参阅
[限制](/docs/zh/eleven-agents/customization/procedures#limitations)。

#### 将全局行为放在系统提示词中

语气、身份、拒绝策略和护栏应放在[系统 提示词](/docs/zh/eleven-agents/best-practices/prompting-guide)中。将任务专属步骤放在
流程中。

#### 流程与智能体一起进行版本控制

流程是智能体配置的一部分，因此发布新智能体版本时会一同创建快照。若要回滚到较早的一组流程，
请恢复较早的智能体版本。请参阅[智能体版本控制](/docs/zh/eleven-agents/operate/versioning)。

#### 基于现有文档快速开始

如果团队已有 SOP，请使用导入器将其转换为草稿，然后在此基础上完善。