openai-patterns

# OpenAI 智能体模式参考 来自 OpenAI Agents SDK、深度研究及自主智能体框架的研究支持模式。 --- ## 概述 OpenAI 的智能体生态系统为 Loki 模式提供了四项关键架构创新： 1. **追踪跨度 (Tracing Spans)** - 带有跨度类型的分层事件追踪 2. **护栏与触发器 (Guardrails & Tripwires)** - 带有提前终止机制的输入/输出验证 3. **移交回调 (Handoff Callbacks)** - 智能体转移过程中的数据准备 4. **多层级回退 (Multi-Tiered Fallbacks)** - 模型和工作流级别的故障恢复 --- ## 追踪跨度架构 ### 跨度类型 (Agents SDK 模式) 每个操作都被封装在一个类型化的跨度中，以便进行可观测性分析： yaml span_types: agent_span: - 封装整个智能体执行过程 - 包含：agent_name, instructions_hash, model generation_span: - 封装 LLM API 调用 - 包含：model, tokens_in, tokens_out, latency_ms function_span: - 封装工具/函数调用 - 包含：function_name, arguments, result, success guardrail_span: - 封装验证检查 - 包含：guardrail_name, triggered, blocking handoff_span: - 封装智能体间的转移 - 包含：from_agent, to_agent, context_passed custom_span: - 用户定义的操作 - 包含：operation_name, metadata ### 分层追踪结构 { "trace_id": "trace_abc123def456", "workflow_name": "implement_feature", "group_id": "session_xyz789", "spans": [ { "span_id": "span_001", "parent_id": null, "type": "agent_span", "agent_name": "orchestrator", "started_at": "2026-01-07T10:00:00Z", "ended_at": "2026-01-07T10:05:00Z", "children": ["span_002", "span_003"] }, { "span_id": "span_002", "parent_id": "span_001", "type": "guardrail_span", "guardrail_name": "input_validation", "triggered": false, "blocking": true }, { "span_id": "span_003", "parent_id": "span_001", "type": "handoff_span", "from_agent": "orchestrator", "to_agent": "backend-dev", "context_passed": ["task_spec", "related_files"] } ] } ### 存储位置 .loki/traces/ ├── active/ │ └── {trace_id}.json # 当前运行的追踪 └── completed/ └── {date}/ └── {trace_id}.json # 按日期归档的追踪 --- ## 护栏与触发器系统 ### 输入护栏 在智能体执行**之前**运行，以验证用户输入： python @input_guardrail(bloc