> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

> 使用 agent 自动更新文档。可从 Slack 消息、PR 或 API 调用中创建更新。

<Info>
  agent 功能适用于 [Pro 和 Custom 方案](https://mintlify.com/pricing?ref=agent)，所有有权访问你控制台的成员都可以使用。
</Info>

agent 会根据你的提示为文档创建包含建议修改的拉取请求（PR）。当你向 agent 发送请求时，它会利用你的文档、已连接的代码仓库以及 Slack 消息，生成符合技术写作最佳实践并遵循 Mintlify schema 的内容。你可以在控制台中直接使用 agent，在 Slack 工作区中调用它，或者通过 API 将其嵌入自定义应用中。

你可以使用 agent 来：

* 根据你的提示、拉取请求链接或 Slack 线程撰写新内容
* 修改过时的代码示例和 API 参考
* 查找并更新现有内容
* 回答关于你的文档和技术写作相关主题的问题

<div id="use-the-agent-in-the-dashboard">
  ## 在控制台中使用 agent
</div>

在控制台中，你可以通过键盘快捷键 <kbd>⌘</kbd>+<kbd>I</kbd>（macOS）或 <kbd>Ctrl</kbd>+<kbd>I</kbd>（Windows/Linux），或者点击 **Ask agent** 按钮来打开 agent。桌面端可以调整 agent 面板大小。在移动设备上，agent 会以全屏方式打开。

agent 面板包含三个视图：

* **Chat**：向 agent 发送提示词，让它更新你的文档。agent 会根据你的指令创建拉取请求（PR；亦称“合并请求”/Merge Request），并显示链接，方便你查看这些拉取请求或在网页编辑器中打开更改。
* **History**：浏览过去的对话，并继续处理之前的请求。点击任意对话即可在聊天视图中打开。
* **Settings**：配置 agent 的集成和存储库访问权限。

<Tip>
  为每个任务与 agent 开启一个新的对话。这样可以让 agent 的上下文更加聚焦，并帮助你将对话与特定项目关联起来。
</Tip>

<div id="add-the-agent-to-your-slack-workspace">
  ## 将 agent 添加到你的 Slack 工作区
</div>

在 Slack 中使用 agent，与团队协作完成文档更新。

<Note>
  如果你的 Slack 工作区所有者要求安装应用需管理员批准，请先让他们批准 Mintlify 应用，再进行连接。
</Note>

1. 在控制台中打开 agent 面板。
2. 点击 **Settings** 按钮。

   <Frame>
     <img src="https://mintcdn.com/anotherhorizon/J4BH3chw5X4BWXwI/images/agent/dashboard-settings-light.png?fit=max&auto=format&n=J4BH3chw5X4BWXwI&q=85&s=b38d93419f324772150682405feed0e9" alt="浅色模式下的设置按钮。" className="block dark:hidden" width="668" height="112" data-path="images/agent/dashboard-settings-light.png" />

     <img src="https://mintcdn.com/anotherhorizon/J4BH3chw5X4BWXwI/images/agent/dashboard-settings-dark.png?fit=max&auto=format&n=J4BH3chw5X4BWXwI&q=85&s=a773c798a5c8a4a4d1621e93229ee7d1" alt="深色模式下的设置按钮。" className="hidden dark:block" width="670" height="112" data-path="images/agent/dashboard-settings-dark.png" />
   </Frame>
3. 在 Slack 集成部分点击 **Connect**。
4. 按照 Slack 的提示，将 `mintlify` 应用添加到你的工作区。
5. 按照 Slack 的提示，将你的 Mintlify 账户关联到你的 Slack 工作区。
6. 测试 agent 是否正常工作，并在你：
   * 向它发送一条私信时，
   * 在频道中使用 `@mintlify` 提及它时，
     能做出响应。

<div id="connect-your-github-account">
  ## 连接你的 GitHub 账号
</div>

默认情况下，智能体会以 Mintlify 机器人身份创建拉取请求（PR）。若要将拉取请求归属到你的账号，请在控制台的 [My profile](https://dashboard.mintlify.com/settings/account) 页面连接你的 GitHub 账号。

<div id="connect-repositories-as-context">
  ## 将代码仓库连接为 context
</div>

agent 只能访问你通过 Mintlify GitHub 应用连接的代码仓库。你可以在 agent 面板的 **Settings** 中，或者在 [GitHub 应用设置](https://github.com/apps/mintlify/installations/new) 中配置 agent 可访问的代码仓库。

<div id="customize-agent-behavior">
  ## 自定义 agent 行为
</div>

在你的存储库中创建一个 `AGENTS.md` 文件以自定义 agent 的行为（也接受 `Agents.md`）。agent 会读取这个文件并遵循你提供的所有指令。

agent 会在两个位置查找 `AGENTS.md` 文件。它首先检查文档目录，然后检查存储库根目录。如果你在这两个位置都有 `AGENTS.md` 文件，agent 会使用文档目录中的那个文件。

添加你希望 agent 遵循的任何指令。agent 会将这些指令追加到它的系统提示（system prompt）中，因此这些指令会应用于所有任务，无论你是在控制台、Slack 中，还是通过 API 使用该 agent。

```markdown Example AGENTS.md file theme={null}
# Documentation agent instructions

## Code examples
- Use TypeScript for all code examples. Our users are primarily TypeScript developers.
- Always include error handling in API call examples.
- Show both success and error response examples for all endpoints.
- Include import statements at the top of code examples.

## API documentation standards
- Every endpoint must document: authentication requirements, rate limits, and common error codes.
- Use real-world parameter values in examples (not foo/bar placeholders).
- Include a complete request/response cycle for each endpoint.

## Style and formatting
- Write for developers with 2-5 years of experience. Don't oversimplify, but explain non-obvious concepts.
- Use active voice and second person ("you").
- Date format: ISO 8601 (YYYY-MM-DD).
- When referencing UI elements, use bold: **Settings** button.

## What to include
- Add prerequisite sections to guides when users need API keys, environment setup, or dependencies.
- Include "Next steps" sections linking to related documentation.
- Add troubleshooting sections for common issues we see in support tickets.
```

<div id="embed-the-agent-via-api">
  ## 通过 API 嵌入 Agent
</div>

使用 Agent 端点来[创建任务](/zh/api-reference/agent/create-agent-job)、[获取指定任务](/zh/api-reference/agent/get-agent-job)以及[获取全部任务](/zh/api-reference/agent/get-all-jobs)。

通过 API 创建任务时，你可以使用 `asDraft` 参数（默认为 `true`）来控制是否将拉取请求以草稿模式创建（拉取请求/PR；亦称“合并请求”/Merge Request）。将 `asDraft` 设置为 `false` 可创建非草稿的拉取请求，以便在自动化工作流中立即进行审核和合并。

<div id="write-effective-prompts">
  ## 编写高效的提示词
</div>

将代理视为需要你指引来完成任务的 AI 助手。请提供清晰的指令和上下文。任务越聚焦越容易完成，因此把复杂项目拆解为更小的步骤。

让你的提示词具体且以结果为导向。像 `@mintlify Improve the onboarding page` 这样的泛化提示会应用通用最佳实践，但可能无法按照你设想的方式针对性地改进内容。

围绕你希望用户达成的结果或他们遇到的问题来设计提示词。例如：

* `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI`
* `@mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key`

对于修正错别字、更新重定向或在整个文档中重命名功能等常规内容维护，可以使用更宽泛的提示词。例如：

* `@mintlify Find and fix all typos in the docs`
* `@mintlify change all unordered lists to use * instead of -`

<div id="specify-a-domain-name">
  ## 指定域名
</div>

如果你拥有多个文档站点，请在消息中包含 `subdomain` 参数，用于指定助手应处理哪一个文档集。

要找到你的域名，请查看你想更新的文档集的 dashboard URL。域名是组织名称后面的最后一段。例如，如果你的 dashboard URL 是 `https://dashboard.mintlify.com/org-name/domain-name`，那么你的域名就是 `domain-name`。

使用 `@mintlify subdomain=&lt;your-domain-name&gt; &lt;your-prompt&gt;` 这种格式，引导助手在特定文档集上执行操作。

示例：

* `@mintlify subdomain=public-docs Add a new section to the quickstart about inviting collaborators based on this PR`：提示助手仅更新 `public-docs` 站点上的 quickstart 章节。
* `@mintlify subdomain=customer-docs Update the auth docs for the new authentication method`：提示助手仅更新 `customer-docs` 站点上的认证文档。

<div id="agent-workflows">
  ## Agent 工作流
</div>

该 Agent 可协助处理多种文档任务。以下工作流展示了将 Agent 集成到文档流程中的一些方式。选择与团队当前工作方式相匹配的方法，并根据你的具体需求进行调整。

<div id="iterate-on-a-prompt-in-a-slack-thread">
  ### 在 Slack 线程中迭代优化提示词
</div>

先向代理发送提示词，然后在同一线程中继续使用 `@mintlify` 提及它，以完善并迭代其创建的拉取请求（PR）。

例如：`@mintlify 我们的快速入门页面需要新增一个“邀请协作者”的章节`。然后：`@mintlify 新章节应命名为 “Inviting collaborators”`。之后可以继续进行其他迭代。

<div id="start-with-the-agent-finish-manually">
  ### 从代理开始，手动收尾
</div>

让代理启动一个项目，然后检出它创建的 branch，并在本地环境或网页编辑器中完成任务。代理可以帮助你开始，随后你可以接手完成整个任务。

例如：`@mintlify Update the quickstart page to include information about inviting collaborators`，接着检出该 branch，按你偏好的方式进行后续修改。

<div id="update-docs-when-merging-feature-changes">
  ### 合并功能改动时更新文档
</div>

当你合并功能拉取请求（PR）后，将该 PR 链接分享给 Agent，以便更新相关文档。

例如：`@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`。

<div id="generate-release-notes-from-a-pull-request">
  ### 从拉取请求生成发布说明
</div>

向代理提供特定的拉取请求，根据提交历史生成发布说明或更新日志。

例如：`@mintlify 为此 PR 生成发布说明：[PR link]`。

<div id="generate-code-examples">
  ### 生成代码示例
</div>

让智能助手在你的文档各处或特定页面为功能生成代码示例。

例如：`@mintlify 生成一个代码示例，帮助更容易理解认证方法`。

<div id="review-existing-content">
  ### 审查现有内容
</div>

让代理审查现有内容的技术准确性、风格、语法等方面的问题。

例如：`@mintlify Review the API rate limiting section. We changed limits last month`

<div id="respond-to-user-feedback">
  ### 响应用户反馈
</div>

将用户的反馈提交给助手，以便对你的文档进行有针对性的更新。

例如：`@mintlify Users are getting confused by step 3 in the setup guide. What might be making it unclear?`.

<div id="automate-with-the-api">
  ### 使用 API 实现自动化
</div>

将 Agent 集成到你现有的自动化工具中，在代码变更时自动更新文档、触发文档审查，或在多个代码仓库之间同步文档更新。

请参阅教程：[当代码合并时自动更新文档](/zh/guides/automate-agent) 了解如何操作。