Agent Zero 工具模型调用前置扩展点解析util_model_call_before 的密钥掩码机制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读在 Agent Zero AI 框架中工具模型utility model承担结构化输出、摘要、分类等非对话性质的推理任务其提示词同样可能携带 API Key 等敏感凭据。util_model_call_before扩展点专门负责在工具模型请求离开框架之前执行预处理核心职责是对 system 与 user 消息做密钥掩码secret masking。本文以 extensions/python/util_model_call_before/AGENTS.md 为骨架结合其唯一实现 _10_mask_secrets.py 与 agent.py 中的调用链、helpers/secrets.py 的掩码底层完整说明该扩展点的契约、实现原理、掩码占位符格式与验证方法。读完本文你将能够理解并安全地扩展工具模型调用前的预处理行为同时保证调用方期望的结构化输出不被破坏。一、扩展点定位工具模型调用生命周期中的出发前检查Agent Zero 的 Python 扩展体系由 extensions/python/AGENTS.md 定义extensions/python/下每个直接子目录是一个具名扩展点扩展点内的 Python 文件按确定性的文件名顺序加载执行。util_model_call_before正是其中之一其官方职责Purpose为Own preprocessing before utility model calls. —— 拥有工具模型调用之前的预处理。从源码结构看该扩展点的所有权Ownership约定为扩展点内有序的 Python 文件负责密钥掩码以及未来的工具调用准备工作。与兄弟扩展点对比可以更清晰地理解其分工before_main_llm_call/主对话模型chat model调用前的预处理util_model_call_before/工具模型utility model调用前的预处理error_format/错误格式与掩码行为hist_add_before/消息写入历史前的掩码行为。工具模型调用发生在 agent.py 的call_utility_model中。该方法先组装call_data字典包含model、system、message、callback、background随后在真正发起模型调用之前触发扩展点await extension.call_extensions_async( util_model_call_before, self, call_datacall_data )注意这里传入的是可变的call_data字典这正是扩展函数改写请求内容的入口对应 extensions/python/AGENTS.md 中Use mutablectxordatadictionaries according to the hook contract when rewriting content的约定。扩展返回后call_data[system]与call_data[message]即被掩码处理后的内容送入model.unified_call()最后在util_model_call_after扩展点做收尾。二、扩展点契约四条不可违背的本地约定util_model_call_before/AGENTS.md 的 Local Contracts 明确了该扩展点的四条行为边界在工具提示词离开框架之前掩码密钥Mask secrets before utility prompts leave the framework。这是该扩展点的第一使命任何包含真实密钥的文本都不得原样发送到工具模型提供方。保持工具模型输入与调用方期望的结构化输出兼容Keep utility model inputs compatible with callers expecting structured outputs。掩码只允许替换敏感值本身不允许改变提示词的格式结构否则下游解析结构化输出如 JSON、枚举值会失败。掩码变更必须与主模型调用和错误格式掩码行为协调Work GuidanceCoordinate masking changes with main model call and error-format masking behavior。三者的占位符格式与掩码策略必须保持一致避免同一密钥在不同链路中暴露。变更后必须验证包含掩码密钥模式的工具模型调用VerificationTest utility model calls that include masked secret patterns after changes。任何修改都要以测试兜底。这些契约与整个 secrets 体系的全局约定一脉相承不记录未掩码的密钥、原始隐藏提示词段或私有用户数据见 extensions/python/AGENTS.md 的 Local Contracts。三、实现剖析_10_mask_secrets.py 如何工作该扩展点目前只包含一个实现文件 _10_mask_secrets.py。文件名前缀_10是确定性加载顺序的一部分——在扩展点内按文件名排序执行数字前缀用于控制执行次序extensions/python/AGENTS.md 明确要求当顺序影响提示词构造、流掩码、持久化或清理时必须保留数字前缀。完整的核心逻辑如下from helpers.extension import Extension from helpers.secrets import get_secrets_manager class MaskToolSecrets(Extension): async def execute(self, **kwargs): if not self.agent: return # model call data call_data:dict kwargs.get(call_data, {}) secrets_mgr get_secrets_manager(self.agent.context) # mask system and user message if system:call_data.get(system): call_data[system] secrets_mgr.mask_values(system) if message:call_data.get(message): call_data[message] secrets_mgr.mask_values(message)逐行拆解其工作方式继承Extension基类扩展函数统一从 helpers/extension.py 的Extension派生并以async def execute(self, **kwargs)作为入口与call_extensions_async的异步调用协议匹配。守卫self.agent若扩展运行在无 Agent 上下文的场景如纯工具脚本直接返回避免空指针。取出call_data从 kwargs 中取回 agent.py 传入的可变字典。获取 secrets 管理器get_secrets_manager(self.agent.context)依据当前 Agent 上下文定位密钥存储——默认合并usr/secrets.env与运行凭据文件usr/.env仅取API_KEY_*前缀键及运行时凭据键若处于活动项目中还会追加项目级secrets.env见 helpers/secrets.py。就地掩码对call_data[system]与call_data[message]分别调用mask_values()结果写回原字典。因为写回的是同一个call_data后续call_data[model].unified_call(system_messagecall_data[system], user_messagecall_data[message], ...)agent.py拿到的就是脱敏后的提示词。四、掩码底层SecretsManager.mask_values 与占位符格式mask_values是掩码链路的核心定义于 helpers/secrets.pydef mask_values( self, text: str, min_length: int 4, placeholder: str §§secret({key}) ) - str: if not text: return text secrets self.load_secrets() result text # Sort by length (longest first) to avoid partial replacements for key, value in sorted( secrets.items(), keylambda x: len(x[1]), reverseTrue ): if value and len(value.strip()) min_length: result result.replace(value, alias_for_key(key, placeholder)) return result其行为要点值长度门槛只有去空白后长度 ≥min_length默认 4的密钥值才会被替换避免把过短的普通文本误判为密钥而破坏提示词。长值优先密钥按值长度降序替换防止短值作为长值的子串先被替换导致残留泄漏。占位符格式替换产物为§§secret(KEY)KEY为密钥名的大写形式由alias_for_key生成helpers/secrets.py。该格式与全局占位符模式ALIAS_PATTERN r§§secret\(([A-Za-z_][A-Za-z0-9_]*)\)一致。可逆性replace_placeholders()会在需要时把占位符还原为真实值change_placeholders()则支持切换占位符格式。这意味着掩码不是单向破坏而是出发前脱敏、必要时还原的可逆机制。例如usr/secrets.env中存在OPENAI_API_KEYsk-xxxx那么任何包含sk-xxxx的工具模型 system/user 消息都会被改写为§§secret(OPENAI_API_KEY)而框架其他环节如 prompts/agent.system.secrets.md 描述的密钥提示注入会引导模型理解并使用这种占位符。值得注意的是helpers/secrets.py还提供了流式掩码组件StreamingSecretsFilterhelpers/secrets.py它维护可能构成密钥前缀的最长后缀缓冲逐块替换完整值并在finalize()时将未解析的残留前缀以***兜底。这主要服务于响应流response_stream_chunk、reasoning_stream_chunk等扩展点的实时掩码与util_model_call_before的整段文本掩码构成互补前者防流式泄漏后者防请求外泄。五、为什么在调用前掩码设计意图与协调约束工具模型调用属于框架内部的高频热路径extensions/python/AGENTS.md 要求扩展模块保持轻导入避免拖慢热点路径。将掩码放在util_model_call_before而非散落在每个调用方带来三个直接收益单一入口、集中管控所有走call_utility_model的调用摘要、分类、命名、分支合并等自动获得一致的脱敏行为无需各调用方自行实现。不污染历史与上下文掩码发生在请求组装阶段写回的是call_data而非全局消息历史历史与上下文管理hist_add_before扩展点另有自己的掩码逻辑互不干扰。与主模型链路对称before_main_llm_call承担主模型侧的同类预处理二者共享同一套SecretsManager与占位符格式这正是原文档要求掩码变更必须与主模型调用和错误格式掩码行为协调的原因——若某次调整只改了工具模型侧的掩码而遗漏主模型或错误格式侧密钥就可能在另一条链路中暴露。六、验证与测试如何确保掩码不回归原文档的 Verification 要求是在变更后测试包含掩码密钥模式的工具模型调用。结合仓库现状可以给出如下实操验证方案单元级验证直接构造SecretsManager调用mask_values()断言真实密钥被替换为§§secret(KEY)、且非密钥普通文本不被误伤值长度门槛生效。扩展级验证模拟call_utility_model的call_data执行MaskToolSecrets.execute(call_data...)断言system/message键已被就地改写且不含原始密钥值。端到端验证运行包含真实密钥模式的工具模型调用如文档摘要、聊天命名确认发送给模型的内容中密钥均为占位符、结构化输出仍可被调用方解析。回归对照同时跑主模型链路与错误格式掩码的相关测试确保三侧占位符格式一致防止协调性被破坏。七、小结util_model_call_before是 Agent Zero 工具模型安全边界的守门员它通过有序 Python 文件在工具请求离境前完成密钥掩码以§§secret(KEY)占位符保持提示词结构化兼容并与主模型调用、错误格式掩码共享同一套 SecretsManager 语义。理解 _10_mask_secrets.py 的实现与 helpers/secrets.py 的掩码算法是安全地扩展该扩展点、或在其后追加未来工具调用准备逻辑如请求路由、上下文注入的前提。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考