content_safety 是 VeADK 基于智能体插件机制提供的内容安全护栏：在模型与工具调用前后把待审查内容发送到配置的审查后端，按返回的拦截决策替换内容或阻止工具执行。适用于需要接入内容策略的智能体应用。
功能说明
对应工具标识content_safety。
content_safety 是一个可选启用的智能体插件，默认不挂载、不发起任何网络请求。通过 provider 选择审查后端，两种后端都必须显式启用：
两种后端都已接入以下审计点：
- Before Model Callback——发送给模型前审查用户输入
- After Model Callback——审查模型输出
- Before Tool Callback——工具调用前审查入参
- After Tool Callback——审查工具返回
启用内容安全
content_safety 支持三种启用方式，按优先级从高到低：
- 在
Agent构造参数中通过content_safety直接配置； - 在
config.yaml中配置tool.content_safety块； - 调用
build_content_safety(config)手动构建插件，传给 ADKApp。
Runner 运行或经 AgentKit 部署的智能体，会在启动时自动解析配置并挂载插件，无需手动处理回调。
Agent 构造参数
Agent 提供 content_safety 参数控制内容安全插件的解析：
main.py
App 时，使用 agent.content_safety_plugins 属性获取已解析的插件列表并传入：
main.py
配置参考
tool.content_safety 块对应 ContentSafetyConfig，完整字段如下：
DecisionConfig 字段：
QuestionConfig 字段：
判定服务连接字段可通过环境变量覆盖
config.yaml：
tool.content_safety 块是结构化运行时配置，不会被展开为环境变量。其嵌套的 questions、decision 等值保持原样传递给插件。LLM Shield 后端
provider: llm_shield 借助火山大模型应用防火墙对各阶段内容做合规审查，拦截不安全的输入与输出。
前提
使用前先购买实例、添加资产并获取 AppID。通过config.yaml 的 tool.content_safety 块或环境变量配置：
config.yaml
tool.llm_shield 配置块，content_safety 在初始化时读取以下配置项。AppID 必须在导入前配置，缺失时无法完成初始化。
config.yaml
config.yaml 中的区域配置。也可在启动 Python 前通过环境变量设置，环境变量优先：
已通过环境变量设置的值优先于
config.yaml 中的同名配置项。策略分类
content_safety 基于火山大模型应用防火墙的多种内容安全策略，对不同类型的风险内容进行检测和拦截。风险内容的一级分类如下：
其中：
- 通用话题控制策略在添加资产时不会默认配置，需要添加后自行配置话题控制防护策略；
- 算力消耗策略并非单次触发即生效：当系统监测到相似攻击向量并伴随高算力输出的行为模式时，才会对该类输入请求进行拦截。
端点与鉴权
content_safety 支持两种内容审查端点，按 TOOL_LLM_SHIELD_URL 自动选择。
默认防火墙端点
当TOOL_LLM_SHIELD_URL 的路径不包含 /OpenTOP/V1/Lumen/Moderate 时使用此端点（即不设置 url 时的默认行为）。请求发送到 <url>/v2/moderate，鉴权方式按以下顺序选择：
- 配置了
TOOL_LLM_SHIELD_API_KEY时，使用 API Key 鉴权（请求头携带x-api-key）。 - 未配置 API Key 时，使用火山引擎 AK/SK 鉴权：优先读取环境变量
VOLCENGINE_ACCESS_KEY与VOLCENGINE_SECRET_KEY；若两者缺失，则从运行环境的 IAM 角色获取临时凭证。请求头携带服务区域与服务标识。
CLOUD_PROVIDER=byteplus 时，全局配置可将 BytePlus AK/SK 映射到上述凭据配置。仍须确认目标审查服务接受该账号凭据；模型使用 BytePlus 不代表审查服务的端点、区域与权限已完成配置
Lumen Moderate 端点
当TOOL_LLM_SHIELD_URL 的路径包含 /OpenTOP/V1/Lumen/Moderate 时使用此端点。请求直接发送到所配置的完整地址，以 AppID 作为端点标识、API Key 作为端点密钥进行鉴权。
与默认端点相比，Lumen Moderate 端点在工具调用审查时会附带当前会话标识与调用标识，便于在审计侧关联同一会话内的多次审查。模型输入审查、模型输出审查与工具入参、工具返回审查分别在对应回调点发起请求，拦截行为与默认端点一致。
AgentSentry V3 私有审查
当设置了AGENTSENTRY_URL 时，content_safety 进入 V3 私有审查模式，与公共防火墙端点（默认端点和 V1 Lumen Moderate 端点）完全独立。此模式优先于 TOOL_LLM_SHIELD_* 配置：设置 AGENTSENTRY_URL 后，公共模式的相关配置不再生效。V3 私有审查通过 AgentSentry V3 的 Moderate 端点（路径 /OpenTOP/V3/Lumen/Moderate）进行内容审查，使用端点 AK/SK 签名鉴权。
环境变量
配置示例：
V3 私有审查必须通过
AGENTSENTRY_URL 配置。如果 TOOL_LLM_SHIELD_URL 的路径为 /OpenTOP/V3/Lumen/Moderate，初始化会报错。审查范围与行为
V3 私有审查模式只审查以下两个环节：
与公共模式的主要差异：
- 用户输入审查：审查用户内容的全部文本部分，而非仅最后一条用户内容的首个文本部分。同一调用内仅审查一次用户输入。
- 模型输出：不审查模型输出，但会记录模型生成工具调用时的可见文本（排除思维过程文本）作为计划，用于后续工具调用审查。
- 工具调用审查：要求模型在生成工具调用时提供可见文本计划。如果未找到匹配的计划，工具调用将被阻止，而非直接执行。审查内容为模型计划文本与工具调用信息，而非序列化的工具参数。
- 工具返回：不审查。
- 审查失败处理：当 V3 服务返回降级响应、非 200 状态码、超时或未知决策时，阻止工具执行并返回服务不可用提示，而非放行内容。
使用方法
provider: llm_shield 通过 Runner 或 AgentKit 部署时会自动挂载。也可直接把 content_safety 的回调挂到智能体上：
config.yaml 中指定对应的访问地址与 API Key 即可，调用方式不变：
config.yaml
检查审查效果
在导入content_safety 前完成配置，并通过环境变量 TOOL_LLM_SHIELD_API_KEY 提供密钥。保存示例后执行 python app.py：普通输入应获得回复；用已在防火墙策略中配置的测试文本验证拦截，并同时检查审查服务的记录。不能仅凭固定示例句子保证命中某项策略
模型输入审查检查当前请求最后一条用户内容的首个文本部分，模型输出审查检查首个文本部分；不会自动审查全部历史、图片、音频或所有多部分内容。工具回调审查序列化的参数与结果。默认请求超时为 50 秒
V3 私有审查模式的审查范围与上述公共模式不同：用户输入审查检查全部文本部分而非仅首个，工具调用审查检查模型可见计划而非序列化参数，且不审查模型输出和工具返回。详见上方「AgentSentry V3 私有审查」一节。
调整请求超时
在前述示例中，用以下配置片段替换content_safety 的导入，保留同样的四个回调配置：
Decision 后端（System One）
provider: decision 把待审计内容组装成 System One 的 state，按一组可配置的问题返回风险概率，再按阈值决定放行或拦截。默认问题集覆盖提示词注入、凭证窃取、数据外泄、危险操作、有害内容等类别。
配置
在config.yaml 中配置后，通过 Runner 运行或部署智能体时会自动挂载插件：
config.yaml
TOOL_CONTENT_SAFETY_DECISION_API_URL、TOOL_CONTENT_SAFETY_DECISION_API_KEY、TOOL_CONTENT_SAFETY_DECISION_MODEL。
也可在代码中直接配置：
main.py
build_content_safety(config) 得到插件，再传给手动创建的 ADK App(plugins=[...])。
内置问题集
provider=decision 且 use_default_questions=true（默认）时，内置问题集自动合并为基准。问题按风险类别设定分级阈值：安全关键类别（如 child_safety、self_harm）阈值较低，倾向于捕获边界情况；上下文相关类别（如 tool_abuse、sensitive_data）阈值较高，需要更强证据。questions 中的同名问题覆盖内置项，新名称追加。设置 use_default_questions=false 时仅使用 questions 中声明的问题，且至少需要一个。
审计窗口与拦截行为
before_model：只审计最后一条user消息；如果上下文中存在最近一次工具返回，也会一并审计。更早的历史轮次不会重复审计。after_model：审计完整的模型响应；流式响应会先扣留可见文本和媒体分片，在响应结束或turn_complete时一次性审计后再放行。before_tool：审计工具名和参数（敏感字段会先脱敏）。after_tool：审计工具名、参数和返回结果（同样先脱敏）。thought内容、函数调用签名等非可见内容不进入state。
before_model 返回带 turn_complete=True 的固定拦截文案；after_model 用拦截文案替换响应内容，并保留原响应的 turn_complete；工具回调返回带 error、blocked: true 的结果；流式响应则用拦截文案替换已扣留的分片。
判定服务超时、网络错误或响应无法解析时，按 on_error 处理：allow（默认）放行并在审计结果中标记降级，block 则失败关闭。每个问题的命中条件是风险概率大于等于其阈值。
请求体过大被判定服务拒绝（HTTP 413/431，或 HTTP 400 且响应明确提示 size/too large）时，内容实际上没有被审计，SDK 会忽略 on_error=allow 并按 block 处理。
多模态审计与 state 结构
state 始终是 System One 的内容数组，纯文本和媒体使用同一套结构。纯文本示例：
无法识别或不受支持的 MIME 类型会跳过并记录告警，不会让整个审计失败。单个内联媒体超过 20 MiB 时会跳过并告警；需要审计的大文件建议先上传到 TOS 并使用 HTTP(S) URL。如果跳过媒体后没有任何可审计内容，审计结果状态为
skipped，同时保留告警日志。
state 的 32,000 字符上限作用于文本片段；媒体 URL 或 data URL 不参与该字符截断。审计文本中的 <untrusted> / </untrusted> 标签会被转义为 <...>，防止内容提前闭合或伪造包裹。字段名脱敏按词边界匹配凭证关键词（如 access_token、secretKey），tokenizer、token_count、next_page_token_data 等元数据字段保留原文，避免字段名误伤造成审计盲区。脱敏是 best-effort，仅作为纵深防御，不替代专门的 DLP 能力。