OpenAI Provider

Purpose: configure, validate, execute, evaluate, and inspect OpenAI workloads through one versioned Actspan provider contract.

This is the first complete provider reference. It separates the upstream OpenAI API from Actspan resources in the same way that infrastructure documentation separates a provider from the resources managed through it.

Start Here

Complete the local workflow before reading the operation catalog or individual field tables.

Install the public CLI and matching examples using the installation guide. Enter the extracted data-enrichment workspace:

cd "$HOME/actspan/actspan-examples/openai/data_enrichment"
actspan --version
actspan init workspace.yaml

Expected: the version contains 0.2.0. This path uses the bundled OpenAI adapter and needs no private repository clone or independent plugin download.

On a fresh workspace, init creates .actspan.env in this directory containing only the local portal setting:

ACTSPAN_PORTAL_DISABLED=1

Export your OpenAI key in the shell before the live commands below:

export OPENAI_API_KEY="<your-openai-api-key>"

Init preserves an existing portal configuration. See Configure a local workspace for setup details. Then run:

actspan validate workspace.yaml
actspan preview workspace.yaml
actspan run workspace.yaml data_enrichment \
  --input-text "Analyze NVIDIA (NVDA)"
actspan eval run eval_summarize_data_enrichment.yaml \
  --mode smoke \
  --fail-on-constraints
actspan runs

preview is intentionally static and makes no OpenAI request. run and live evals require valid credentials and provider access.

Expected result: validation accepts the workspace, preview shows its plan, run returns a run ID and structured output, and the smoke eval reports whether its declared constraints passed.

Provider Status

Property	Value
Provider type	`openai`
Provider source	`actspan/openai`
Python distribution	`actspan-provider-openai`
Independent adapter in this handoff	`0.1.1`
Plugin API	`1.0`
Upstream API generation	OpenAI `/v1`
Authentication	`OPENAI_API_KEY`
Default endpoint	`https://api.openai.com/v1`
First-class action	`openai_response` -> `responses/create`

The provider plugin version and OpenAI's /v1 API path are independent. Actspan locks an exact plugin artifact while the plugin owns the OpenAI operations and request schemas it supports.

Resource Model

Actspan object	Purpose	OpenAI relationship
`actspan.required_providers`	Select and constrain the provider plugin	Pins `actspan/openai`
`providers`	Declare credentials, endpoint, timeout, and routing alias	Creates an OpenAI provider binding
`schemas`	Define the required application output contract	Used for structured OpenAI responses
`actions.openai_response`	Author one provider-native Responses API call	Maps to `responses/create`
`tools`	Register callable capabilities and argument contracts	Compiled into OpenAI function or hosted tools
`agents`	Add runtime limits, memory, tools, policy, and eval bindings	Wraps a prompt or materialized action
`workflows`	Order calls, pass outputs, branch, and select final output	Orchestrates one or more OpenAI operations
policy file	Define allowed models, tools, budgets, and admission behavior	Evaluated before governed execution
eval config	Define datasets, checks, graders, and constraints	Measures behavior and observable evidence
`.actspan.lock.yaml`	Record exact provider and workspace dependency identity	Generated by `setup`/`lock`
Run Ledger	Record execution, usage, cost, policy context, and evidence	Written locally and optionally reported to the portal

Reference Pages

Block-By-Block Reference

Block	Detailed reference
`actspan`	Runtime and provider requirements
`providers`	OpenAI provider bindings
`meta`, `exec`, `execution`, `defaults`	Workspace control blocks
`schemas`	Application output contracts
`actions.openai_response`	OpenAI Responses calls
`tools`, `mcpServers`	Tools and MCP
`prompts`	Direct OpenAI operations
`agents`	Governed agent identity
`workflows`	Orchestration and data flow
Policy file	Deterministic controls
Eval file	Datasets, checks, and constraints
Generated evidence	Lockfile, Run Ledger, artifacts, and portal

Start with the complete data-enrichment workspace when you want to see every block assembled before reading individual field tables.

Worked Examples

Browse the OpenAI example catalog for walkthroughs on this website. Use examples supplied with your handoff; optional gateway or release-evidence demos may need additional files and a guided setup. The first workflow uses the supplied OpenAI data-enrichment workspace.

Data enrichment: research, summarize, inspect, and evaluate.
Planning helper: ask for missing information and resume a workflow.
Customer service: simulated tools, routing, and human review.
Customer service template: compact branching and a review checkpoint.
Support chat agent: local knowledge, fixture records, and structured follow-up decisions.
Release and evidence: connected pilot controls and evidence collection.

Control Boundary

Actspan validates and governs executions routed through its CLI, SDK, runtime adapter, or connected control-plane path. A direct OpenAI SDK request made outside those paths is not claimed as governed. Provider-hosted tools can add runtime context and cost that static preview cannot know in advance; preview marks those estimates as lower-confidence rather than presenting false precision.