Services

Implementing Restate services with the Python SDK.

The Restate Python SDK is open source and available on GitHub.

The Restate SDK lets you implement handlers. Handlers can be part of a Basic Service, a Virtual Object, or a Workflow. This page shows how to define them with the Python SDK.

Prerequisites

• Python >= v3.11

Getting started

Get started quickly with the Python Quickstart.

Add the restate_sdk[serde] dependency to your Python project to start developing Restate services.

Basic Services

Basic Services group related handlers and expose them as callable endpoints:

import restate

my_service = restate.Service("MyService")


@my_service.handler("myHandler")
async def my_handler(ctx: restate.Context, greeting: str) -> str:
    return f"{greeting}!"


app = restate.app([my_service])

• Initialize the Service and specify the service name (here MyService).
• Annotate each handler with @my_service.handler(). Optionally, you can override the handler name (here myHandler).
• Each handler can then be called at <RESTATE_INGRESS>/myService/myHandler
• Handlers take the restate.Context as the first argument.
• Handlers can take one optional JSON-serializable input and must return an optional output. These can be of any primitive type, TypedDict or Pydantic model (or see custom serialization for advanced types).
• Finally, initialize the app, bind the service(s) to it, and serve it. Look at the serving docs to learn more about serving your app.

Virtual Objects

Virtual Objects are services that are stateful and key-addressable — each object instance has a unique ID and persistent state.

import restate

my_object = restate.VirtualObject("MyVirtualObject")


@my_object.handler("myHandler")
async def my_handler(ctx: restate.ObjectContext, greeting: str) -> str:
    return f"{greeting} {ctx.key()}!"


@my_object.handler(kind="shared")
async def my_concurrent_handler(ctx: restate.ObjectSharedContext, greeting: str) -> str:
    return f"{greeting} {ctx.key()}!"


app = restate.app([my_object])

• Initialize a restate.VirtualObject and specify the object’s name (here MyVirtualObject).
• Each instance is identified by a key (accessible via ctx.key()).
• Virtual Objects can have exclusive and shared handlers.
• Exclusive handlers receive an ObjectContext, allowing read/write access to object state.
• Shared handlers have the annotation kind="shared" and receive an ObjectSharedContext.

Workflows

Workflows are long-lived processes with a defined lifecycle. They run once per key and are ideal for orchestrating multi-step operations, which require external interaction via signals and queries.

import restate

my_workflow = restate.Workflow("MyWorkflow")


@my_workflow.main()
async def run(ctx: restate.WorkflowContext, req: str) -> str:
    # ... implement workflow logic here ---
    return "success"


@my_workflow.handler()
async def interact_with_workflow(ctx: restate.WorkflowSharedContext, req: str):
    # ... implement interaction logic here ...
    return


app = restate.app([my_workflow])

• Initialize a restate.Workflow and specify its name (here MyWorkflow).
• Every workflow must include a run handler:
  • This is the main orchestration entry point and is annotated with @my_workflow.main().
  • It runs exactly once per workflow execution and uses the WorkflowContext
  • Resubmission of the same workflow will fail with “Previously accepted”. The invocation ID can be found in the request header x-restate-id.
  • Use ctx.key() to access the workflow’s unique ID
• Additional handlers are annotated with @my_workflow.handler(). They must use the WorkflowSharedContext and can signal or query the workflow. They can run concurrently with the run handler and until the retention time expires.

Configuring services

Check out the service configuration docs to learn how to configure service behavior, including timeouts and retention policies.