Restate Python SDK

0.17.1 · active · verified Thu Apr 16

The `restate-sdk` is a Python SDK for Restate, a platform designed for building resilient applications using distributed durable async/await. It enables developers to implement durable backend services, virtual objects, and AI agents that can withstand failures and manage state reliably. The library is actively maintained with frequent minor version releases, integrating new features and improvements often.

Common errors

```
Protocol violation error (RT0012) OR The service endpoint does not support any of the supported service protocol versions of the server (RT0013)
```
cause The Restate Python SDK version is incompatible with the Restate server version it's trying to communicate with.

fix Check the Restate documentation for SDK-server compatibility. Upgrade your `restate-sdk` package or the Restate server to compatible versions.
```
My Restate service keeps retrying indefinitely for an application-specific error, instead of failing permanently.
```
cause Restate, by default, retries all errors unless explicitly marked as terminal. Your application-specific error is being treated as a transient failure.

fix For errors that should not be retried (e.g., invalid input, business logic violations), raise `restate.exceptions.TerminalError('My error message')` in your handler.
```
Non-deterministic behavior or unexpected state during replays when interacting with external systems (e.g., HTTP calls, random numbers).
```
cause External, non-deterministic operations or side effects are not being wrapped correctly within `ctx.run` blocks, which ensure their results are journaled and replayed consistently.

fix Wrap all external calls, non-deterministic computations, or any operation that should only execute once and whose result needs to be durable, inside `await ctx.run("unique-name", lambda: my_nondeterministic_op())`.

Warnings

breaking SDK versions prior to 0.6 are deprecated and will be rejected by Restate server versions 1.5 and above. This can lead to registration failures for services deployed with older SDKs.
Fix: Upgrade your `restate-sdk` to version 0.6 or higher. After upgrading, re-register your deployment with the Restate server.
breaking The default retry strategy for LLM calls within Restate AI integrations (e.g., `pydantic-ai`) changed in v0.16.0. It now defaults to 10 attempts with a 1-second minimum interval, potentially altering the behavior of existing AI agent workflows.
Fix: Review and explicitly configure the retry policy for your LLM calls if the new defaults are not suitable for your application. This can often be done via service or handler-level configurations.
gotcha Using broad exception handling like `except Exception:` or bare `except:` in Restate handlers is highly discouraged. This can inadvertently catch internal SDK exceptions, leading to non-deterministic behavior and breaking Restate's durable execution guarantees.
Fix: Always catch specific exceptions. For permanent, non-retryable errors, explicitly raise `restate.exceptions.TerminalError`. For transient errors, let them propagate to trigger Restate's built-in retry mechanism.
gotcha Incompatible versions between the Restate SDK and the Restate server can lead to runtime errors like 'Protocol violation error' (RT0012) or 'The service endpoint does not support any of the supported service protocol versions of the server' (RT0013).
Fix: Ensure your Restate SDK version is compatible with your Restate server version. Refer to the official Restate documentation for compatibility matrices. Upgrade either the SDK or the server as necessary.
gotcha New service/object/workflow constructor fields and handler decorator fields (e.g., `inactivity_timeout`, `abort_timeout`, `invocation_retry_policy`) only function correctly with Restate server versions 1.4 or 1.5 and newer.
Fix: If you are using these advanced configuration options, ensure your Restate server is at least version 1.4 or 1.5, depending on the specific feature. Consult the in-code documentation or Restate release notes for exact version requirements.

Install

pip install restate-sdk Base installation
pip install restate-sdk[serde] With msgspec for enhanced serialization
pip install restate-sdk[openai-agents] With OpenAI Agents SDK integration
pip install restate-sdk[harness] With testing harness (Testcontainers, pytest)

Imports

restate
```
import restate
```
The primary import for accessing SDK components like Service, Context, and app.
Service
wrong:
```
import Service
```
correct:
```
from restate import Service
```
Service is typically accessed via the top-level 'restate' import.
Context
wrong:
```
import Context
```
correct:
```
from restate import Context
```
Context is typically accessed via the top-level 'restate' import and passed to handlers.
app
wrong:
```
import app
```
correct:
```
from restate import app
```
The 'app' factory function is typically accessed via the top-level 'restate' import for serving services.
TerminalError
wrong:
```
from restate import TerminalError
```
correct:
```
from restate.exceptions import TerminalError
```
TerminalError is in the `restate.exceptions` submodule, not directly under `restate`.

Quickstart

This quickstart defines a basic Restate service named 'MyService' with a single asynchronous handler 'greet'. Handlers receive a `restate.Context` object for durable operations and can process input to produce an output. To execute this service, it needs to be run within a Restate runtime environment, typically by using the `restate serve` CLI command after defining the service.

import restate

my_service = restate.Service("MyService")

@my_service.handler("greet")
async def greet(ctx: restate.Context, name: str) -> str:
    # Use ctx.run to wrap any non-deterministic operations or external calls
    # For this simple example, we'll just return a greeting.
    return f"Hello {name}!"

# To run the service, typically you'd run this file with 'restate serve'
# or deploy it to a Restate runtime. For local testing, you can use:
# (This part is not runnable without a Restate runtime running)
# app = restate.app([my_service])
# app.run() # This would start an HTTP server

# Example of how to call this service (requires a running Restate server)
async def call_service_example():
    # This client creation is for an ingress client (v0.12.0+)
    async with restate.create_client("http://localhost:8080") as client:
        # Assuming 'MyService' is registered and 'greet' handler is available
        result = await client.object_call(my_service, key="unique-key", handler_name="greet", arg="World")
        print(f"Service call result: {result}")

if __name__ == "__main__":
    # For a full local setup and run, refer to Restate's Python Quickstart documentation.
    # The provided code snippet defines a service, but doesn't run it as a standalone app
    # without a Restate server or the 'restate serve' command.
    import asyncio
    # asyncio.run(call_service_example()) # Uncomment to try calling (requires Restate server)
    print("Service 'MyService' with handler 'greet' defined. To run, use 'restate serve'.")

view raw JSON →