openai-agents-python 沙箱技能实战解析 prior-auth-packet-builder 的授权预审资料包构建流程【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python导读本文以 openai-agents-python 仓库中 healthcare_support 示例自带的沙箱技能 SKILL.md 为线索完整拆解预先授权Prior Authorization资料包构建这一技能的编写规范、执行工作流与源码级落地机制。你将掌握技能描述frontmatter如何决定 Agent 何时触发技能、沙箱内如何用rg || grep双保险检索策略文档、如何产出符合机器校验标准的policy_findings.md与human_review_checklist.md两类工件以及finalize_policy_packet如何作为唯一收尾门禁保证工作流完整性。文章同时结合 support_agents.py、workflow.py 与 skills.py 给出底层实现佐证。一、技能是什么SKILL.md 在 openai-agents-python 中的角色在 openai-agents-python 的沙箱体系中技能Skill被定义为一组存储在SKILL.md文件中的本地指令见 skills.py。一个技能目录以SKILL.md为入口可附带scripts/、references/、assets/等子目录。技能采用**惰性加载lazy loading**机制只有 Agent 决定使用某个技能时对应目录才会被复制进沙箱工作区避免一次性注入过多上下文。prior-auth-packet-builder就是这样一个技能目录examples/sandbox/healthcare_support/skills/prior-auth-packet-builder/ └── SKILL.md该技能是 healthcare_support 演示工作流的核心组成部分。根据 README.md该示例演示了标准 Agent 编排 沙箱 Agent挂载工作区、shell 命令、输出目录、运行时选中的沙箱配置的组合其中沙箱能力包括Shell、Filesystem以及惰性加载的Skills。也就是说本技能并非孤立文档而是被沙箱 Agent 在运行时按需加载并执行的实操指令集。二、技能元数据frontmatter 如何决定触发时机SKILL.md以 YAML frontmatter 开头--- name: prior-auth-packet-builder description: Build a concise prior authorization packet from local case files and payer policy docs. ---name技能的稳定标识符Agent 通过load_skill工具按此名称请求加载。在 support_agents.py 中沙箱 Agent 的指令明确要求先调用load_skill加载prior-auth-packet-builder然后阅读其SKILL.md。description技能的语义摘要是模型判断当前任务是否需要该技能的依据。技能正文第一句进一步界定了触发条件Use this skill when a case requires prior authorization review, referral validation, imaging review, or payer-specific policy checks.即当病例涉及预先授权审查、转诊referral核验、影像学审查、或特定保险方payer策略核对四类场景之一时才应启用本技能。这种description 广而告之、正文精确触发的写法是编写可被 LLM 可靠检索的技能文档的通用模式。三、核心工作流五步构建资料包技能正文给出了严格的五步工作流每一步都对应沙箱 Agent 的一次工具调用或文件操作1. 检查病例文件首先检查沙箱工作区中的case/scenario.json与case/transcript.txt。这两个文件并非预置在技能目录中而是由工作流运行时动态挂载的在 workflow.py 的_build_manifest中case目录被构造成Dir其scenario.json内容来自ScenarioCase模型scenario.model_dump(modejson)transcript.txt来自场景的对话记录scenario.transcript。病例的 JSON 与对话文本均来自 data/scenarios 下的六个内置场景例如prior_auth_confusion_ct.json聚焦预授权与受理分流混淆、messy_ambiguous_knee_case.json触发人工审批流程。2. 检索策略库双保险命令在policies/目录中检索保险方payer、预授权、转诊、影像学与 PPO 相关策略指引。技能要求将首选搜索与回退搜索合并为一条 shell 命令执行rg -n -i prior authorization|prior-auth|imaging|referral|billing|PPO|Blue Cross policies || grep -RniE prior authorization|prior-auth|imaging|referral|billing|PPO|Blue Cross policies这条命令有两个设计要点首选rgrg -n -i递归默认、带行号-n、忽略大小写-i地搜索多个关键词。关键词覆盖了预授权两种拼写prior authorization/prior-auth、影像学imaging、转诊referral、计费billing、PPO 计划与保险方品牌Blue Cross。回退grep当rg因启动器launcher或引导bootstrap失败而无法完成搜索时用 POSIX 可移植的grep -RniE-E扩展正则接力。技能明确警告Anrglauncher or bootstrap failure is not evidence that there are no policy matches.——即rg运行失败绝不等于策略库中没有匹配项Agent 不得据此提前得出空结果结论。这一规则同时被写进了沙箱 Agent 的系统提示support_agents.py并在 workflow.py 的WorkflowHooks.on_tool_end中被监控当检测到一条命令同时包含rg与grep -RniE且退出码为 0 时会被记录到context.policy_search_commands作为后续校验确实执行过策略搜索的证据。本技能检索的policies/目录policies共包含 13 份 Markdown 策略文档与搜索关键词直接对应例如blue_cross_ppo_prior_auth.mdPPO 成员在住院手术、超 $1,500 门诊手术、与手术规划绑定的高级影像学检查时需要预授权膝盖手术咨询本身无需预授权但咨询后开具的 MRI/CT 若在医院门诊部执行可能需要转诊状态 pending 时应先转授权审查再安排影像。blue_cross_referral_rules.md、referral_pending_sop.md转诊核验与待定转诊的标准处理流程。orthopedic_imaging_policy.md、knee_surgery_medical_necessity.md影像学与手术必要性判定。auth_review_queue_routing.md授权审查队列的路由规则。human_escalation_policy.md人工升级策略。3. 只读取最相关的策略文件检索命中后技能要求只读取最相关的策略文件Read only the most relevant policy files避免全量读取拖慢执行、稀释上下文。这与Skills能力文档中读取SKILL.md时只读足够的部分按需加载references/等子目录的原则一脉相承skills.py。4. 生成output/policy_findings.md创建output/policy_findings.md必须包含以下逐字精确的五个小节标题## Case summary## Matched policy files## Prior authorization## Referral## Missing information同时要求每个匹配到的策略文件都必须以文件名形式被引用Cite each matched policy by its filename。5. 生成output/human_review_checklist.md创建output/human_review_checklist.md内容需覆盖三类信息人工审查员human reviewer应核验什么应向患者说明什么该病例应由哪个队列queue承接。四、收尾门禁finalize_policy_packet是唯一完成条件技能明确了两条硬性规则只有两个工件policy_findings.md与human_review_checklist.md都存在之后才能调用finalize_policy_packet整个工作流只有在finalize_policy_packet成功后才算完成。该门禁在源码侧有多层强制校验。首先finalize_policy_packet工具通过is_enabled钩子packet_ready控制可用性workflow.py只有满足以下三个条件才允许被调用——技能已加载context.policy_skill_loaded为真已记录过策略搜索命令context.policy_search_commands非空output/目录中同时存在REQUIRED_POLICY_ARTIFACTS定义的两个文件human_review_checklist.md与policy_findings.md。其次工具本体workflow.py执行严格验证policy_findings.md必须包含全部五个必需小节标题REQUIRED_POLICY_FINDINGS_HEADINGShuman_review_checklist.md不得为空传入的matched_policy_files必须全部存在于policies/目录通过POLICIES_ROOT.glob(*.md)比对不允许引用未知文件每个匹配文件的名字必须出现在policy_findings.md正文中必须引用实际检查过的策略文件的机器化实现。校验通过后工具将把结构化结果封装为SandboxPolicyPacket见 models.py包含matched_policy_files、generated_files、shell_commands、policy_summary、human_review_recommended五个字段返回给编排层。而在沙箱 Agent 侧tool_use_behavior{stop_at_tool_names: [finalize_policy_packet]}support_agents.py进一步确保一旦调用finalize_policy_packet成功Agent 立即停止工具调用不再产生额外动作。工作流结束时workflow.py 的_copy_output_files会把沙箱output/中的工件复制到仓库.cache/healthcare_support/output/scenario_id/目录并对缺失工件、缺失小节标题、未引用真实策略文件等情形再次兜底校验。五、规则清单可操作性优先的执行纪律技能以Rules清单收束全部执行纪律用定向搜索而非大范围文件读取Use targeted searches over broad file reads仅在rg无法完成搜索时才使用grep -RniE回退只引用实际检查过的策略文件输出保持简洁、可操作concise and operational只有finalize_policy_packet成功才算完成若转诊状态 pending 且预授权情况不明确应建议人工审查。其中转诊 pending 预授权不明 → 推荐人工审查这一规则与策略库blue_cross_ppo_prior_auth.md中如果转诊状态 pending应在安排影像前转授权审查队列的条款互相印证也对应SandboxPolicyPacket.human_review_recommended字段的语义仅在策略检索或病例输入显示授权/转诊细节缺失、需要人工核验后再答复时才置为truesupport_agents.py。六、技能如何被沙箱 Agent 加载LazySkillSource 机制本技能并非预置在沙箱镜像中而是通过Skills能力的LocalDirLazySkillSource从宿主机按需注入support_agents.pycapabilities[ Shell(), Filesystem(), Skills( lazy_fromLocalDirLazySkillSource( sourceLocalDir(srcskills_root), ) ), ],其中skills_root指向examples/sandbox/healthcare_support/skillsworkflow.py。在 skills.py 中LocalDirLazySkillSource会扫描宿主机技能目录下的子目录定位每个子目录中的SKILL.md生成技能元数据当 Agent 请求加载某技能时load_skill工具把对应目录含SKILL.md及其脚本、引用文件复制进沙箱的skills_path。这也是为什么技能正文开头要求 Agent 先调用load_skill加载prior-auth-packet-builder然后读取其SKILL.mdsupport_agents.py。同时沙箱工作区的policies/目录通过LocalDir条目直接挂载宿主机的策略库case/与output/分别作为输入与产物目录workflow.py这与技能工作流第一步检查case/和第四、五步写入output/一一对应。七、运行与验证在仓库中实际跑通该技能该技能随 healthcare_support 示例一起分发可通过 CLI 直接运行。在仓库根目录执行uv run python examples/sandbox/healthcare_support/main.py常用选项详见 README.md# 列出全部内置场景 uv run python examples/sandbox/healthcare_support/main.py --list-scenarios # 指定场景运行预授权与受理分流混淆案例最能触发本技能 uv run python examples/sandbox/healthcare_support/main.py --scenario prior_auth_confusion_ct # 触发人工审批流程的复杂病例 uv run python examples/sandbox/healthcare_support/main.py --scenario messy_ambiguous_knee_case # 清空共享 SQLite 会话记忆后运行 uv run python examples/sandbox/healthcare_support/main.py --reset-memory # 无人值守模式自动回答审批提示 EXAMPLES_INTERACTIVE_MODEauto uv run python examples/sandbox/healthcare_support/main.py --scenario messy_ambiguous_knee_case运行结束后沙箱生成的policy_findings.md与human_review_checklist.md会被复制到.cache/healthcare_support/output/scenario_id/供人工检查编排器最终输出的CaseResolution结构化结果models.py包含policy_summary、route_to_human、handoff_id、patient_facing_response等字段。需要注意该示例是演示用途而非生产医疗系统所有患者、保险方与策略数据均为合成数据README.md。八、对技能编写者的可复用经验从这份SKILL.md中可以提炼出在 openai-agents-python 沙箱中编写高质量技能文档的通用范式frontmatter 的 description 决定召回用一句话写清技能能做什么让 LLM 在任务与技能之间建立可靠映射正文首句界定触发条件明确什么场景该用本技能避免误触发工作流步骤可执行化每一步对应具体的文件、命令或输出而不是抽象目标命令双保险首选高性能工具rg POSIX 可移植回退grep并明确工具失败 ≠ 无结果输出工件规格化用精确的小节标题约定输出结构使下游程序如finalize_policy_packet的标题校验、_copy_output_files的引用校验可以机器化验证收尾门禁单一化只保留一个完成动作如finalize_policy_packet配合is_enabled条件与stop_at_tool_names强制 Agent 在产物齐备后才能结束。九、小结prior-auth-packet-builder是一个麻雀虽小、五脏俱全的沙箱技能范本它以SKILL.md为单一入口通过 frontmatter 声明触发条件、五步工作流约束执行路径、双保险检索命令保障策略召回、两类规格化工件承载输出、finalize_policy_packet作为唯一收尾门禁并在 workflow.py 与 support_agents.py 中获得了从技能加载、命令监控到工件校验的全链路强制落地。阅读本文后你既可以直接运行 healthcare_support 示例观察该技能的真实执行也可以参照其结构为自有业务编写可被沙箱 Agent 可靠加载、可被机器校验的SKILL.md技能文档。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考