Plano 提示词护栏Prompt Guardrails实战基于 Filter Chain 构建输入安全与合规检查层【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/planoGuardrails护栏是 Plano 数据平面中在提示词进入应用逻辑之前施加安全检查与验证的一层机制通常以 Filter Chain 中可复用的过滤器形式挂载到 Agent 上使每个请求都流经一致的校验管线。本文以 TechCorp 客服场景的领域限定输入护栏为例完整讲解护栏的动机、MCP/HTTP 两种过滤器实现方式、Plano 配置接线方法、拒绝响应语义与测试验证并结合仓库源码揭示内置prompt_guards的 jailbreak 检测实现与过滤器编排最佳实践帮助读者为生产级 Agent 构建可插拔、可观测、可审计的安全边界。为什么需要护栏Why Guardrails护栏是维持 AI 应用可控性的关键设施。它们帮助企业强制执行组织策略、满足 GDPR 或 HIPAA 等合规要求并保护用户免受有害或不恰当内容的影响。在提示词会触发响应或动作的应用中护栏将恶意输入、离题查询或不一致输出的风险降到最低——为交互增加一层一致的输入审查使交互更安全、更可靠、更易于推理。从仓库中的内置能力与工程实践看Plano 护栏主要解决三类问题Jailbreak 预防Jailbreak Prevention检测并过滤试图改变 LLM 行为、泄露系统提示词或绕过安全策略的输入。Plano 为此提供了内置的prompt_guards配置其模式定义在 配置 Schema 中对应请求/响应数据结构实现于 prompt_guard.rs。领域与主题限制Domain and Topicality Enforcement确保 Agent 只响应批准领域内的提示词例如仅限金融或仅限医疗场景拒绝无关查询——这正是本文 TechCorp 示例的核心场景。动态错误处理Dynamic Error Handling请求违反策略时给出清晰、可操作的错误消息帮助用户修正输入而非返回笼统的 4xx。护栏的工作原理MCP 过滤器与 HTTP 过滤器护栏既可以实现为进程内in-process的 MCP 过滤器也可以实现为基于 HTTP 的过滤器。HTTP 过滤器是外部服务通过 HTTP 接收请求、执行校验并返回允许或拒绝请求的响应——这让过滤器可以用任何语言编写或以独立服务的形式运行天然支持多语言团队与独立部署。每个过滤器接收聊天消息chat messages按策略进行评估然后选择放行请求或通过抛出ToolError或返回错误响应来拒绝请求并附带有用的错误信息。请求在到达 Agent 或上游 LLM 之前会按顺序流经整条 Filter Chain每一个过滤器都可能检查传入的提示词、元数据与对话状态变更或丰富请求如重写查询、构建上下文短路流程、提前返回响应如合规失败时阻断请求输出结构化日志与 trace便于调试与持续改进。正如 Filter Chain 概念文档 所描述的过滤器通过 HTTP 状态码表达处理结果HTTP 200成功过滤器成功处理请求若过滤器变更了请求如重写查询、丰富上下文变更会向下游传递。HTTP 4xx用户错误请求违反过滤器规则如内容审核策略、合规检查。请求被终止错误返回给调用方。这不是致命错误而是预期的策略执行。HTTP 5xx致命错误过滤器自身出现意外故障崩溃、配置错误等。Plano 将错误反馈给调用方并记录到日志与 trace 中。这套语义让护栏可以执行策略4xx而不拖垮整个系统同时将关键故障5xx暴露出来供排查。数据平面执行层的核心实现在 llm_gateway 的 filter_context.rs它基于 Envoy WASM 在请求处理上下文中维护过滤器调用callouts映射异步接收各过滤器的 HTTP 响应并继续流水线。编写第一个护栏FastMCP 领域校验过滤器下面以 TechCorp 客服系统的输入护栏为例它校验查询是否落在公司领域内。使用 FastMCP 将护栏暴露为 MCP 工具from typing import List from fastmcp.exceptions import ToolError from . import mcp mcp.tool async def input_guards(messages: List[ChatMessage]) - List[ChatMessage]: Validates queries are within TechCorps domain. # Get the users query user_query next( (msg.content for msg in reversed(messages) if msg.role user), ) # Use an LLM to validate the query scope (simplified) is_valid await validate_with_llm(user_query) if not is_valid: raise ToolError( I can only assist with questions related to TechCorp and its services. Please ask about TechCorps products, pricing, SLAs, or technical support. ) return messages代码要点从消息列表中逆序找到最后一条user消息作为待校验查询这保证评估的是用户最近一次意图校验通过则原样返回messages让请求继续流转校验失败则抛出ToolError携带对用户友好、可操作的提示信息指明可提问的范围。将护栏接入 PlanoFilter 定义与 Filter Chain 配置要把这个护栏接入 Plano先在配置中定义过滤器再把它加入 Agent 的 filter chainfilters: - id: input_guards url: http://localhost:10500 listeners: - type: agent name: agent_1 port: 8001 router: plano_orchestrator_v1 agents: - id: rag_agent description: virtual assistant for retrieval augmented generation tasks filter_chain: - input_guards当请求到达agent_1时Plano首先调用input_guards过滤器。校验通过则请求继续流向 Agent校验失败抛出ToolError则 Plano 向调用方返回错误响应被拒绝的查询永远不会到达 Agent。最小配置与可选字段根据 Filter Chain 编程模型定义过滤器时以下字段都是可选的实际起步通常只需id与urltype控制过滤器运行时mcp表示 Model Context Protocol 过滤器http表示纯 HTTP 过滤器默认mcptransport控制 Plano 与过滤器的通信方式默认streamable-http基于 HTTP 的高效流式交互标准 HTTP 传输时可省略tool指定 Plano 调用的 MCP 工具名默认取过滤器id工具名与过滤器 id 一致时可省略。仓库中的 mcp_filter 示例配置 展示了一条由input_guards、query_rewriter、context_builder组成的三段式过滤链先做输入安全校验再重写查询最后构建检索上下文并通过model_aliasesfast-llm/smart-llm配合路由。模型监听器上的护栏Model Listener Filter ChainFilter Chain 也可以直接挂到model listener上让直接走 LLM 代理请求/v1/chat/completions、/v1/responses等的流量无需 Agent 层也能先过输入护栏filters: - id: content_guard url: http://content-guard:10500 type: http model_providers: - model: openai/gpt-4o-mini access_key: $OPENAI_API_KEY default: true listeners: - type: model name: llm_gateway port: 12000 filter_chain: - content_guard这里filter_chain声明在监听器层级而非按 Agent 声明。请求到达模型监听器时Plano 按序执行过滤器再转发给上游 LLM 提供商若过滤器拒绝请求HTTP 4xx错误直接返回给调用方LLM 永远不会被调用——这是成本与安全双赢的设计。仓库中的 model_listener_filter 示例 更进一步区分了input_filters输入侧content_guard与output_filters输出侧output_redactor即输入安全 输出脱敏的双向护栏对应的 content_guard.py 是一个纯关键词内容安全过滤器兼容 OpenAI/v1/chat/completions、/v1/responses与 Anthropic/v1/messages三种请求格式无需调用 LLM命中黑名单关键词即返回 400。测试护栏拒绝越界查询下面演示护栏的实际效果——拒绝一条关于 Apple Corporation 的查询超出 TechCorp 领域curl -X POST http://localhost:8001/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4, messages: [ { role: user, content: what is sla for apple corporation? } ], stream: false }护栏返回的错误响应{ error: ClientError, agent: input_guards, status: 400, agent_response: I apologize, but I can only assist with questions related to TechCorp and its services. Your query appears to be outside this scope. The query is about SLA for Apple Corporation, which is unrelated to TechCorp.\n\nPlease ask me about TechCorps products, services, pricing, SLAs, or technical support. }响应结构清晰可观测error标明错误类型、agent指明是哪条过滤器拒绝input_guards、status为 400、agent_response携带完整的解释性消息。这样既阻止越界查询触达 Agent又给用户明确的拒绝原因与修正方向。纵深内置 prompt_guards 与编排最佳实践内置 jailbreak 检测prompt_guards除了自定义 Filter ChainPlano 还提供内置的 jailbreak 检测能力无需部署任何外部服务。配置结构定义在 配置 Schema其底层数据结构任务类型与请求/响应模型位于 prompt_guard.rsPromptGuardTask任务类型可选jailbreak、toxicity、bothPromptGuardRequest携带input待检文本与taskPromptGuardResponse返回toxic_prob、jailbreak_prob概率值与对应的toxic_verdict、jailbreak_verdict布尔判定。配置示例来自 filter-guardrails 规则version: v0.3.0 prompt_guards: input_guards: jailbreak: on_exception: message: Im not able to help with that request. This assistant is designed to help with customer support. Please rephrase your question or contact supportyourdomain.com if you believe this is an error.当内置 jailbreak 检测被触发时Plano 返回on_exception.message而不是转发请求。注意两点prompt_guards对所有 listener 全局生效如需按 Agent 差异化策略应使用各 Agent 上的filter_chain拒绝消息必须可操作空消息或Error code 403: guard triggered这类晦涩消息会让用户困惑、无法重新表述应说明限制原因并给出可做的替代动作既改善体验又降低支持负担。内置检测 自定义过滤器的组合实战中推荐将内置 jailbreak 检测快速、无需外部服务与MCP 自定义过滤器领域限定等附加策略组合使用# Built-in jailbreak detection (fast, no external service needed) prompt_guards: input_guards: jailbreak: on_exception: message: This request cannot be processed. Please ask about our products and services. # MCP-based custom guards for additional policy enforcement filters: - id: topic_restriction url: http://host.docker.internal:10500 type: mcp transport: streamable-http tool: topic_restriction # Custom filter for domain-specific restrictions listeners: - type: agent name: customer_support port: 8000 router: plano_orchestrator_v1 agents: - id: support_agent description: Customer support assistant for product questions and order issues. filter_chain: - topic_restriction # Additional custom topic filtering过滤器链的编排顺序护栏优先丰富靠后filter_chain是有序的过滤器 id 列表每个过滤器接收上一个过滤器的输出顺序具有语义意义。根据 filter-ordering 规则推荐顺序为输入护栏Input guards——jailbreak 检测、PII 检测、主题限制尽早拒绝查询重写Query rewriting——规范化或增强用户查询上下文构建Context building——RAG 检索、工具查询、知识注入开销大输出护栏Output guards——在返回前校验或清理 LLM 响应。反例是先把context_builder放在input_guards之前jailbreak 请求会在被阻断前先获得 RAG 增强的上下文——既浪费算力又存在数据暴露风险。同一条 listener 下不同 Agent 可以有不同过滤链对外 Agent 全量上护栏内部管理 Agent 可以跳过部分检查。延伸阅读Filter Chain 概念文档过滤器可复用工作流步骤、HTTP/MCP 编程模型与状态码语义Filter Chain 示例配置 与 Model Listener 双向过滤示例filter-guardrails 规则可操作拒绝消息的写法与prompt_guards全局语义filter-mcp 规则显式声明type/transport/tool避免默认值静默误路由filter-ordering 规则守卫在前、丰富在后的链式编排配置 Schema 与 prompt_guard.rs内置检测的配置结构与数据结构llm_gateway 执行上下文Filter Chain 在 Envoy WASM 数据平面中的运行时实现【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Plano 提示词护栏（Prompt Guardrails）实战：基于 Filter Chain 构建输入安全与合规检查层
Plano 提示词护栏Prompt Guardrails实战基于 Filter Chain 构建输入安全与合规检查层【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/planoGuardrails护栏是 Plano 数据平面中在提示词进入应用逻辑之前施加安全检查与验证的一层机制通常以 Filter Chain 中可复用的过滤器形式挂载到 Agent 上使每个请求都流经一致的校验管线。本文以 TechCorp 客服场景的领域限定输入护栏为例完整讲解护栏的动机、MCP/HTTP 两种过滤器实现方式、Plano 配置接线方法、拒绝响应语义与测试验证并结合仓库源码揭示内置prompt_guards的 jailbreak 检测实现与过滤器编排最佳实践帮助读者为生产级 Agent 构建可插拔、可观测、可审计的安全边界。为什么需要护栏Why Guardrails护栏是维持 AI 应用可控性的关键设施。它们帮助企业强制执行组织策略、满足 GDPR 或 HIPAA 等合规要求并保护用户免受有害或不恰当内容的影响。在提示词会触发响应或动作的应用中护栏将恶意输入、离题查询或不一致输出的风险降到最低——为交互增加一层一致的输入审查使交互更安全、更可靠、更易于推理。从仓库中的内置能力与工程实践看Plano 护栏主要解决三类问题Jailbreak 预防Jailbreak Prevention检测并过滤试图改变 LLM 行为、泄露系统提示词或绕过安全策略的输入。Plano 为此提供了内置的prompt_guards配置其模式定义在 配置 Schema 中对应请求/响应数据结构实现于 prompt_guard.rs。领域与主题限制Domain and Topicality Enforcement确保 Agent 只响应批准领域内的提示词例如仅限金融或仅限医疗场景拒绝无关查询——这正是本文 TechCorp 示例的核心场景。动态错误处理Dynamic Error Handling请求违反策略时给出清晰、可操作的错误消息帮助用户修正输入而非返回笼统的 4xx。护栏的工作原理MCP 过滤器与 HTTP 过滤器护栏既可以实现为进程内in-process的 MCP 过滤器也可以实现为基于 HTTP 的过滤器。HTTP 过滤器是外部服务通过 HTTP 接收请求、执行校验并返回允许或拒绝请求的响应——这让过滤器可以用任何语言编写或以独立服务的形式运行天然支持多语言团队与独立部署。每个过滤器接收聊天消息chat messages按策略进行评估然后选择放行请求或通过抛出ToolError或返回错误响应来拒绝请求并附带有用的错误信息。请求在到达 Agent 或上游 LLM 之前会按顺序流经整条 Filter Chain每一个过滤器都可能检查传入的提示词、元数据与对话状态变更或丰富请求如重写查询、构建上下文短路流程、提前返回响应如合规失败时阻断请求输出结构化日志与 trace便于调试与持续改进。正如 Filter Chain 概念文档 所描述的过滤器通过 HTTP 状态码表达处理结果HTTP 200成功过滤器成功处理请求若过滤器变更了请求如重写查询、丰富上下文变更会向下游传递。HTTP 4xx用户错误请求违反过滤器规则如内容审核策略、合规检查。请求被终止错误返回给调用方。这不是致命错误而是预期的策略执行。HTTP 5xx致命错误过滤器自身出现意外故障崩溃、配置错误等。Plano 将错误反馈给调用方并记录到日志与 trace 中。这套语义让护栏可以执行策略4xx而不拖垮整个系统同时将关键故障5xx暴露出来供排查。数据平面执行层的核心实现在 llm_gateway 的 filter_context.rs它基于 Envoy WASM 在请求处理上下文中维护过滤器调用callouts映射异步接收各过滤器的 HTTP 响应并继续流水线。编写第一个护栏FastMCP 领域校验过滤器下面以 TechCorp 客服系统的输入护栏为例它校验查询是否落在公司领域内。使用 FastMCP 将护栏暴露为 MCP 工具from typing import List from fastmcp.exceptions import ToolError from . import mcp mcp.tool async def input_guards(messages: List[ChatMessage]) - List[ChatMessage]: Validates queries are within TechCorps domain. # Get the users query user_query next( (msg.content for msg in reversed(messages) if msg.role user), ) # Use an LLM to validate the query scope (simplified) is_valid await validate_with_llm(user_query) if not is_valid: raise ToolError( I can only assist with questions related to TechCorp and its services. Please ask about TechCorps products, pricing, SLAs, or technical support. ) return messages代码要点从消息列表中逆序找到最后一条user消息作为待校验查询这保证评估的是用户最近一次意图校验通过则原样返回messages让请求继续流转校验失败则抛出ToolError携带对用户友好、可操作的提示信息指明可提问的范围。将护栏接入 PlanoFilter 定义与 Filter Chain 配置要把这个护栏接入 Plano先在配置中定义过滤器再把它加入 Agent 的 filter chainfilters: - id: input_guards url: http://localhost:10500 listeners: - type: agent name: agent_1 port: 8001 router: plano_orchestrator_v1 agents: - id: rag_agent description: virtual assistant for retrieval augmented generation tasks filter_chain: - input_guards当请求到达agent_1时Plano首先调用input_guards过滤器。校验通过则请求继续流向 Agent校验失败抛出ToolError则 Plano 向调用方返回错误响应被拒绝的查询永远不会到达 Agent。最小配置与可选字段根据 Filter Chain 编程模型定义过滤器时以下字段都是可选的实际起步通常只需id与urltype控制过滤器运行时mcp表示 Model Context Protocol 过滤器http表示纯 HTTP 过滤器默认mcptransport控制 Plano 与过滤器的通信方式默认streamable-http基于 HTTP 的高效流式交互标准 HTTP 传输时可省略tool指定 Plano 调用的 MCP 工具名默认取过滤器id工具名与过滤器 id 一致时可省略。仓库中的 mcp_filter 示例配置 展示了一条由input_guards、query_rewriter、context_builder组成的三段式过滤链先做输入安全校验再重写查询最后构建检索上下文并通过model_aliasesfast-llm/smart-llm配合路由。模型监听器上的护栏Model Listener Filter ChainFilter Chain 也可以直接挂到model listener上让直接走 LLM 代理请求/v1/chat/completions、/v1/responses等的流量无需 Agent 层也能先过输入护栏filters: - id: content_guard url: http://content-guard:10500 type: http model_providers: - model: openai/gpt-4o-mini access_key: $OPENAI_API_KEY default: true listeners: - type: model name: llm_gateway port: 12000 filter_chain: - content_guard这里filter_chain声明在监听器层级而非按 Agent 声明。请求到达模型监听器时Plano 按序执行过滤器再转发给上游 LLM 提供商若过滤器拒绝请求HTTP 4xx错误直接返回给调用方LLM 永远不会被调用——这是成本与安全双赢的设计。仓库中的 model_listener_filter 示例 更进一步区分了input_filters输入侧content_guard与output_filters输出侧output_redactor即输入安全 输出脱敏的双向护栏对应的 content_guard.py 是一个纯关键词内容安全过滤器兼容 OpenAI/v1/chat/completions、/v1/responses与 Anthropic/v1/messages三种请求格式无需调用 LLM命中黑名单关键词即返回 400。测试护栏拒绝越界查询下面演示护栏的实际效果——拒绝一条关于 Apple Corporation 的查询超出 TechCorp 领域curl -X POST http://localhost:8001/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4, messages: [ { role: user, content: what is sla for apple corporation? } ], stream: false }护栏返回的错误响应{ error: ClientError, agent: input_guards, status: 400, agent_response: I apologize, but I can only assist with questions related to TechCorp and its services. Your query appears to be outside this scope. The query is about SLA for Apple Corporation, which is unrelated to TechCorp.\n\nPlease ask me about TechCorps products, services, pricing, SLAs, or technical support. }响应结构清晰可观测error标明错误类型、agent指明是哪条过滤器拒绝input_guards、status为 400、agent_response携带完整的解释性消息。这样既阻止越界查询触达 Agent又给用户明确的拒绝原因与修正方向。纵深内置 prompt_guards 与编排最佳实践内置 jailbreak 检测prompt_guards除了自定义 Filter ChainPlano 还提供内置的 jailbreak 检测能力无需部署任何外部服务。配置结构定义在 配置 Schema其底层数据结构任务类型与请求/响应模型位于 prompt_guard.rsPromptGuardTask任务类型可选jailbreak、toxicity、bothPromptGuardRequest携带input待检文本与taskPromptGuardResponse返回toxic_prob、jailbreak_prob概率值与对应的toxic_verdict、jailbreak_verdict布尔判定。配置示例来自 filter-guardrails 规则version: v0.3.0 prompt_guards: input_guards: jailbreak: on_exception: message: Im not able to help with that request. This assistant is designed to help with customer support. Please rephrase your question or contact supportyourdomain.com if you believe this is an error.当内置 jailbreak 检测被触发时Plano 返回on_exception.message而不是转发请求。注意两点prompt_guards对所有 listener 全局生效如需按 Agent 差异化策略应使用各 Agent 上的filter_chain拒绝消息必须可操作空消息或Error code 403: guard triggered这类晦涩消息会让用户困惑、无法重新表述应说明限制原因并给出可做的替代动作既改善体验又降低支持负担。内置检测 自定义过滤器的组合实战中推荐将内置 jailbreak 检测快速、无需外部服务与MCP 自定义过滤器领域限定等附加策略组合使用# Built-in jailbreak detection (fast, no external service needed) prompt_guards: input_guards: jailbreak: on_exception: message: This request cannot be processed. Please ask about our products and services. # MCP-based custom guards for additional policy enforcement filters: - id: topic_restriction url: http://host.docker.internal:10500 type: mcp transport: streamable-http tool: topic_restriction # Custom filter for domain-specific restrictions listeners: - type: agent name: customer_support port: 8000 router: plano_orchestrator_v1 agents: - id: support_agent description: Customer support assistant for product questions and order issues. filter_chain: - topic_restriction # Additional custom topic filtering过滤器链的编排顺序护栏优先丰富靠后filter_chain是有序的过滤器 id 列表每个过滤器接收上一个过滤器的输出顺序具有语义意义。根据 filter-ordering 规则推荐顺序为输入护栏Input guards——jailbreak 检测、PII 检测、主题限制尽早拒绝查询重写Query rewriting——规范化或增强用户查询上下文构建Context building——RAG 检索、工具查询、知识注入开销大输出护栏Output guards——在返回前校验或清理 LLM 响应。反例是先把context_builder放在input_guards之前jailbreak 请求会在被阻断前先获得 RAG 增强的上下文——既浪费算力又存在数据暴露风险。同一条 listener 下不同 Agent 可以有不同过滤链对外 Agent 全量上护栏内部管理 Agent 可以跳过部分检查。延伸阅读Filter Chain 概念文档过滤器可复用工作流步骤、HTTP/MCP 编程模型与状态码语义Filter Chain 示例配置 与 Model Listener 双向过滤示例filter-guardrails 规则可操作拒绝消息的写法与prompt_guards全局语义filter-mcp 规则显式声明type/transport/tool避免默认值静默误路由filter-ordering 规则守卫在前、丰富在后的链式编排配置 Schema 与 prompt_guard.rs内置检测的配置结构与数据结构llm_gateway 执行上下文Filter Chain 在 Envoy WASM 数据平面中的运行时实现【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考