Python SDK changelog

​

What’s Changed

• Pydantic AI Integration: Upgrade to Pydantic AI 2.x by @gvdongen in https://github.com/restatedev/sdk-python/pull/215
• Fix: Handle signal registration outside the main thread by @brightsparc in https://github.com/restatedev/sdk-python/pull/218
• Harness: Fix outdated env var for disabling retries by @gvdongen in https://github.com/restatedev/sdk-python/pull/213

​

What’s Changed

• Scope API for virtual objects by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/212

​

What’s Changed

• Fix request identity by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/210

​

New Features

​

(Preview) Scope and limit key to enable flow control

# Route a call into a named scope
await ctx.scope("tenant-123").service_call(MyService.process, payload)

# Add a limit key for hierarchical concurrency limits within the scope
await ctx.scope("tenant-123").workflow_call(
    MyWorkflow.run, "wf-key", payload, limit_key="api-key/user42"
)

NOTE: This API is in preview and is not enabled by default. To use it in restate-server 1.7, enable the flow control and protocol v7 experimental features via RESTATE_EXPERIMENTAL_ENABLE_PROTOCOL_V7=true and RESTATE_EXPERIMENTAL_ENABLE_VQUEUES=true (new clusters only). See https://docs.restate.dev/services/flow-control for details.

​

Signals

# Inside the invocation that wants to wait:
approved = await ctx.signal("approved", type_hint=bool)

# Inside another handler that knows the target invocation's ID:
ctx.resolve_signal(target_invocation_id, "approved", True)
# or, to wake the waiter with a terminal error:
ctx.reject_signal(target_invocation_id, "approved", "Request denied")

NOTE: Signals require restate-server 1.7 with RESTATE_EXPERIMENTAL_ENABLE_PROTOCOL_V7=true enabled.

​

TerminalError metadata

raise TerminalError(
    "Payment declined",
    status_code=402,
    metadata={"reason": "insufficient_funds"},
)

​

General improvements

• New cooperative suspensions behavior when awaiting futures (#192): the SDK now propagates the full tree of pending futures to the shared core to decide when and how to suspend, resulting in less concurrency-quota thrashing when fanning out many requests from one handler to others.
• Cheaper ctx.run round-trips: instead of echoing the full completion message back to the SDK after storing a ctx.run result, the runtime replies with an ack message. This noticeably cuts network cost for handlers with many or large ctx.run entries.
• zstd response compression on AWS Lambda (#206): on Python 3.13 or older, install the optional dependency with pip install restate_sdk[zstd] to enable it.
• Fixed a race condition in the LangChain turnstile (#198).
• Require tool calls to carry an ID in the LangChain extension (#199).
• Journal the tool message ID (#200).
• pydantic: use current_context() in RestateModelWrapper.request_stream, fixing an AttributeError on streaming / event_stream_handler (#201).

NOTE: The cooperative suspensions and run-acks improvements above are enabled in restate-server 1.7 with RESTATE_EXPERIMENTAL_ENABLE_PROTOCOL_V7=true set up.

​

What’s Changed

• Cooperative suspensions by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/192
• Add TerminalError.metadata by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/196
• Bump shared core by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/197
• Fix race condition langchain turnstile by @gvdongen in https://github.com/restatedev/sdk-python/pull/198
• Require tool calls with ID in langchain ext by @gvdongen in https://github.com/restatedev/sdk-python/pull/199
• Bump shared core by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/202
• Journal tool message ID by @gvdongen in https://github.com/restatedev/sdk-python/pull/200
• Support zstd compression for py < 3.14 by @aelci in https://github.com/restatedev/sdk-python/pull/206
• feat: Add scopes, flow-control limit keys and signals by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/207
• fix(pydantic): use current_context() in RestateModelWrapper.request_stream (AttributeError on streaming / event_stream_handler) by @selimacerbas in https://github.com/restatedev/sdk-python/pull/201

​

New Contributors

• @aelci made their first contribution in https://github.com/restatedev/sdk-python/pull/206
• @selimacerbas made their first contribution in https://github.com/restatedev/sdk-python/pull/201

• PR 198 Fixed race condition in LangChain integration

​

What’s Changed

• Agent integrations: remove default retries by @gvdongen in https://github.com/restatedev/sdk-python/pull/190
• Add Langchain integration by @gvdongen in https://github.com/restatedev/sdk-python/pull/194

​

What’s Changed

• Logfire Tracing: fix default arguments for Tracer.start_as_current_span by @gvdongen in https://github.com/restatedev/sdk-python/pull/188

​

What’s Changed

• Use WarpBuild runners for CI workflows by @tillrohrmann in https://github.com/restatedev/sdk-python/pull/185
• Introduce RetryableError by @hatstand in https://github.com/restatedev/sdk-python/pull/184
• Add a RestateTracer and RestateTracerProvider for AI observability by @gvdongen in https://github.com/restatedev/sdk-python/pull/187

​

New Contributors

• @hatstand made their first contribution in https://github.com/restatedev/sdk-python/pull/184

​

What’s Changed

• Pydantic AI integration: upgrade pydantic ai library to 1.68.0. Disable autowrapping tools in ctx.run. Default retry strategy for LLM calls is now 10 attemps with 1 second minimum interval.
• Google ADK integration: Added RestateEventsSummarizer to wrap LLM summarization calls in durable steps and added flushing compaction events in append_event to Restate.

​

Bug fixes

• fix: #175 BidiStream SIGTERM causes CPU hot loop and pod stuck in Terminating by @brightsparc in https://github.com/restatedev/sdk-python/pull/176
• Bump shared core, bump max protocol version, update feature matrix by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/183

​

New Contributors

• @brightsparc made their first contribution in https://github.com/restatedev/sdk-python/pull/176

​

What’s Changed

• Support zstd compression in python 3.14+ by @jackkleeman in https://github.com/restatedev/sdk-python/pull/174

​

What’s Changed

• Update shared core by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/170
• Fix stacktrace propagation inside ctx.run by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/171

​

What’s Changed

• doc: fix various typos by @didier-durand in https://github.com/restatedev/sdk-python/pull/168
• Add pydantic ai by @igalshilman in https://github.com/restatedev/sdk-python/pull/167
• [extensions] Avoid global state in the ADK plugin by @igalshilman in https://github.com/restatedev/sdk-python/pull/169

​

New Contributors

• @didier-durand made their first contribution in https://github.com/restatedev/sdk-python/pull/168

​

What’s Changed

• OpenAI integration: DurableRunner with LLM retry opts and lazy session flushing by @gvdongen in https://github.com/restatedev/sdk-python/pull/164
• Add explicit tool execution synchronization by @igalshilman in https://github.com/restatedev/sdk-python/pull/165
• Cancel subsequent tools by @igalshilman in https://github.com/restatedev/sdk-python/pull/166

​

What’s Changed

• Update Google ADK extension by @gvdongen in https://github.com/restatedev/sdk-python/pull/163

​

New Contributors

• @gvdongen made their first contribution in https://github.com/restatedev/sdk-python/pull/163

​

New features :tada:

• Use context manager together with service handlers:

@contextvar
@asynccontextmanager
async def my_resource_manager():
    yield "hello"


@greeter.handler(invocation_context_managers=[my_resource_manager])
async def greet_with_cm(ctx: Context, name: str) -> str:
    return my_resource_manager.value

• Add msgspec support, works out of the box when adding restate_sdk[serde] dependency:

# models
class GreetingRequest(msgspec.Struct):
    name: str

class Greeting(msgspec.Struct):
    message: str

msgspec_greeter = Service("msgspec_greeter")

@msgspec_greeter.handler()
async def greet(ctx: Context, req: GreetingRequest) -> Greeting:
    return Greeting(message=f"Hello {req.name}!")

• Add extension modules for Google ADK and OpenAI, more info soon!

​

What’s Changed

• Add current_context() extension point by @igalshilman in https://github.com/restatedev/sdk-python/pull/148
• Add context manager support by @igalshilman in https://github.com/restatedev/sdk-python/pull/149
• Rename to invocation_context_managers by @igalshilman in https://github.com/restatedev/sdk-python/pull/150
• Rethrow TerminalError/SdkBaseException accidentally wrapped by @igalshilman in https://github.com/restatedev/sdk-python/pull/151
• feat: add msgspec support by @v1gnesh in https://github.com/restatedev/sdk-python/pull/154
• Consolidate msgspec conditional imports into a single place by @igalshilman in https://github.com/restatedev/sdk-python/pull/155
• Use DefaultSerde instead of JsonSerde for promise() default parameter by @Gustavo-Hagenbeck in https://github.com/restatedev/sdk-python/pull/157
• Support union | None return types by @igalshilman in https://github.com/restatedev/sdk-python/pull/158
• Use HttpError for the typed ingress client by @igalshilman in https://github.com/restatedev/sdk-python/pull/159
• Replace traceback.print_exc() with logger.exception() for proper logging by @Gustavo-Hagenbeck in https://github.com/restatedev/sdk-python/pull/160
• Add an optional extension module for Google ADK integration by @igalshilman in https://github.com/restatedev/sdk-python/pull/161
• Add an optional ext module for openai by @igalshilman in https://github.com/restatedev/sdk-python/pull/162

​

New Contributors

• @v1gnesh made their first contribution in https://github.com/restatedev/sdk-python/pull/154
• @Gustavo-Hagenbeck made their first contribution in https://github.com/restatedev/sdk-python/pull/157

​

New features :tada:

• Added ingress client to send requests from your python applications to restate services:

async with restate.create_client("http://localhost:8080") as client:
  await client.object_call(increment, key="a", arg=5)
  await client.object_send(increment, key="a", arg=5)

  current_count = await client.object_call(count, key="a", arg=None)

• Added new test harness constructor to be used in combination with @pytest.fixture:

# Your fixture
@pytest.fixture(scope="session")
async def restate_test_harness():
  app = restate.app([greeter])
  async with restate.create_test_harness(app) as harness:
        yield harness
        
# A test example, using the client
async def test_greeter(restate_test_harness: HarnessEnvironment):
    greeting = await restate_test_harness.client.service_call(greet, arg="Pippo")
    assert greeting == "Hello Pippo!"

• Various type hints improvements, such as https://github.com/restatedev/sdk-python/issues/112

​

What’s Changed

• Revert usage of asyncio cancellation mechanism by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/142
• Update crazy-max/ghaction-setup-docker to v4 by @muhamadazmy in https://github.com/restatedev/sdk-python/pull/144
• Use modern lints, tools and type checkers by @igalshilman in https://github.com/restatedev/sdk-python/pull/143
• Add typed client by @igalshilman in https://github.com/restatedev/sdk-python/pull/145
• Add test for harness and typed client. Fix name of TestHarnessEnvironment so it doesn’t get mixed up in pytest. Fix imports in init by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/147

​

New features

• You can configure more retry options for ctx.run_typed:

ctx.run_typed("payment", payment, RunOptions(
    # Initial retry interval
    initial_retry_interval=timedelta(milliseconds=100),
    # Retry policies are exponential, the retry interval will double on each attempt
    retry_interval_factor=2.0,
    # Maximum retry interval
    max_retry_interval=timedelta(seconds=10),
    # Max duration of retries before giving up
    max_duration=timedelta(minutes=5),
    # Max attempts (including the initial) before giving up
    max_attempts=10,
))

• You can now provide a name to sleep, you’ll be able to see this name in the UI.

​

Notable changes

• When suspending, the SDK will now throw an asyncio.CancelledError, instead of the previously thrown custom error. Catch this exception only if you need to cleanup some external resources between execution attempts.

​

What’s Changed

• Use task cancellation instead of custom suspension exception by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/132
• Remove typing_extensions dependency by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/133
• Copy RunOptions when mutating them by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/135
• Add name parameter to sleep by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/136
• Fix ctx.time() by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/138
• Expose all run retry options by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/137
• Test suite 3.2 upgrade by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/139
• Use service image by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/140
• Fix lint warning by @igalshilman in https://github.com/restatedev/sdk-python/pull/141

​

What’s Changed

• Add better closed error by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/131

​

Invocation retry policy

​

What’s Changed

• Retry Policy by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/126
• Clarify ctx.run max attempts by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/127
• Bring back Python 3.10 support by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/129

​

What’s Changed

• Add always_replay flag to test harness by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/124
• Add disable_retries flag to test harness by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/125

​

New features :sparkles:

• ctx.random() and ctx.uuid() for deterministic random and uuid. by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/120
• Add ctx.time() as wrapper around ctx.run(time.time) by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/121
• Integration with standard library logging module: replay aware logging filter restate.RestateLoggingFilter and log factory restate.getLogger() by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/122

​

What’s Changed

• enhancement: Add support for function args & kwargs type hints in ctx.run. by @objecthuman in https://github.com/restatedev/sdk-python/pull/109
• Bump PyO3 version, this required few changes by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/110
• Update pyproject.toml to include correct license metadata by @tillrohrmann in https://github.com/restatedev/sdk-python/pull/111

​

New Contributors

• @objecthuman made their first contribution in https://github.com/restatedev/sdk-python/pull/109

• Introduce new Service/Object/Workflow constructor fields and the decorator fields inactivity_timeout, abort_timeout, journal_retention, idempotency_retention, ingress_private, workflow_retention. Please note these work only from Restate 1.4 onward. Check the in-code documentation for more details.
• Improved error messages

​

What’s Changed

• Discovery manifest V3 by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/103
• Bump shared core by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/106
• Use shared core 0.4 by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/107

​

New Contributors

• @muhamadazmy made their first contribution in https://github.com/restatedev/sdk-python/pull/101

​

What’s Changed

• Minor type hint improvments by @igalshilman in https://github.com/restatedev/sdk-python/pull/95

​

What’s Changed

• Trigger building docker by @igalshilman in https://github.com/restatedev/sdk-python/pull/92
• Asgi recv() on lambda should hang when there are no more events by @igalshilman in https://github.com/restatedev/sdk-python/pull/93
• Add an explicit HTTP input closed event by @igalshilman in https://github.com/restatedev/sdk-python/pull/94

​

What’s Changed

• Fix DefaultSerde with_type_hint by @igalshilman in https://github.com/restatedev/sdk-python/pull/79
• Make the restate app mountable by @igalshilman in https://github.com/restatedev/sdk-python/pull/80
• [test] Use single element tuples by @igalshilman in https://github.com/restatedev/sdk-python/pull/81
• Rename created Docker image into test-services-python by @tillrohrmann in https://github.com/restatedev/sdk-python/pull/77
• [docs] Add types to the attributes section by @igalshilman in https://github.com/restatedev/sdk-python/pull/82
• Introduce attempt completion event by @igalshilman in https://github.com/restatedev/sdk-python/pull/83
• Auto cancel tasks when an attempt is over by @igalshilman in https://github.com/restatedev/sdk-python/pull/84
• Support concurrent side effects more robustly by @igalshilman in https://github.com/restatedev/sdk-python/pull/86
• Fix task error is ignored by @igalshilman in https://github.com/restatedev/sdk-python/pull/87
• Catch asyncio.CancelledError during attempt tear down by @igalshilman in https://github.com/restatedev/sdk-python/pull/88
• Wait for the side effect to complete by @igalshilman in https://github.com/restatedev/sdk-python/pull/89
• Use stable rust in rust-toolchain.toml by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/91
• Separate the ASGI types from the restate types by @igalshilman in https://github.com/restatedev/sdk-python/pull/90

​

What’s Changed

• Service Protocol V4 by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/33
• [tests] Add Docker GHA for test-services by @igalshilman in https://github.com/restatedev/sdk-python/pull/42
• [verification] Move the interpreter to test-services/ by @igalshilman in https://github.com/restatedev/sdk-python/pull/43
• Protocol V5 by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/44
• Offload synchronous actions in ctx.run via asyncio.to_thread to prevent event loop blocking by @ouatu-ro in https://github.com/restatedev/sdk-python/pull/47
• Export Public API via all in init.py by @ouatu-ro in https://github.com/restatedev/sdk-python/pull/49
• Add CLA automation by @tillrohrmann in https://github.com/restatedev/sdk-python/pull/50
• Expose new SDK features by @igalshilman in https://github.com/restatedev/sdk-python/pull/51
• Pass call headers in call/send by @igalshilman in https://github.com/restatedev/sdk-python/pull/52
• Use a custom future by @igalshilman in https://github.com/restatedev/sdk-python/pull/53
• Feature/general serde by @ouatu-ro in https://github.com/restatedev/sdk-python/pull/48
• Add invocation_id to a call promise by @igalshilman in https://github.com/restatedev/sdk-python/pull/54
• Lazy create the run() coroutine by @igalshilman in https://github.com/restatedev/sdk-python/pull/55
• Add additional features by @igalshilman in https://github.com/restatedev/sdk-python/pull/56
• Support ctx.run combinators by @igalshilman in https://github.com/restatedev/sdk-python/pull/58
• Rename combinators to asyncio by @igalshilman in https://github.com/restatedev/sdk-python/pull/59
• Add sleep future by @igalshilman in https://github.com/restatedev/sdk-python/pull/60
• Use RestateDurableFuture in workflow methods by @igalshilman in https://github.com/restatedev/sdk-python/pull/61
• Add select future combinator by @igalshilman in https://github.com/restatedev/sdk-python/pull/62
• Chore/fix type hints and general clarity by @ouatu-ro in https://github.com/restatedev/sdk-python/pull/57
• Try to auto deduce the types provided for ctx.run() by @igalshilman in https://github.com/restatedev/sdk-python/pull/63
• Use DefaultSerde in more places by @igalshilman in https://github.com/restatedev/sdk-python/pull/64
• Add optional args= param to ctx.run by @igalshilman in https://github.com/restatedev/sdk-python/pull/65
• Notify the VM about a transient error by @igalshilman in https://github.com/restatedev/sdk-python/pull/66
• Update test suite to 3.0 by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/68
• Rename cancel_invocation by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/69
• Add health check by @igalshilman in https://github.com/restatedev/sdk-python/pull/70
• Fix discovery information for void args by @igalshilman in https://github.com/restatedev/sdk-python/pull/71
• Fix type inference in PyCharm for ctx.run(). by @igalshilman in https://github.com/restatedev/sdk-python/pull/72
• Add a shortcut f.cancel_invocation() by @igalshilman in https://github.com/restatedev/sdk-python/pull/73
• Support dataclasses serde by @igalshilman in https://github.com/restatedev/sdk-python/pull/74
• Cleanup the concurrent example by @igalshilman in https://github.com/restatedev/sdk-python/pull/75
• Bump shared core by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/76

​

New Contributors

• @ouatu-ro made their first contribution in https://github.com/restatedev/sdk-python/pull/47
• @tillrohrmann made their first contribution in https://github.com/restatedev/sdk-python/pull/50

​

What’s Changed

• Infer basic json schema by @igalshilman in https://github.com/restatedev/sdk-python/pull/28
• Use test suite 2.4 by @jackkleeman in https://github.com/restatedev/sdk-python/pull/31
• Add test harness by @igalshilman in https://github.com/restatedev/sdk-python/pull/36
• Make test_harness a conditional import by @igalshilman in https://github.com/restatedev/sdk-python/pull/37
• Bumped shared core and bumped pyo3 by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/38
• Fix delay by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/41

​

New Contributors

• @jackkleeman made their first contribution in https://github.com/restatedev/sdk-python/pull/31

​

What’s Changed

• Convert stringized annotations to real types by @igalshilman in https://github.com/restatedev/sdk-python/pull/27

​

What’s Changed

• Add support for pydantic by @igalshilman in https://github.com/restatedev/sdk-python/pull/26

​

Breaking changes

​

New features

• It is now possible to configure the max number of retry attempts/max duration of retries for ctx.run

​

What’s Changed

• Add x-restate-server to the response headers by @igalshilman in https://github.com/restatedev/sdk-python/pull/20
• Add side effect retry by @igalshilman in https://github.com/restatedev/sdk-python/pull/21
• Run retry e2e tests by @slinkydeveloper in https://github.com/restatedev/sdk-python/pull/22

​

New features

• AWS Lambda support. Develop your service as usual and when deploying on AWS Lambda set the handler name to the variable containing restate.app.
• Implement request verification, to secure your service when interacting with Restate cloud: https://docs.restate.dev/deploy/cloud#http
• Implement ctx.state_keys() and ctx.clear_all()

​

What’s Changed

• We now test the SDK with the new SDK test tool