跳到主要内容

Middleware Configurations

本指南解释了在 NPO Studio 中创建或编辑 AI Agent 时可用的 Middleware 设置。Middleware 选项卡提供了 3 个关键功能：Human in the loop、PII (Personally Identifiable Information) 保护和 Summarization（基于 LangChain）。

访问 Middleware 设置​

  1. 从 Agent 设计画布中打开您的 AI Agent。
  2. 点击 AI Agent 节点（例如，“Agent 1 - Main Agent”）。
  3. 在右侧配置面板中，选择 Middleware 选项卡。

人工干预​

人工干预中间件让您控制代理可以自主执行的工具以及哪些工具需要明确的人类批准。当启用时，符合您配置规则的工具调用将暂停执行，并等待人类批准、编辑或拒绝后再继续。

启用人工干预​

在 Middleware 面板顶部将 Human in the loop 开关切换为开启。此功能在主代理和子代理节点上均可用。

为每个 MCP 服务器配置工具权限​

启用人工干预后，每个连接的 MCP 服务器将显示为可折叠的部分。您可以在每个 MCP 服务器内为每个工具配置批准规则。

添加工具权限规则​

  1. 展开 MCP 服务器部分（例如，“Lunar15 Apr ZCP Alert Backend”，“ddg-search”）。
  2. 点击 Select a tool 下拉菜单以选择该 MCP 服务器中的特定工具。
  3. 点击 Select one or more permission 下拉菜单以分配该工具的允许权限。
  4. 点击 checkmark 按钮以确认，或点击 X 按钮以取消。
  5. 该工具现在在列表中显示其分配的权限操作。

Note: 如果 MCP 服务器没有为人类参与配置工具，它将显示“未为此 MCP 配置工具。”

工具权限操作​

每个配置的工具显示一个或多个操作按钮，定义代理如何处理工具执行请求。一个工具可以同时配置多个权限：批准、编辑、拒绝。

操作描述
Approve允许工具执行继续进行。人类审核者确认工具调用及其参数是可接受的。
Edit允许人类审核者在执行前修改工具调用参数。可在配置了可编辑权限时使用。
Reject完全阻止工具执行。代理被告知工具调用被拒绝，必须在没有它的情况下继续进行。

管理工具规则​

  • 点击工具旁边的 three-dot menu (⋮) 以访问其他选项（例如，删除规则）。
  • 点击 MCP 服务器标题中的 add 图标以添加新的工具权限规则。
  • 来自同一 MCP 服务器的多个工具可以各自具有不同的权限配置。

人类参与在运行时的工作原理​

当启用人类参与的代理在 NPO Workspace 聊天中使用时：

  1. 代理处理用户的消息并确定需要调用一个工具。
  2. 代理不会自动执行工具，而是在聊天中显示一条 "Tool execution pending approval" 消息。
  3. 消息显示：
    • 正在调用的 tool name （例如，fetch_content、search、get_alerts_api_alert_v1...）。
    • 代理打算传递的 arguments
  4. 人类审核员点击可用操作按钮之一：
    • Approve：工具使用显示的参数执行。
    • Edit：审核员修改参数，然后工具使用更新的值执行。
    • Reject：工具调用被阻止；代理继续而不使用工具结果。
  5. 操作后，代理继续处理工具结果（如果被批准）或不处理（如果被拒绝）。

Note：多个工具调用可能出现在单个待批准消息中。消息中的每个工具调用必须进行审核。代理在所有待处理工具得到解决之前不会继续。所有为主代理和子代理选择的 MCP 服务器应显示在“人类在环”部分下。确保 MCP 配置了可选择的工具。

配置示例​

MCP 服务器工具可用操作用例
ZCP 警报后端get_alerts_api_alert_v1...批准、编辑、拒绝在执行之前审核警报查询
ddg-searchfetch_content批准、拒绝控制代理可以获取哪些 URL
ddg-searchsearch批准、编辑、拒绝审核和修改搜索查询

人类在环的最佳实践​

  • 为执行 write operations （创建、更新、删除）或访问 sensitive data 的工具启用人类在环。
  • 对于参数调整可以提高准确性的工具（例如，搜索查询、API 过滤器），使用 Edit 权限。
  • 对于风险较低的 read-only tools，考虑不使用人类干预以保持对话速度。
  • 根据 MCP 服务器配置工具规则，以应用细粒度控制 - 并非所有工具都需要相同级别的监督。
  • 在发布之前测试 Playground 中的审批流程，以确保用户体验顺畅。
  • 人类干预适用于主代理和子代理节点，独立配置每个代理节点以满足其特定工具使用需求。

PII 个人可识别信息​

PII 中间件会自动检测并保护通过您的 AI 代理流动的敏感数据。启用后，它会扫描消息中的特定数据类型并应用保护措施。

启用 PII​

将 PII 开关切换为开启，以激活代理的 PII 保护。

支持的 PII 类型​

每种 PII 类型都可以单独开启或关闭：

PII 类型描述
Email电子邮件地址（例如，user@example.com）
Credit card信用卡/借记卡号码
IPIP 地址（IPv4/IPv6）
MAC address网络 MAC 地址
URL网络 URL 和链接
Action Mode

每种 PII 类型都有一个操作下拉菜单，用于确定如何处理检测到的数据：

  • Redact：用占位符（例如，[REDACTED]）替换检测到的 PII，完全从消息中移除敏感值。
Apply To

对于每种 PII 类型，您可以选择应用保护的位置。使用复选框选择一个或多个：

  • Input：扫描并保护发送给代理的用户消息中的 PII。
  • Output：扫描并保护代理回复用户时的 PII。
  • Tool results: 扫描并保护从工具/API 调用返回的数据中的 PII。
Configuration Examples
PII 类型操作输入输出工具结果用例
电子邮件删除未选中选中选中防止代理在响应中泄露电子邮件
信用卡删除未选中选中未选中仅在输出中屏蔽卡号
IP删除未选中选中未选中隐藏响应中的 IP 地址
MAC 地址删除未选中选中未选中隐藏响应中的 MAC 地址
URL删除选中未选中未选中在处理之前从用户输入中剥离 URL
Best Practices for PII
  1. 启用 Output 保护敏感类型（电子邮件、信用卡），以防止意外数据泄露。
  2. 当后端 API 返回不应暴露的用户数据时，启用 Tool results。
  3. 当您希望在用户提供的数据到达 LLM 之前进行匿名处理时，启用 Input。
  4. 在连接可能返回敏感信息的新 MCP 工具时，检查 PII 设置。

摘要​

摘要中间件（基于 LangChain）自动压缩对话历史，以管理上下文窗口限制。当对话超出配置的阈值时，它会触发摘要，以保持上下文在范围内，同时保留重要信息。

启用摘要​

将 Summarization 开关切换为开启，以激活对话摘要。

LLM 配置​

摘要需要其自己的 LLM 来生成摘要。配置以下必填字段：

Provider(必填)

  • 用于生成摘要的 LLM 提供者。
  • 示例：OpenAI
  • 从配置的提供者下拉列表中选择。

Default model(必填)

  • 用于摘要的特定模型。
  • 示例：GPT 4o
  • 选择一个在摘要任务中平衡质量和成本的模型。

API Key(必需)

  • 用于与LLM提供者进行身份验证的API密钥。
  • 示例：BachDX
  • 从系统中预配置的API密钥中选择。

触发器​

Trigger部分定义了启动摘要的条件。当满足任何启用的条件时，摘要过程将运行。您可以同时启用多个触发器 - 当满足any条件时，摘要将激活。

Messages
  • 当对话达到指定数量的消息时触发摘要。
  • 示例：50 - 在对话中50条消息后运行摘要。
  • 点击x以清除该值。
Tokens
  • 当对话达到指定的令牌计数时触发摘要。
  • 输入摘要激活前的最大令牌计数。
  • 有助于保持在LLM上下文窗口限制内。
Fraction
  • 当对话使用指定百分比的上下文窗口时触发摘要。
  • 通过滑块可调（0-100%）。
  • 有助于根据模型容量进行动态上下文管理。

保留​

Keep部分确定在摘要运行后保留多少对话历史。选择三种策略之一：

Messages (Keep by message count)
  • 在摘要后保留固定数量的最新消息。
  • Messages limit：要保留的最新消息数量。
  • 示例：30 - 在摘要后，保留30条最新消息的逐字记录，较旧的消息将被摘要替换。
Tokens (Keep by token count)
  • 保留最近消息，直到达到指定的令牌预算。
  • Tokens limit：要从最近历史中保留的最大令牌数。
  • 当您需要精确控制上下文窗口使用时非常有用。
Fraction (Keep by percentage)
  • 保留总对话的一定百分比作为最近消息。
  • Fraction limit: 可通过滑块调整（例如，12%）。
  • 剩余部分被总结。
  • 对于比例上下文管理，无论对话长度如何都很有用。
How Summarization Works (LangChain-based)
  1. 代理根据配置的 Trigger 条件监控对话。
  2. 当达到触发阈值时，总结 LLM 生成较旧消息的简明摘要。
  3. 系统根据 Keep 策略保留最近消息。
  4. 摘要替换较旧的对话历史，减少上下文大小。
  5. 未来的交互使用摘要 + 最近消息作为上下文。
Choosing the Right Configuration
场景触发保留策略推荐
短对话，成本敏感消息：30消息：10简单且可预测
长对话，注重质量令牌：接近模型限制比例：20%最大化上下文使用
可变长度对话比例：80%消息：20适应对话长度
严格的令牌预算令牌：4000令牌：1000精确的令牌控制
Best Practices for Summarization
  • 使用快速、成本效益高的模型（例如，GPT 4o）进行摘要，因为它运行频繁。
  • 将 Trigger 阈值设置在模型实际上下文限制以下，以为摘要本身留出余地。
  • 启用多种触发类型以确保安全——如果一个条件配置错误，另一个可以捕捉到。
  • 使用真实对话进行测试，以验证在摘要后重要上下文是否得以保留。
  • 对于多轮任务代理，优先选择 Messages 保留策略，以确保最近的指令保持完整。
  • 对于知识密集型对话，优先选择 Tokens 或 Fraction 以保留更多细节。