Prototype generic JSON durable agent server

[shivam5]

What did you change, and why?

This is a draft interface prototype for a supplied generic JSON server. It has the same runtime capabilities as the decorator app in #476, but the developer constructs and configures the server explicitly.

Developer contract

async def agent(payload, context): ...
async def resume_agent(payload, context): ...

server = DatabricksDurableServer(
    agent,
    on_resume=resume_agent,
)
app = server.app

The server owns the fixed JSON /invocations protocol, background and blocking execution, heartbeat recovery, final-result storage, polling, and cursor-based SSE replay.

Durable CUJ in the cookbook

• A request uses background=true and stream=true.
• A streamed proposal completes with a persisted requires_action result.
• The client submits approval as a second durable run with the same session ID.
• OpenAI Agents SDK state is stored in AsyncDatabricksSession.
• SDK events are persisted through context.emit().
• The approved run includes a 60-second tool call so the process can be stopped and recovered through the explicit on_resume callback.

Capability	Result
Request/response shape	Fixed generic JSON /invocations protocol
Background execution	Provided
Pod/process recovery	Provided through on_resume
Durable stream replay	Provided through context.emit()
HITL	Two durable runs sharing one session
Final result	Stored in the durable run row

How do you know it works?

• 27 focused runtime/store/server tests pass.
• Tests cover recovery callback selection and background stream submission.
• Ruff check and format pass for source, tests, and 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	background=true, stream=false returns 202; the server stores status/output and the client polls GET /invocations/{id}.
Streaming	The developer calls context.emit(); stream=true returns SSE and the client reconnects with ?after=<event-id>.
OpenAI Agents SDK client	An app-specific client changes to the generic /invocations envelope; the in-process Runner.run_streamed() loop remains inside the registered handler.
LangGraph SDK client	Native threads/runs calls change to /invocations; thread_id is passed as session_id. Preserving langgraph_sdk requires a protocol adapter.

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.