OpenAI Agent SDK Tracing: Add the Missing Health Receipts

OpenAI agent SDK tracing is the right first record for explaining what happened inside an agent run. It is not, by itself, proof that the worker is reachable now, that a scheduled run started, that an external effect landed once, or that the promised deliverable exists. The reliable default is to keep the built in trace, give every run a stable non secret ID, and join that trace to separate runtime and outcome receipts before assigning a health verdict. This guide is pinned to the Python openai agents 0.19.0 release metadata retrieved on July 28, 2026. The package had been uploaded on July 27, so verify the reference for your installed version before copying configuration into a long lived service. Start with the trace the SDK already gives you The current OpenAI integrations and observability guide says tracing is enabled by default in the normal server side SDK path. A run can emit structured records for model calls, tool calls, handoffs, guardrails, and custom spans. The Python tracing reference adds task, turn, agent, generation, function, handoff, guardrail, and audio span details. That is valuable execution evidence. It answers questions such as: Which agent and model turn ran? Which function tools were called, and in what nesting order? Did a guardrail or handoff occur? Where did an exception or long duration appear? Which runs belong to the same workflow or conversation? Use one higher level trace when several Runner.run() calls implement one business operation. Put a random, non secret run ID in both group id and metadata so the trace can be joined to application records. Do not put customer content, credentials, or a complete deliverable into that ID. The sensitive data setting matters. The official Python reference says generation spans and function spans can contain model and tool inputs and outputs, and that sensitive capture is enabled by default. trace include sensitive data=False reduces that exposure. It does not redact data that you deliberately place in custom span metadata, so keep custom evidence minimal as well. The finally block solves a narrower problem. The default batch processor exports in the background every few seconds and flushes on process exit. For a queue worker that must make its trace visible before acknowledging a job, call flush traces() after the trace context closes. A flush confirms that buffered trace records were handed to their processor; it still does not prove the external business outcome. Draw the boundary where the trace stops A trace describes the path observed by its instrumentation. Agent health asks whether the surrounding system is working now and whether useful work reached its destination. Those clocks and evidence sources are different. Consider a trace that ended cleanly at 10:00. At 10:05 the worker can be offline. A 10:15 schedule can be missed without producing any new trace. A tool span can contain a successful HTTP response while the destination later rejects the transaction. A final model answer can say “done” while the expected file is absent. Treat the trace as one column in an evidence join: Health question What the SDK trace can show Additional receipt required Did the instrumented run execute? Trace and span lifecycle Trace export freshness and run identity Is the runtime reachable now? Nothing after the last observed span Heartbeat with an expiry threshold Did scheduled work start on time? A trace if the run started Expected run record and start deadline Is the agent waiting legitimately? A paused path or approval related activity Approval owner, deadline, decision ID, and resume token Did a side effect happen once? Tool attempt and returned data Destination side idempotency or reconciliation receipt Is the requested deliverable correct? Model and tool activity Deterministic artifact check or explicit acceptance rule This separation prevents three expensive mistakes. First, do not convert “trace ended” into “healthy.” It means the instrumented execution path ended. Health requires fresh runtime evidence and an outcome receipt. Second, do not convert “trace absent” into “failed” immediately. The background exporter may still be inside its delivery window. Compare export age with a documented grace period; classify the run as uncertain while the evidence is late. Third, do not convert “paused” into “stuck.” A pause with an authorized owner, a live deadline, and a resumable decision token is waiting. It becomes stuck when the dependency contract is broken or progress fails after the decision. Run a five case coverage audit To make the boundary falsifiable, I built a normalized five run fixture. Each row contains a run ID and six evidence groups: trace, runtime, schedule, approval, effect, and outcome. The audit applies health precedence in this order: 1. Preserve a well formed approval wait. 2. Mark an expired heartbeat unreachable. 3. Keep a recent missing export uncertain. 4. Check the expected schedule. 5. Compare the outcome receipt and digest. 6. Call the run healthy only when trace, effect, and outcome evidence agree. The core false success rule is deliberately small: The fixture produced five expected verdicts from five cases: The individual results expose why the join matters: Fixture Trace only assumption Joined verdict Evidence that changed the decision Healthy Healthy Healthy Fresh heartbeat and matching effect and outcome receipts confirm it False success Healthy False success Expected artifact receipt is missing Approval wait Stuck Waiting Authorized owner and deadline make the pause legitimate Runtime lost Healthy Unreachable Heartbeat age is 900 seconds against a 120 second limit Export pending Trace failure Uncertain export Export age is 2 seconds inside a 10 second grace window This is not a claim that every application needs the same thresholds. A batch job that runs nightly needs a different heartbeat envelope from an interactive support agent. A read only lookup may not need an effect receipt. A generated report might require a checksum, schema validation, row count floor, and HTTP 200 at its final URL. The reusable part is the evidence shape and precedence, not the sample numbers. The audit also uses normalized records rather than private Platform trace downloads or a paid live model call. That keeps it inspectable, but it leaves exporter implementation, dashboard retention, and account policy outside the experiment. Test those in your own environment. Use one run ID, but keep separate evidence stores The practical production design is a join, not a larger trace payload. Keep diagnostic spans where they are useful for debugging. Keep runtime freshness in the system that owns the worker or adapter. Keep schedule expectations beside the scheduler. Keep approval authority in the application that can resume the run. Keep effect receipts at the destination or reconciliation layer. Keep deliverable checks close to the artifact. Join them through the non secret run ID and expose freshness for every source. A health record can be compact: Do not silently treat an unavailable field as green. If the runtime heartbeat cannot be read, the runtime state is unknown. If an organization uses Zero Data Retention, note that the current Python tracing reference says tracing is unavailable for that API policy; use an approved internal processor or a different evidence design only after confirming the applicable policy and SDK behavior. The final operating rule is simple: use OpenAI Agents SDK tracing to explain execution, not to overclaim health. A healthy verdict requires a recent trace when one is expected, a reachable runtime, an honest waiting state, reconciled effects where applicable, and a verified outcome. Clear an incident only after the evidence that failed becomes fresh and passes again. Sidewisp is currently in private preview. Its intended role is to turn evidence such as reachability, progress, tool access, and verified outcomes into a clear health view; production OpenAI Agents SDK monitoring is not generally shipped today.