[igalshilman]

Session objects and agents (preview)

Two new packages, shipped in the SDK's wheel and usable only through opt-in extras. Existing users get no new dependencies.

restate.sessions: virtual objects with a SQL database per key

from restate import sessions

notes = sessions.SessionObject("notes", migrations=["CREATE TABLE notes (text TEXT NOT NULL)"])

@notes.handler
async def add(ctx: sessions.SessionContext, text: str) -> None:
    await ctx.db.execute("INSERT INTO notes (text) VALUES (?)", [text])

@notes.view(name="list")
async def list_notes(ctx: sessions.ViewContext) -> list[str]:
    return [row["text"] for row in await ctx.db.query("SELECT text FROM notes ORDER BY rowid")]

• Storage: each key's SQLite-compatible database (ctx.db) lives in the object's state in Restate, so there's no database to run. It comes from shared-core's sql feature (8.3.0), bound with PyO3 in src/sessions.rs. Its futures run on the asyncio loop thread, and writes go straight into the VM.
• Handlers and views: handlers run one at a time per key; views run beside them. Transactions are async with ctx.db.transaction() as tx, with tx.send(...) committed together with the transaction.
• Recovery and cancellation: handlers run with explicit recovery (explicit_recovery as a handler and service key #265): a retried attempt runs again from the start, against what was committed, instead of replaying a journal. Explicit cancellation (Add explicit cancellation (preview) #264) is opt-in per handler; the agents use it to stop a turn.
• Calls: typed calls and sends, await ctx.call(handler, arg, key=...) and ctx.send(handler, arg, key=..., delay=...).
• Serving: sessions.app(...) gives an ASGI app (with the services agents need beside them), served like any Restate app: asyncio.run(restate.serve(sessions.app(notes))) (Add restate.serve: serve an app over HTTP/2 #266), or any ASGI server.
• API/implementation split: the API is declared as Protocols (_api.py), and decorated handlers stay plain functions, so tests can pass fakes.

restate.agents: AI agents in session objects

• AgentObject: one conversation per key, with built-in views (status, stop, pending, signal, notifications, watch, messages, sync, clear) and a signals companion object.
• Tools for any framework: tool, plus tools that are Restate itself: call, send, workflow, subagent, wait_for_signal. Each tool call is made once.
• restate.agents.langgraph (langgraph extra): LangGraph's checkpoints live in ctx.db (SqlCheckpointSaver). Each step is stored before the next starts.
• restate.agents.pydantic_ai (pydantic_ai extra): the conversation is stored before each model request and with each response.
• Shared behaviour: a crash in a tool resumes it with the same call id without asking the model again; a stop ends the turn as cancelled; a provider's refusal fails with 424 and names what to fix.

Changes to the SDK itself

Explicit cancellation (#264), the explicit_recovery key (#265) and restate.serve (#266), which this builds on, are merged. Beside the new packages:

• _internal.pyi: types the native sessions API.
• Small fixes: tests/connect.py's fake peer no longer leaks failed futures into later tests, and deprecated context-manager annotations are fixed in ext/pydantic.

Dependencies

• [project] dependencies is still empty.
• New extras: langgraph; pydantic_ai now also lists pydantic. (The serve extra comes with Add restate.serve: serve an app over HTTP/2 #266.)
• Lazy imports: each integration imports its framework only when used. Importing one without its extra raises an ImportError naming the extra, and tests/agents_imports.py checks this.

Things to look at

• Wheel size: sql adds a SQLite-compatible engine and foyer's page cache. A local unstripped release build of the extension is 29 MB (macOS arm64); compare with CI's wheel artifacts.
• Restate version: session objects preload only their database's head (state_preload), which needs restate-server 1.8 or later.
• Preview status: the API is a preview. Anthropic and OpenAI integrations, structured output and a testing helper follow in later PRs.

API review

A developer-experience review of the public surface, read as an experienced Python developer would read it, led to these changes in this PR:

• Flat calls instead of curried ones.
• migrations= instead of schema=.
• wait_for_signal and PerSession.
• A smaller restate.agents namespace.
• SqlError that can be caught.
• Errors at definition time (a lone string as migrations, a sync handler, a reserved name).
• RESTATE_AGENT_MODEL.
• PEP 257 / Google-style docstrings throughout.

Left for follow-ups:

• A restate.sessions.testing helper with an in-memory host.
• A scalar() read helper.
• An explicit only= in place of RESTATE_SERVE_ONLY.
• Tool parameters injected by annotation.

Testing

• Static checks: ruff, pyright (strict for sessions/agents), mypy, basedpyright, cargo fmt and clippy.
• The full suite passes on 3.14 and 3.10, including end-to-end tests against a real Restate server.
• The agent integrations are tested on scripted models: crashes mid-tool, stop and cancel, refusals, wrong tool arguments, and per-user options.
• tests/examples_agents.py runs every example's commands, and runs one example as a program over HTTP/2.
• A new CI job, "Install without extras", installs the built wheel alone into a fresh environment (Python 3.10 and 3.14) and runs scripts/check_no_extras.py:
  • nothing is installed beside restate-sdk, and import restate loads neither new package;
  • an ordinary app, and session objects and agents, serve;
  • each optional part fails only when used, naming its extra.

🤖 Generated with Claude Code

[github-actions]

Test Results

  8 files  ±0    8 suites  ±0   3m 51s ⏱️ -4s
 71 tests ±0   71 ✅ ±0  0 💤 ±0  0 ❌ ±0 
322 runs  ±0  322 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit 16ed3ec. ± Comparison against base commit 39bb159.

♻️ This comment has been updated with latest results.

[pullfrog]

Important

Three defects should be fixed before merge. The selector can stall a handler until the inactivity timeout. The agents' sync view returns a new revision alongside stale messages. The pydantic_ai integration can ask the model a second time after its answer was already stored. Smaller items are inline.

Reviewed changes

This is a first review of the whole PR: the native SQL binding, restate.sessions, restate.agents with its LangGraph and pydantic_ai integrations, and the small SDK typing changes.

• src/sessions.rs: binds shared-core's sql::Database to PyO3. Calls run on the asyncio loop; writes go directly into the VM, and Python handles waits.
• restate.sessions: SessionObject with exclusive handlers (explicit recovery) and shared views, transactions with an outbox for tx.send, migrations, a single-loop FutureSelector hooked into ServerInvocationContext, and app/serve.
• restate.agents: AgentObject with built-in views, a signals companion object, durable tools (call, send, workflow, subagent, wait_for_signal), and the conversation log.
• LangGraph and pydantic_ai integrations: SqlCheckpointSaver keeps checkpoints in ctx.db; pydantic_ai stores the conversation before each model request and with each response.
• SDK, build and tests: an _internal.pyi stub, annotation fixes, lint-rust added to just verify, new serve/langgraph extras, strict type checking for the new packages, and extensive tests and examples.

Specialist reads of the Rust binding (locking, wake-ups, VM borrows, page cache) and of SqlCheckpointSaver's compliance with the LangGraph contract found no defects.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}

[pullfrog]

ℹ️ All six earlier findings are fixed. One small follow-up is inline.

Reviewed changes

This run covers the commits since d1c9208: fixes for the earlier review, restate.serve replacing sessions.serve, and a CI job that installs the wheel without extras.

• Selector stall fixed: FutureSelector now sets _missed when a wait is registered while the loop is between passes. It takes another pass rather than blocking in receive(), and a new test covers a flush that yields.
• sync page now matches its revision: the view reads the revision first, then gets the page from a call to its own messages view, a new invocation that starts after the read.
• Stopped turns report calls that returned: both integrations' _close now use _calls.outcomes and cut_off_result. A call whose Restate call returned is recorded with its error or with RETURNED_UNRECORDED, not CANCELLED.
• pydantic_ai fixes: a retried run that already stored a final text response marks that response as the answer instead of asking the model again. The message adapter now stores bytes as base64, as pydantic-ai's own adapter does.
• Outbox docstring corrected: Transaction no longer promises that sends repeated by a retried attempt are dropped.
• restate.serve replaces sessions.serve: examples, docstrings and the README now use asyncio.run(restate.serve(sessions.app(...))).
• CI job without extras: no-extras builds the wheel and installs it alone on 3.10 and 3.14. scripts/check_no_extras.py then checks that nothing else is installed, that import restate loads neither new package, and that each optional part raises an ImportError naming its extra only when used.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}

[pullfrog]

This line still sets status="error" when cut_off_result returns RETURNED_UNRECORDED. langchain-anthropic turns that status into is_error: true on the tool_result block. So the model is told the call failed, while the text says it happened, which is the mixed signal this change set out to remove. Set "error" only when the result is not RETURNED_UNRECORDED. The pydantic_ai _close has no status flag, so it is unaffected.