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

# ElevenAgents Architect 的工作方式

## 概述

ElevenAgents Architect 对话以实时 ElevenAgents 对话形式运行，使用与所构建智能体相同的引擎。Architect 的工具在浏览器中、登录会话下运行。每个工具都会调用仪表板使用的同一套 ElevenAgents API，因此每次读取和写入都会根据权限进行检查。参阅 [权限、审批和草稿](/docs/zh/eleven-agents/operate/architect/authentication)。

## ElevenAgents Architect 默认了解的信息

每次对话开始时，Architect 会获得：

* **账户和工作区**：套餐、工作区和用量。
* **所在位置**：当前页面；如果正在查看某个智能体，还包括该智能体以及打开的分支。在侧边栏中，Architect 还会获取页面快照，并在页面变更后、每条消息前获得更新。
* **智能体摘要**：在智能体内时由 ElevenLabs 生成。包括智能体名称和所有者、分支及其流量分配、过去 7 天的通话量、草稿状态、已连接的智能体、流程、是否已配置测试，以及可编辑的分支。
* **智能体上下文**：智能体的 `agents.md` 文档，供所有构建该智能体的人共享。参阅 [自定义 Architect](/docs/zh/eleven-agents/operate/architect/customization)。
* **偏好设置**：个人 `user.md` 文档，适用于构建的每个智能体。
* **入口传入的内容**：例如失败的测试、Spotlight 发现或分诊工单。参阅 [开始对话](/docs/zh/eleven-agents/operate/architect/entry-points)。
* **此聊天中之前的消息。**

Architect **不会**一开始就获取智能体的完整配置、转录文本、测试结果、Spotlight 数据或其他 Architect 聊天记录。任务需要时，它会通过工具读取这些内容。这样能让每次对话保持聚焦，也意味着 Architect 始终基于当前数据工作，而不是过时副本。

## 调查与直接指令

Architect 会以不同方式处理两类请求。

**直接指令**会明确说明要进行的更改，例如“添加一项护栏，禁止讨论竞品定价”或“缩短第一条消息”。Architect 会读取相关配置、进行编辑，并报告已暂存的内容。在默认审批模式下，对智能体配置的编辑会暂存在草稿中，无需询问。影响实时流量或共享资源的操作会等待批准。

**调查**会提出问题但不指定修复方案，例如“为什么退款通话会升级？”或“如何提高退款解决率？”。Architect 会先研究，再进行任何更改：

* 它会为调查创建一份 **待办列表**，完成项目时会一直显示在编辑器上方。
* 它会先查看成本较低的信号，例如对话数量、主题和评估结果，再读取单个转录文本。
* 它会并行分析对话，并按根本原因归类发现结果。
* 它的推理过程可见。每个推理步骤会折叠为 **思考 Ns**，并可展开。
* 它会报告发现的内容，包括实际读取了多少段对话。不会把样本说成完整结果。

### 计划模式

对于较大的改动，将编辑器切换为 **计划**（按 <kbd>Shift</kbd>+<kbd>Tab</kbd> 可切换模式）。在计划模式下，Architect 使用只读工具进行研究，编写可实时查看其起草过程的计划，然后要求你 **批准计划** 或 **拒绝**。在批准前，它不会进行任何更改。如果拒绝计划并附上备注，Architect 会修订后再次请求批准。

在全屏 Architect 标签页中，计划会显示在编辑器上方的面板内。在侧边栏中，它会以聊天卡片的形式显示。

## 完整示例：提高退款解决率

本示例展示一次对话如何从一个宽泛问题发展到可供审核的更改。文中列出了工具名称，方便将每个步骤与对话中显示的内容对应起来。Architect 会自行选择步骤，因此实际对话的顺序和细节可能有所不同。

从智能体的 Architect 标签页发送的请求：

> 如何提高退款解决率？

#### 规划调查

Architect 创建待办列表（`write_todos`）：衡量问题、找出退款失败的对话、确定根本原因、提出并测试修复方案。

#### 衡量问题

Architect 读取智能体主题（`get_agent_topics`、`get_topics_summary`），找出退款主题及其成功率，然后统计并列出近期评估失败的退款对话（`count_conversations`、`list_conversations`）。

#### 阅读对话

Architect 搜索包含退款请求的转录文本（`search_conversation_messages`、
`semantic_search_conversations`），然后并行分析一批失败对话
（`analyze_conversation_subagent`）。每次分析都会说明用户想要什么、智能体在哪一步出错，以及发生错误的轮次。

#### 找出根本原因

Architect 将失败案例与当前配置进行比较（`get_agent_config`、
`list_procedures`、`get_procedure`）。它会报告类似这样的发现：“40 通失败退款电话中，有 31 通里智能体在询问订单号前调用了 `lookup_order`，导致出错并升级。”

#### 在分支上进行更改

Architect 创建分支（`create_branch`），使更改与实时智能体隔离。接着编辑退款流程（`update_procedure`），在查询前先询问订单号。编辑会暂存在该分支的草稿中。实时来电者不会受到任何影响。

#### 为更改编写测试

Architect 会编写用于捕捉该失败问题的测试：模拟未提供订单号却请求退款的来电者（`create_simulation_test`）；检查 `lookup_order` 未被优先调用的工具调用测试（`create_tool_test`）；以及根据一段真实失败对话生成的测试（`generate_test_from_conversation`）。Architect 会在模拟中模拟具有副作用的工具，因此不会发起真实退款。

#### 在更改前后运行测试

Architect 先针对未更改的智能体运行测试（原始分支上的 `run_tests`，或使用 `include_draft: false` 的 `run_agent_tests`），然后针对包含更改的草稿运行测试（`run_agent_tests`），并读取结果（`get_test_suite_summary`、
`get_test_suite_failures`）。预期结果是：新测试在没有更改时失败，在应用更改后通过。如果测试仍然失败，Architect 会读取失败信息、调整更改并再次运行。

#### 展示更改

Architect 会总结根本原因、更改内容和测试结果，并打开发布对话框（`request_draft_publish`）。审核差异后选择 **发布**，即可将更改作为分支上的新版本提交。Architect 无法代为发布。

#### 创建提案

Architect 读取分支历史和合并预览（`get_branch_history`、
`merge_branch_preview`），并向 `main` 创建合并提案（`create_merge_proposal`）。说明包含 **摘要**、**测试** 和 **审核方式** 三个部分，内容基于实际提交和测试运行记录。Architect 可以建议审核者
（`suggest_merge_proposal_reviewers`），但由你选择。

#### 提供渐进式发布选项

Architect 会建议在审核提案期间，将一小部分实时流量（通常为 5%）发送到该分支（`set_traffic_split`）。这会改变实时流量，因此会等待批准。

验证在对话中进行，在要求发布或审核任何内容之前完成。当提案送达审核者时，促成此次更改的测试已附加到智能体，并已在分支上运行。参阅 [提案和验证](/docs/zh/eleven-agents/operate/architect/proposals)，了解审核者会看到什么。

> **Tip**
>
> 更改前后运行测试是良好实践，但 Architect 不会针对每项更改自动运行。为确保执行，请直接提出要求，例如“向我展示新测试在 main 上失败、在分支上通过。”

![Architect 工作轨迹](/docs/_fern-img/a0ac226f441713105d638105f3ca8fd93ad672556b6ae0ae48847d1de8c7ba8d.webp)

## 斜杠命令

在编辑器中输入 `/`，即可查看当前页面可用的命令。

| 命令            | 功能                                        |
| ------------- | ----------------------------------------- |
| `/start`      | 设置此智能体的上下文（`agents.md`），让 Architect 了解目标。 |
| `/generate`   | 根据描述生成新智能体。                               |
| `/debug`      | 调试近期失败的对话。                                |
| `/test`       | 运行测试并汇总结果。                                |
| `/explain`    | 用通俗语言解释此智能体的功能。                           |
| `/optimize`   | 建议提示词和配置改进。                               |
| `/review`     | 审核智能体表现并找出改进点。                            |
| `/branch`     | 为此智能体创建新分支。                               |
| `/experiment` | 创建分支并将其部署为 A/B 测试。                        |
| `/rollback`   | 审核近期配置更改，并在需要时撤销。                         |
| `/remember`   | 将智能体相关事实存储为知识库文档。                         |
| `/dashboard`  | 在聊天中构建自定义分析仪表板。                           |
| `/clear`      | 清除此对话并重新开始。                               |
| `/feedback`   | 向 ElevenLabs 发送关于本次会话的私密反馈。               |

大多数命令仅在智能体内适用。`/clear` 和 `/feedback` 在 Architect 标签页主页上不可用。

## 聊天中的仪表板

Architect 可以在对话中构建仪表板，用数据回答问题，例如“按原因细分本周的升级情况，并展示趋势。”使用 `/dashboard` 或直接请求构建。

Architect 使用工具收集数据，通过 [代码](#running-code) 处理数据，并使用与 Spotlight 相同的指标卡片、图表、列表和文本卡片渲染仪表板。仪表板可以包括：

* 带有核心数值、变化情况和迷你趋势图的 **指标卡片**。
* **图表**：面积图、折线图、柱状图、堆叠面积图、环形图，以及用于前 N 项细分的排名柱状列表。
* 带有状态标签、日期和 ElevenAgents 页面链接的 **列表**，例如单个对话页面。
* 用于展示发现和建议的 **文本卡片**。

在全屏 Architect 标签页中，仪表板会在对话中内嵌呈现。在侧边栏中，它会在聊天旁的面板中打开。

仪表板数据仅保存在构建它的浏览器标签页内存中，绝不会随聊天保存。重新加载页面、在其他标签页打开聊天，或构建多个大型仪表板后，较早的仪表板会显示提示信息，而不是数据。请 Architect 重新构建。仪表板是只读快照，没有筛选条件，也不会实时更新。

## 运行代码

Architect 可以运行简短的 Python 程序，对工具中的数据进行计数、分组和比较，例如计算数百段对话按周的解决率。代码在浏览器中的沙箱内运行，仅可使用 Python 标准库。它无法访问网络、ElevenLabs 账户，并且有 20 秒的时间限制。代码执行功能正在逐步推出，可能并非每个工作区都可用。

## 大型响应

当工具返回的数据超出对话可容纳的范围时，例如很长的对话列表，Architect 会将完整响应保留在浏览器标签页内存中，并使用摘要进行处理。它可按需搜索和读取其余内容。工具调用上的提示会显示这种情况。这些响应绝不会被保存或上传。