Prototype transport-neutral durable runtime library

[shivam5]

What did you change, and why?

This is a draft interface prototype for the transport-neutral library option. It is intentionally an alternative to the provided app/server interfaces, not a proposed final API.

Developer contract

runtime = DatabricksDurableRuntime(run_agent)
await runtime.start()
await runtime.submit(run_id, request)

The library stores requests, results, heartbeats, attempts, and ordered events. The developer owns FastAPI lifecycle, request mapping, 202 responses, polling, SSE formatting, cursor handling, and recovery behavior inside run_agent.

Durable CUJ in the cookbook

• A background streamed proposal completes with requires_action.
• The client polls the persisted result and submits approval as a second run with the same session ID.
• OpenAI Agents SDK conversation state is stored in AsyncDatabricksSession.
• SDK events are persisted through context.emit() and exposed by developer-authored SSE routes.
• The approved run includes a 60-second tool call so the process can be stopped and recovered with context.is_recovery=True.

Capability	Result
Existing request/response protocol	Developer can preserve it
Background execution	Runtime primitive provided; HTTP contract developer-owned
Pod/process recovery	Supported
Durable stream replay	Storage provided; SSE route developer-owned
HITL	Two durable runs sharing one session
Final result	Stored by the runtime; polling route developer-owned

This prototype makes the cost of the library approach explicit: it has the least protocol coupling and the most developer integration work.

How do you know it works?

• 23 focused runtime/store tests pass.
• Ruff check and format pass for the cookbook files.
• Cookbook modules compile successfully.
• The OpenAI adapter imports successfully against openai-agents==0.19.4; no live model call was made.

Background and streaming client contract

Concern	Contract in this POC
Background	The runtime stores and schedules work, but the developer defines 202, run IDs, polling routes, and result mapping.
Streaming	context.emit() and runtime.events() provide durable storage; the developer defines SSE, reconnect cursors, and client behavior.
OpenAI Agents SDK client	The developer may preserve an existing route or adopt the cookbook's /runs envelope. The library does not mandate the migration.
LangGraph SDK client	langgraph_sdk can remain unchanged only if the developer implements its native routes over the runtime; the cookbook instead uses /runs.

The cookbook README includes concrete OpenAI Agents SDK and LangGraph before/after client snippets for background=true, stream=true.

[shivam5]

Interface comparison set:

• Prototype transport-neutral durable runtime library #475 — transport-neutral library; developer owns the server
• Prototype SDK provided durable entrypoint #476 — AgentCore-style @app.entrypoint; SDK supplies the app
• Prototype generic JSON durable agent server #477 — supplied generic JSON server
• Generalize long-running agent recovery and replay #467 — Responses-specific LongRunningAgentServer

The first three use the same tiny progress agent and the same run/heartbeat/event durability semantics so the developer-facing differences are directly comparable.