phionyx-openai-agents

Status: alpha (v0.1.0a3). TracingProcessor adapter implemented; 37 tests pass.

OpenAI Agents SDK tracing bridge for Phionyx runtime evidence. This package surfaces on phionyx.ai/runtime-evidence as one of the framework adapters that turn third-party agent runs into reviewer-runnable evidence.

Every Trace and Span emitted by the OpenAI Agents SDK is recorded as a hash-chained envelope entry (signed when a signer is configured; unsigned by default). Phionyx provides the trust-object substrate above the SDK's own tracing — observability records what happened; Phionyx binds it into a hash-chained envelope that a holder of the signing key can check. No independent party has verified these records.

Where this fits

Phionyx ships three distinct things, each with its own version line:

• Engine — phionyx-core (latest v0.9.0): the deterministic runtime (46-block canonical pipeline, signed audit chain). Its Reasoned Governance Envelope (RGE) is the developed alongside AIREP; a conformant projection between the two is not implemented (measured 2026-08-06: AIREP's own reference verifier rejects an RGE envelope handed to it directly).
• Gate — phionyx-pipeline-mcp (stable v0.2.0, alpha v0.3.0a1): the self-claim gate that records each agent self-claim as an AIREP evidence record.
• Format — ai-runtime-evidence-protocol (AIREP) (v0.1, experimental): a vendor-neutral open format for an AI decision receipt — one signed, hash-chained, offline-checkable record per runtime decision, readable by anyone and tied to no vendor. It is a proposed open format, not a ratified standard.

This package is an adapter (its own version line: v0.1.0a1). It bridges the OpenAI Agents SDK into the Phionyx envelope format. It is not the engine, the gate, or the AIREP format itself — it produces AIREP-shaped evidence records from SDK traces.

Why

The OpenAI Agents SDK ships its own tracing (add_trace_processor, BatchTraceProcessor, BackendSpanExporter) optimised for debugging and internal observability. It is not optimised for third-party verification: the trace stream is mutable, unsigned, and exported to the operator's choice of backend. Phionyx envelopes are append-only, hash-chained, and signed under the operator's key (Ed25519-capable; the demo default is HMAC) — they survive review even when the agent and the trace store are not trusted.

Install

pip install phionyx-openai-agents          # core
pip install "phionyx-openai-agents[sdk]"   # + openai-agents SDK

Source: github.com/halvrenofviryel/phionyx-openai-agents.

60-second usage

from agents import add_trace_processor
from phionyx_openai_agents import PhionyxTracingProcessor

processor = PhionyxTracingProcessor()    # UNSIGNED by default — set PHIONYX_OPENAI_AGENTS_DEMO=1 (demo-HMAC) or PHIONYX_OPENAI_AGENTS_SIGNING_KEY=<hex> (Ed25519); + filesystem store
add_trace_processor(processor)

# ... run any Agents SDK workflow ...

print(f"{len(processor.envelopes)} envelopes (unsigned by default; configure a signer to sign)")
print(f"Chain verifies: {processor.verify_chain()['ok']}")
processor.export_envelopes("evidence/run.jsonl")

A complete runnable example (works with or without the SDK installed) is in examples/quickstart.py:

pip install phionyx-openai-agents
python examples/quickstart.py

Expected output (mocked-SDK mode):

Mode        : mocked Trace/Span
Envelopes   : 8 ({'trace_start': 1, 'span_start': 2, 'span_end': 2, 'processor_flush': 1, 'trace_end': 1, 'processor_shutdown': 1})
Verify chain: OK (8 envelopes; 0 errors)
Exported    : 8 envelopes → /tmp/phionyx-oai-demo-XXXXXXXX/quickstart-evidence.jsonl

Span trees

The processor preserves parent_id linkage in every envelope payload, so verifiers can reconstruct the full span tree:

# A typical workflow: supervisor → worker → tool
on_trace_start(trace)
on_span_start(root)                              # parent_id = None
on_span_start(child, parent_id=root.span_id)     # parent_id = "sp-root"
on_span_start(grand, parent_id=child.span_id)    # parent_id = "sp-child"
on_span_end(grand)
on_span_end(child)
on_span_end(root)
on_trace_end(trace)

Each span_start envelope's payload exposes parent_id and span_id; together with trace_id you can reconstruct any tree shape offline without reading the SDK's own trace stream.

Status — what's live in v0.1.0a1

• ✅ PhionyxTracingProcessor — all 6 SDK TracingProcessor methods (on_trace_start/end, on_span_start/end, shutdown, force_flush) emit hash-chained envelopes (signed when a signer is configured).
• ✅ AgentMessageEnvelope as the inner record (from phionyx_core.contracts.envelopes).
• ✅ HmacSigner demo + Signer protocol for Ed25519 swap.
• ✅ FilesystemEnvelopeStore with PHIONYX_OPENAI_AGENTS_AUDIT_ROOT env-var override.
• ✅ verify_chain — detects payload tamper + broken links.
• ✅ export_envelopes — JSONL round-trip preserves chain byte-exact and re-verifies under module-level helper.
• ✅ Cross-thread emission lock — 5-thread × 20-callback test yields a dense [0..99] turn-index sequence; no race conditions.
• ✅ Defensive serialization — minimally-attributed Trace/Span objects degrade to unknown / None, never crash.
• ✅ register() defers SDK import — package loads cleanly without openai-agents installed.
• ✅ 37 tests — smoke, envelope chain, extended scenarios (multi-span tree, parent_id chains, error spans, 100-event chain, concurrent callbacks, lifecycle edges, JSONL round-trip).

Roadmap beyond v0.1.0a1: a v0.1.0 stable release that locks the envelope schema against the current phionyx-core (latest v0.9.0); and promotion of audit_chain into phionyx-core so all companion packages share one canonical implementation (see below).

audit_chain vendoring

This package vendors a copy of audit_chain.py from phionyx-langchain-langgraph. The two copies differ only in namespace constants (schema id, runtime tag, default audit root, env var, HMAC secret prefix); the canonical-JSON discipline and hash format are identical, so verifiers written once apply to both companion packages. Promoting audit_chain into phionyx-core (so the companion packages share one canonical implementation) remains a planned consolidation; until then, the vendored copies stay byte-compatible.

License

AGPL-3.0-or-later. Commercial dual-license available — contact founder@phionyx.ai.

See also

• phionyx.ai/runtime-evidence — entry pillar this package surfaces under
• phionyx.ai/evidence — Evidence Matrix: every load-bearing claim paired with a reviewer-runnable command
• phionyx-core (PyPI) — core envelope schema + Ed25519 signing (the engine; latest v0.9.0)
• ai-runtime-evidence-protocol (AIREP) — vendor-neutral open format for per-decision AI evidence receipts; this adapter's outputs are AIREP-shaped records
• phionyx-langchain-langgraph — LangChain + LangGraph bridge companion
• phionyx-mcp-server — MCP trust boundary companion
• phionyx-pipeline-mcp — agent self-claim gate companion (records each self-claim as an AIREP evidence record)
• phionyx-eval-inspect — Inspect AI bridge companion (interop-only; no UK AISI endorsement claim)