phionyx-openai-agents

Status: alpha (v0.1.0a4). TracingProcessor adapter implemented; a unit + integration test suite passes.

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 with an optional signature. No independent party has verified these records.

Where this fits

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

• Engine — phionyx-core (current release on PyPI): the deterministic runtime (46-block canonical pipeline, signed audit chain). Its Reasoned Governance Envelope (RGE) is 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 (current release on PyPI): the self-claim gate that records each agent self-claim as an RGE evidence record.
• Format — ai-runtime-evidence-protocol (AIREP) (experimental prerelease published 9 September 2026; the v0.1 line frozen and supported): 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. AIREP v0.2.0-beta.1 was published on 9 September 2026 as an experimental prerelease: it ships a first-party Python producer for Decision, Control, Execution and Effect artifacts, runnable lifecycle examples and structured reconciliation; the v0.1 line remains frozen and supported. External implementation results are version- and role-specific — an independently authored producer measured against frozen v0.1.2, and an independently implemented consumer/verifier measured against an earlier v0.2 handoff — and they do not establish same-beta producer-to-consumer interoperability.

This package is an adapter (its own version line: v0.1.0a4). 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 Phionyx envelope records (the adapter's native schema) from SDK traces; it does not produce AIREP records, and similar fields do not establish AIREP conformance.

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 link recorded payload hashes. They are unsigned by default; Ed25519 signing or demo-only HMAC must be explicitly configured. Hash checks alone do not authenticate an operator or prevent a party from rewriting and rehashing the whole chain.

Verification boundary

verify_chain() checks payload hashes, previous-hash links and turn order. Its legacy ok field refers only to those checks. Every report now also returns verification_scope: HASH_CHAIN_ONLY and signature_verification: NOT_EVALUATED, including failures and empty input. A signature-only edit does not change the hash result; no signature is checked. Empty input returns ok: null / NOT_MEASURED, never PASS. For Ed25519 authentication a separate verifier must check the signature against a trusted public key. Capture completeness and truth need additional evidence. These adapter envelopes are not native AIREP artifacts.

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"Hash chain checks: {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})
Hash 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.0a4

• ✅ 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 in that test — no ordering gaps observed under the tested contention, which is not a general absence of race conditions.
• ✅ Defensive serialization — minimally-attributed Trace/Span objects degrade to unknown / None without raising in the covered cases.
• ✅ register() defers SDK import — package loads cleanly without openai-agents installed.
• ✅ Unit + integration test suite — 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.0a4: a v0.1.0 stable release that locks the envelope schema against the current phionyx-core (current release on PyPI); 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; current release on PyPI)
• ai-runtime-evidence-protocol (AIREP) — vendor-neutral open format for per-decision AI evidence receipts; this adapter's outputs are Phionyx envelope records, not AIREP 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 RGE evidence record)
• phionyx-eval-inspect — Inspect AI bridge companion (interop-only; no UK AISI endorsement claim)