Skip to content

Connect OpenAI Agents SDK

Add a small Python tracing hook to your existing application. It records model inputs, model outputs and completed function-tool calls in Planisphere's existing AI Provenance pack. This connection records activity; it does not gate execution.

In the console, select Connect → Configure agent → OpenAI Agents SDK · Python. Enter the system name, environment and surface. Copy the generated installation and initialization snippets. Python 3.10+ and Agents SDK 0.22.2 are the tested target.

Install once per application process

In your application's folder and virtual environment:

python -m pip install 'openai-agents==0.22.2'
curl --fail --output planisphere_openai.py \
  https://api.planisphere.ooo/docs/examples/python/planisphere_openai.py

Set PLANISPHERE_API_KEY in your application's environment using a tenant key from Keys. Keep your existing OpenAI authentication and model selection. Planisphere does not need your OpenAI key. The helper is a downloadable file; you do not need an unpublished Planisphere package or access to a Git repository.

Add this before starting any agent runs, once per process (after a worker forks):

from planisphere_openai import connect

evidence = connect(
    system_id="claims-agent-prod",
    environment="production",
    surface="claims-workflow",
)

# Your existing Agent / Runner code follows.

For a short script, after the workflow finishes:

evidence.force_flush()
print(evidence.status())

Check pending, failed and skipped are zero. Copy last_action_key into Connect's Check receipt step. It reads the actual received record, checks its system, environment, surface and connector marker, and opens it in Records or Verify. This check creates no synthetic receipt. A matching receipt confirms one received event, not complete workflow coverage or continuous health.

Use a separate system ID for each environment if you need separate system views. Environment and surface are committed with every record, but readable metadata remains subject to the tenant's retention policy.

What is captured

Agents SDK event Planisphere record Content handling
Trace begins session_started Trace ID links the session; model is initially unknown
Completed Responses/generation span with input agent_prompt Input hashed locally
Completed Responses/generation span with output agent_response Output hashed locally
Completed function-tool span with input tool_used Input/output hashed locally; name, duration and SDK error status reported

Every record carries the configured system ID and the SDK trace ID as session context. Model prompt/response pairs carry the same span ID as their agent_id; span and parent IDs are committed as metadata. This preserves session grouping and commits the identifiers needed to correlate prompt/response pairs. It does not claim that the console reconstructs every cross-service or handoff relationship.

The helper hashes canonical JSON: UTF-8, sorted object keys, compact separators, no NaN, and Pydantic values converted with model_dump(mode="json"). Strings are hashed as JSON strings, including their quotes. Retain source material in your own environment if you need to reproduce a commitment later.

Tracing and privacy

The hook only hashes content available to local tracing processors. It does not enable tracing, change sensitive-data settings, or remove existing processors. If tracing is disabled, it receives no events. If sensitive-data tracing is disabled, some spans have no input/output; the hook reports these as skipped instead of manufacturing hashes for content it did not observe.

OpenAI's default exporter and any other installed processors continue to follow their own data policies. Hashing before sending to Planisphere does not redact data sent by those exporters. Review those settings before enabling sensitive data for local capture. See OpenAI's tracing documentation.

This first hook supports the Python Agents SDK, including Responses and Chat Completions model spans. It does not instrument direct OpenAI() calls, ChatGPT, Codex, other processes, hosted tool internals, or arbitrary business actions. It does not capture separate handoff/guardrail records. Tool success means the SDK span reported no error, not independent verification of an external effect.

Delivery and troubleshooting

Network delivery runs in a background thread with a bounded in-memory queue. The helper retries network errors, HTTP 429 and server errors up to three attempts, using a stable idempotency key. A failed delivery or full queue is counted and logged without raw payloads or keys. Failed records are not persisted for later recovery; abrupt termination can lose queued records. Call evidence.shutdown() during graceful application shutdown. This is a lightweight hook, not a durable institutional collector.

  • No records: register before running the agent; check tracing is enabled.
  • Skipped records: inspect sensitive-data settings and supported span types.
  • HTTP 401/403: check the Planisphere key and its tenant permissions.
  • HTTP 422: check event fields and whether this system requires a sequence counter.
  • Pending/failed records: inspect network access, rate limits and application logs.
  • Receipt mismatch: match Connect's system/environment/surface to the running hook.

The helper does not invent a global sequence counter for multiple workers. Use a new system ID for this integration if an existing declaration requires one. Records count toward normal Planisphere usage; OpenAI calls keep their normal provider charges.

For an example model-plus-tool run, use openai_connection_check.py. For action approval instead of passive recording, the separate planisphere_gate.py helper remains available for explicit tool-boundary enforcement.