welt-io-openai-agents

The OpenAI Agents SDK (Python) adapter for Welt's wire contract.

Install

uv add welt-io-openai-agents

Usage

See examples/agent — the smallest complete agent built on this package (text streaming, tool use, file output, file input, and human-approval tools), with the model on Amazon Bedrock's OpenAI-compatible endpoint. The sections below explain the adapters it wires in.

Supported Versions

Welt

While both are 0.x, a welt-io-openai-agents 0.Y release supports Welt v0.Y. From 1.0 on, a release supports any Welt release that shares its major version, and the minor versions move independently. Support is best effort either way, and other combinations come with no guarantee.

OpenAI Agents SDK

The badge at the top states the range this release installs against. Every push and pull request runs the suite at both ends of it: the declared floor, and the newest release CI has picked up. That is best effort rather than a guarantee — the floor is where the suite was last seen to pass, so a later release may raise it, and no ceiling is declared at all. openai comes along as a dependency and carries no floor of its own, because the Agents SDK asks for a newer one than anything here needs.

The badge follows the current release. For the range an older release declared, read that release's own metadata on PyPI.

Something misbehaving inside that range is worth an issue.

API

The wire between Welt and the agent is JSON, specified by Welt's wire contract — plain OpenAI Agents SDK values do not fit it in either direction. Two functions adapt the inbound payload, one the outbound stream.

Inbound

decode_messages(messages)

Turns Welt's Converse-shaped messages — built from the Slack thread, file bytes base64-encoded — into role/content input items that feed Runner.run_streamed as-is:

Each file-carrying block becomes the data URL the Responses API expects in place of the Converse format token, and the base64 data stays base64 — a data URL carries it as it came. A video block raises ValueError rather than dropping silently: there is nothing to rebuild one into, and a silent drop would leave the model answering a conversation with a piece missing.

decode_interrupt_responses(responses, state)

Applies Welt's resume payload — a mapping of interrupt id to the answer a human chose and the widget it came from — to the RunState the interrupted run left behind, and returns that state, which feeds Runner.run_streamed directly, answering every pending question at once:

pending = state.get_interruptions()  # read before decoding, for renderable_events
decode_interrupt_responses(payload["interrupt_responses"], state)
result = Runner.run_streamed(agent, state)

The SDK resumes from the state rather than from a payload, which is why this adapter takes both arguments where its siblings take one. The widget decides what each answer means:

A press is identified by the widget it came from — Welt says which widget produced each answer, so a typed "approve" is read where meaning belongs: it reaches the model as the tool's answer. An answer whose id names no pending approval of the state raises ValueError, since resuming the wrong run would act on questions nobody was asked.

The interrupt ids are the tool calls' own ids, as emitted by renderable_events; the state is the host app's to stash when an interrupt event goes by (see the example agent).

What arrives is taken as correct

Welt builds the payload and checks its own output against the wire contract before releasing it, so these two functions do no field validation of their own. A payload that departs from the contract is a bug on the sending side rather than an input to guard against, and it surfaces as an ordinary error from whatever touches it first — a KeyError or a TypeError here, or a refusal from the SDK or the model's endpoint further on.

The one thing decode_messages refuses outright is a content block of a kind Welt never sends. A messages turn carries only text, image, document, and video blocks; a toolUse or toolResult block is not a malformed one of those but a forged conversation turn, and rebuilt into history it would let a caller that is not Welt put words the model treats as its own past tool calls and their results into the run. It raises ValueError. This is a trust-boundary check, not the field validation the contract otherwise saves you from.

Outbound

renderable_events(result, files_from=..., pending_approvals=...)

Reduces a Runner.run_streamed result — whose stream events wrap values Welt does not render — to the events Welt renders:

Reasoning deltas stay off the wire: models like gpt-oss think aloud before they answer, and the wire has no place for reasoning — only the answer streams.

A tool hands files to the model for either of two reasons — to have it read them, or to give them to the human — and only the agent knows which is which, so name the tools whose files belong in the thread:

async for event in renderable_events(result, files_from={"create_sample_file"}):

A tool left out keeps its files to the model: one that reads a PDF for the model does not drop it into the thread as a side effect. A tool named there returns the file as file content, which the model reads and Welt uploads:

return [
    {"type": "text", "text": "Created sample.csv."},
    {
        "type": "file",
        "filename": "sample.csv",
        "file_data": b64encode(csv).decode("ascii"),
    },
]

Uploaded names come from the part's own filename; parts without one are named by their media type when a data URL carries it (file.pdf, image.png). A part pointing at its file instead — a file id, an http URL — carries nothing to upload and stays off the wire.

One caveat: whether a tool may return file content at all is the model endpoint's call, not this adapter's. The OpenAI platform accepts it; Bedrock's OpenAI-compatible endpoint takes a tool's output only as a string and rejects the request otherwise — so on Bedrock a tool cannot hand the model a file, and a file for the thread goes on the wire as a file event the host app yields itself, beside the events this function produces. The example agent shows that pattern.

The stream names the tool behind each output itself, except on a resumed run, where the approved tools' calls streamed before the interrupt: pending_approvals — the interruptions of the state being resumed, read before the answers are decoded — names those.

Each event carries only what Welt reads, and an event with nothing to render — a delta the model left empty, a file with no bytes — is not sent at all.

Gating tools with needs_approval

The SDK's interrupts are tool approvals: a tool declares needs_approval=True (or a callable deciding per call), and the run pauses before the tool's body starts — the tool itself carries no approval code, which is what lets a tool the agent did not write, from a library or an MCP server, be gated the same way. It works over Welt as-is:

@function_tool(needs_approval=True)
def sample_dangerous_action(action: str) -> str:
    ...

A run that stops on approvals ends its stream with one interrupt event per pending approval. There is no free-form interrupt in this SDK — no agent code declares a question of its own — so the question's shape is this adapter's, not the agent author's: the call's name and arguments as the message, Approve / Reject buttons, and a free-text field for answering on the tool's behalf. The inbound table shows what each answer does; Welt's Interrupts doc covers the Slack side — how the question renders, who can answer, multiple questions, and expiry.

On the SDK side:

• Resume is a state round trip. An interrupted Runner.run_streamed result yields its RunState via to_state(); the host app stashes it, applies the answers with decode_interrupt_responses, and runs the same agent again with the state as input. An in-memory stash works on AgentCore Runtime, where each session keeps its own microVM.
• Welt resumes once every question is answered. There is no partial resume on the wire, so the state's approvals are all applied in one call.
• Approved tools run on the resumed stream. Their calls streamed before the interrupt, so hand renderable_events the state's interruptions as pending_approvals — that is how their files keep flowing on resume.

License

MIT