本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 自定义代理
<a name="automate-custom-agents"></a>

自定义代理是一种智能操作，它使用集成的工具调用功能处理自然语言输入以自动执行复杂的步骤。它主要使用集成作为其工具界面，同时提供可扩展性，可以将 Code 用作工具，以及其他原生操作，例如人类在环任务。该代理提供结构化、可预测的输出，经过优化，可无缝集成到下游自动化步骤中。

## Properties
<a name="custom-agent-properties"></a>
+ **标题**： step/custom 代理人姓名
+ **模式**：一种模式根据您的用例定义代理的运行方式。三种可用模式是：快速、专业和自定义。Fast 最适合简单的任务，例如摘要、分类和高容量自动化，而 Pro 则非常适合涉及推理和编排多种工具或操作的复杂任务。Fast 和 Pro 是完全托管模式，无需事先进行预设置。在自定义模式下，你需要一个 Bedrock 运行时连接器，并且可以选择要使用的模型（详见下文）。当你已经有针对特定 Bedrock 模型进行微调的提示，特别需要为特定 Bedrock 模型使用 Agent，或者想要在 Bedrock 上包含自己的自定义或微调模型时，这是理想的选择。在自定义模式下，由于您通过集成从 Bedrock 引入自己的模型，因此模型推断将单独计费到与该 Bedrock 集成关联的账户中。
+ **说明**：在此字段中，您可以用自然语言编写代理的提示。编写提示时的最佳做法：
  + 清楚明确地说明你想要什么。
  + 构造提示。首先提及 “任务” 或 “角色”，然后提及 “说明”，通过编号步骤完成任务
  + 为了提高工具呼叫的准确性并指导代理，请在提示中明确指定在每个步骤中使用哪个工具（如果适用）。
  + 明确指定长度要求（例如，少于 100 个字）或输出格式（例如 MM/DD/YY 格式中的日期）
  + 用三引号 (“"”) 将文本换成多行提示。例如：

    ```
    """You are content summarization agent.
    Summarize the last two paragraphs of the provided text, focusing only on the main conclusion."""
    ```
+ **操作：操作**是一种使 AI 代理能够与外部系统交互或执行特定任务的工具。这是可选的。无需任何操作即可运行自定义代理。以下是可以在自定义代理中使用的不同操作
  + **一般操作**
    + **创建用户任务**-如果启用，此工具允许代理在 Human-in-the-Loop (HITL) 任务被卡住并在执行过程中需要帮助时触发 (HITL) 任务。代理停下来等待人工输入。HITL 任务在任务中心可见。为了获得最佳结果，作者可以在提示中指定代理应在何时调用 HITL。此选项默认处于选中状态。自动化一直持续到任务完成。
    + **代码**-“代码” 操作在受限的 python 环境中生成和执行 python 代码，与代码操作相同，以解决涉及计算、数据操作和文件处理的任务。与代码生成器不同，它会主动创建和运行脚本来实现目标，使用 Excel、PDF 文件、各种数据格式和可用的集成
      + **关键功能：**
        + **文件操作**：处理多选项卡 Excel 文件、提取内容、执行日期计算、应用条件格式并将结果上传到 S3
        + **数据转**换：在 JSON 格式和表格格式之间进行转换、转置数据、重命名列和联接表
        + **高级计算**：生成数值序列并执行自动验证
  + **集成**：如果您已向自动化组添加了特定的集成操作（例如 Salesforce、MS Exchange 或 Bedrock），则它们的相应操作将显示在此处，以便在自定义代理中使用。然后，作者可以选择相关操作作为代理的工具。

    可以在自定义代理 tools/actions 中使用的集成列表
    + Amazon S3
    + Amazon Bedrock 数据自动化
    + Amazon Comprehend
    + Amazon Textract
    + 自定义 REST API
    + 自定义 MCP 连接器
    + Microsoft Outlook
    + Salesforce
+ **结构化输出（可选）**

  将 AI 代理配置为返回下游步骤可以处理的结构化 JSON 输出。此功能非常适合文本摘要、报告生成、数据转换以及从非结构化内容中提取统计数据。此为可选字段。如果未定义结构化输出，则默认情况下，代理会以自然语言返回输出。当您的输出具有已定义的结构（例如列表、数据表或 JSON）时，请使用结构化输出。
**注意**  
自定义代理的结构化输出配置遵循与 UI 代理相同的格式。有关详细的配置说明，请参阅 UI 代理结构化输出部分。
+ **代理响应**：用于分配代理输出的变量的名称。如果已定义，则响应遵循您在 JSON 架构中的结构化输出格式，否则为自由格式文本。

## 在自定义代理中使用自定义模型（自带基岩模型）
<a name="custom-agent-byom"></a>

将托管在 B AWS edrock 中的所需或自定义微调模型与 Quick Suite 自动化工作流程集成。

开始之前，确保您已准备好以下事项：
+ 在 Bedrock 中部署并可访问经过微调的 AWS 模型
+ 用于创建连接器的快速套件管理员访问权限
+ 具有调用模型的 Bedrock 权限的 IAM 角色
+ 您的型号（例如，`us.anthropic.claude-3-5-sonnet-20241022-v2:0`）

**第 1 步：**按照中的详细说明创建 Bedrock 运行时操作集成 [AWS 服务操作连接器](builtin-services-integration.md)

**步骤 2：**设置您的自动化组

创建自动化组并连接集成：
+ **创建自动化群组**-按照中的详细说明进行操作 [设置任务](getting-started-quick-automate.md#automate-setup-tasks)
+ **配置集成**-按照中的详细说明进行操作 [设置任务](getting-started-quick-automate.md#automate-setup-tasks)
+ 配置完成后，连接器将出现在您的可用资产列表中

**步骤 3：**配置自定义代理

添加并配置自定义代理以使用经过微调的模型：
+ 在您的自动化工作流程中，添加自定义代理
+ 配置以下代理设置：
  + **代理人职称**：输入代理人的描述性姓名
  + **说明**：输入根据您的用例量身定制的自定义提示
  + **模式**：选择自定义
  + **连接器**：选择你的 Bedrock Runtime 连接器（选择 “自定义” 模式时为必填项）
  + **自定义模型**：输入您的模型 ID（例如`us.anthropic.claude-3-5-sonnet-20241022-v2:0`）-选择自定义模式时为必填项

**后续步骤**

配置完成后，您的自定义代理将使用经过微调的模型根据您提供的说明处理请求。现在，您可以将此代理整合到您的 Quick Automate 工作流程中。

**注意**  
确保您的模型 ID 格式正确，并且与您的 B AWS edrock 账户中部署的模型相匹配。您可以在 B AWS edrock 控制台的已配置模型下找到您的模型 ID。

## 定制代理测试
<a name="custom-agent-testing"></a>

自定义代理测试使您能够独立于完整的自动化工作流程来测试单个代理。此功能可帮助您验证代理行为、调试提示并更有效地进行迭代，而无需执行整个工作流程。

### 先决条件
<a name="custom-agent-testing-prerequisites"></a>
+ 包含至少一个已配置的自定义代理的自动化工作流程
+ 在工作区中运行自动化的适当权限

### 开始测试
<a name="custom-agent-testing-start"></a>
+ 在工作流程画布中，将鼠标悬停在要测试的代理卡片上
+ 选择出现在卡片顶部的**单元测试**按钮
+ 在打开的变量收集窗口中，查看代理提示中自动检测到的变量
  + 提示预览会突出显示所有检测到的变量
+ 为每个变量输入一个值
  + 值必须使用有效的表达式语法
  + 如果值包含无效语法，则会显示一条错误消息并阻止测试执行

### 监控测试执行情况
<a name="custom-agent-testing-monitor"></a>

在测试执行期间，您可以在屏幕右侧的审计面板中监控进度。该测试会跳过所有前面的工作流程步骤，只执行选定的代理。您获得的日志记录体验与完整工作流程运行相同。

### 查看测试结果
<a name="custom-agent-testing-results"></a>

测试完成后，在 “测试” 面板中查看以下信息：
+ 指标卡（测试面板顶部的 “监控” 选项卡）
  + 总执行时间
  + 使用的工具数量
  + 创建的任务数
+ 介于两者之间登录
+ “监视变量” 选项卡（“测试” 面板的底部手风琴）
  + 输入-查看输入变量及其值
  + 输出-检查代理执行的输出结果
  + 对于结构化输出，请单击 “查看详细信息” 按钮选择 JSON 查看器以打开 “查看输出” 对话框：
    + “字段” 选项卡-使用树结构视图浏览数据
    + 字段-通过在 “字段” 选项卡中选择树节点来突出显示相应的值
    + 输出字段-JSON 密钥的相应值

## 在 “使用助手构建” 中使用自定义代理
<a name="custom-agent-build-with-assistant"></a>

自定义代理的当前原则是必须特别提及它才能始终如一地调用它，以下是提示中使其显示所需的内容：

```
- Function names: `use_inline_agent`
- Representation names: "Custom Agent", "Inline Agent" → use `use_inline_agent`
- Generic terms: "agentic skills" → default to `use_inline_agent`
```

否则，最好使用模型来确定性地创作工作流程。

但是，实际上，当没有适当的操作可用时，计划者可能会选择自定义代理作为解决方法。但是，为了在工作流程中始终如一地调用自定义代理，建议在提示中使用上述短语。

## 代理用例示例
<a name="custom-agent-examples"></a>

**用例 1：电子邮件分类和分配代理**

**角色：**您是电子邮件分类和分配代理

**说明：**请按照以下步骤操作：
+ 第 1 步：根据提供的参考表的 “类别” 列将收到的电子邮件归类为知识邮件
+ 步骤 2：使用电子邮件系统发送通知：
  + 发件人：[系统邮箱]
  + 收件人：[团队\_分发\_电子邮件]
  + 主题：[分级结果]
  + 正文：包括一份简短的摘要，解释原始电子邮件中的分类理由和要点
+ 第 3 步：对于所有有效类别（“未知” 除外），请使用以下命令在 Salesforce 中创建一个新案例：
  + 主题：[原始电子邮件主题]
  + 描述：电子邮件正文中的问题摘要
  + 优先级：基于内容的紧急程度 (High/Medium/Low)
  + 类型：选择适当的类型 (Question/Problem/Feature Request/Other)
  + 状态：“新”
  + 类别：[步骤 1 的分类结果]
+ 第 4 步：如果归类为 “未知”：
  + 上报给主管进行人工审查
  + 添加注释，解释为什么分类不确定
  + 根据从主管那里收到的类别，按照步骤 2 和 3 进行操作，然后停止
  + 如果从主管那里收到的类别未知或无效，请停止

## 将知识库与自定义代理一起使用
<a name="custom-agent-knowledge-bases"></a>

在 Amazon Quick Automate 中，您可以将知识库连接到自定义代理，以便对组织的文档进行 AI-powered 检索和问题解答。通过将 Quick 空间链接到您的自动化群组，自定义代理可以搜索和检索该空间内的知识库中的信息。

将其用于需要参考组织知识的自动化，例如回答政策文件中的问题、汇总报告或根据参考数据对内容进行分类。

知识库会索引您的文档以进行语义搜索，因此自定义代理只检索最相关的段落，而不是处理整个文件。这使得检索更快、更准确，尤其是在大型文档集中。

### 先决条件
<a name="custom-agent-kb-prerequisites"></a>
+ 配置了一个或多个知识库的快速空间。有关更多信息，请参阅 [使用 Amazon Quick 中的空间整理、协作和共享资源](working-with-spaces.md)。
+ 您是其所有者的自动化群组
+ Owner-level 访问您要关联的空间

### 将空间关联到您的自动化群组
<a name="custom-agent-kb-link-space"></a>

在自定义代理可以访问知识库之前，您必须将包含这些知识库的空间链接到您的自动化组。链接空间将授予自动化组访问该空间内知识库和文件的权限。

要将空间链接到自动化组，请执行以下操作：

1. 在 “**自动化**” 选项卡中，转到 “**项目**” 页面。

1. 选择 “**群组**”，然后选择要将空间附加到的群组。
**提示**  
您也可以选择右侧的**创建群组**来创建新的自动化群组。

1. 在 “**资源**” 部分中，选择 “**添加**”，然后选择 “**空间**”。

1. 选择包含您要使用的知识库的空间，然后选择 “**添加**”。

现在，该空间出现在自动化组的连接列表中。此自动化组中的自定义代理可以访问链接空间中的知识库和文件。该领域的其他资源不可用于自动化。

**注意**  
如果空间在添加后显示**访问权限受限**，则表示并非所有知识库都与自动化组共享。如果在链接后将知识库添加到空间中，或者最初没有共享所有知识库，则可能会发生这种情况。要解决此问题，请刷新空间连接以与自动化组共享所有资源。您无需在单个自定义代理上重新配置 “知识” 选项卡。

### 向自定义代理添加知识
<a name="custom-agent-kb-add-knowledge"></a>

将空间链接到您的自动化群组后，您可以配置自定义代理以使用该空间中的知识库。工作流程必须位于您附加空间的同一个自动化组中。

要向自定义代理添加知识，请执行以下操作：

1. 在工作流生成器中，添加 “**自定义代理**” 步骤。您可以将自定义代理节点拖放到画布上，也可以与自动化助手聊天以构建此步骤。

1. 在代理属性面板中，选择**知识**，然后选择**添加**。

1. 将打开一个选取器，显示链接到自动化组的可用空间。选择一个或多个包含您希望代理使用的知识库的空间。

1. 选择**保存**。

现在，当自动化运行时，自定义代理可以在选定空间的知识库中搜索和检索内容。

附加空间后，该空间内的所有知识库都将自动可供代理使用。您无需单独附上每个知识库。在运行时，代理会独立查询每个知识库，并将结果合并到响应中。

**注意**  
如果自动化组所有者失去了对空间内特定知识库的访问权限，则在查询期间会跳过该知识库，工作流编辑器会在空间附件上显示警告标记。

### 为知识库查询编写说明
<a name="custom-agent-kb-instructions"></a>

当自定义代理附有知识库时，它会根据您的说明自动搜索和检索相关内容。编写说明，清楚地描述代理应查找哪些信息或应如何使用知识库内容。

最佳实践：
+ 具体说明要检索或汇总哪些信息
+ 引用您期望代理查找的内容类型（例如，“在政策文件中搜索...” 或 “查找有关... 的信息”）
+ 指定代理应如何在其响应中使用检索到的信息
+ 包括知识库中不包含相关内容时的备用说明

### 示例：具有知识库的客户咨询代理
<a name="custom-agent-kb-example"></a>

以下示例说明如何配置自定义代理，该代理使用知识库根据公司文档回答客户查询。

**设置：**
+ 包含包含产品文档和常见问题解答内容的知识库的空间
+ 该空间已链接到自动化组
+ 该空间将作为知识添加到自定义代理中

**说明：**

```
"""You are a customer support agent.

Task: Answer the customer inquiry using information from the knowledge base.

Instructions:
1. Search the knowledge base for information relevant to the customer's question.
2. Provide a clear, concise answer based on the retrieved content.
3. If the knowledge base does not contain relevant information, respond with:
   "I don't have enough information to answer this question. Please escalate to a human agent."

Constraints:
- Only use information found in the knowledge base. Do not make up answers.
- Keep responses under 200 words.
- Include the source document name when referencing specific information."""
```

**结构化输出：**

```
{
  "answer": "The response to the customer inquiry",
  "sourceDocument": "Name of the document used",
  "confidence": "high/medium/low",
  "escalationNeeded": false
}
```