restatedev

Capabilities

Restate enables agents to build resilient, stateful applications that automatically recover from failures without losing progress. Core capabilities include:

• Durable Execution: Persist operation results in a journal and replay from failures, ensuring handlers run to completion
• Stateful Services: Manage persistent key-value state across requests with automatic consistency guarantees
• Workflow Orchestration: Coordinate multi-step processes with guaranteed once-per-ID execution
• AI Agent Integration: Add fault tolerance to LLM agents and tool executions with automatic retries and state management
• Event Processing: Connect to Kafka topics for transactional event handling with zero consumer management
• Service Communication: Call other Restate services or external APIs with automatic deduplication and error handling
• Human-in-the-Loop: Pause execution and wait for external signals (approvals, webhooks) without losing state
• Concurrent Operations: Execute multiple tasks in parallel with deterministic recovery from failures

Skills

Service Types

Basic Services: Stateless handlers that group related functionality

• Define handlers with Context parameter
• Invoke via HTTP: POST /ServiceName/handlerName
• Example: curl -X POST localhost:8080/Greeter/greet --json '{"name":"Alice"}'

Virtual Objects: Stateful, key-addressable entities with persistent state

• Each instance identified by unique key
• Exclusive handlers with write access (one at a time per key)
• Shared handlers for concurrent read-only access
• Invoke: POST /ObjectName/key/handlerName
• Example: curl -X POST localhost:8080/UserAccount/user123/updateBalance --json '{"amount":50}'

Workflows: Long-lived processes with guaranteed once-per-ID execution

• Main run handler executes exactly once per workflow ID
• Additional handlers can signal, query, or wait for events
• Ideal for multi-step operations requiring external interaction
• Invoke: POST /WorkflowName/workflowId/run

Durable Execution Primitives

Durable Steps: Persist operation results in execution journal

• Wrap non-deterministic operations (database calls, HTTP requests, UUID generation)
• Automatically replayed on failures without re-execution
• Use ctx.run() to execute and persist results

Concurrent Tasks: Execute multiple operations in parallel

• Use ctx.all() or ctx.select() for concurrent execution
• Deterministic replay during recovery
• Gather results from multiple concurrent operations

Durable Timers: Wait for specific durations with automatic recovery

• Use ctx.sleep(duration) for timeouts
• Timers survive crashes and don’t restart from beginning
• Combine with awakeables for timeout patterns

Awakeables: Durable promises for external events

• Create awakeable with unique ID: awakeable = ctx.awakeable()
• Send ID to external system (webhooks, human approvers, etc.)
• Handler suspends until external completion via API call
• Resolve: POST /restate/awakeables/{awakeableId}/resolve
• Reject: POST /restate/awakeables/{awakeableId}/reject

State Management

Virtual Object State: Persistent key-value storage

• ctx.get(key) – retrieve state
• ctx.set(key, value) – persist state
• ctx.clear(key) – delete state
• ctx.stateKeys() – list all keys
• State retained indefinitely and shared across requests

Workflow State: Temporary state during workflow execution

• Same API as Virtual Objects
• Cleared after workflow completion based on retention policy

Service Communication

Service-to-Service Calls: Invoke other Restate handlers

• ctx.serviceCall(service, handler, input) – call and wait
• ctx.serviceSendClient(service).handler(input) – fire-and-forget
• Automatic deduplication within same handler execution
• Optional idempotency key for cross-handler deduplication

External API Calls: Call non-Restate services

• Wrap in ctx.run() for durability
• Automatic retries on transient failures
• Results persisted in journal

Invocation Methods

HTTP Invocation: Direct HTTP requests to Restate ingress (port 8080)

• Synchronous: POST /Service/handler – wait for response
• Asynchronous: POST /Service/handler/send – fire-and-forget
• With idempotency: Add Idempotency-Key header for deduplication

Kafka Integration: Connect handlers to Kafka topics

• Create subscription: POST /subscriptions with source and sink
• Restate manages consumer groups automatically
• Each event triggers handler invocation
• For Virtual Objects, Kafka message key becomes object key
• Access metadata: ctx.request().headers() contains subscription ID, offset, partition, timestamp

Typed SDK Clients: Invoke from external applications

• TypeScript: @restatedev/restate-sdk-clients
• Java: dev.restate:sdk-client
• Go: github.com/restatedev/sdk-go/client
• Example: restateClient.serviceClient(service).handler(input)

Error Handling & Resilience

Automatic Retries: Failed invocations retry with exponential backoff

• Default: infinite retries for all errors
• Transient errors: network failures, timeouts
• Terminal errors: application logic failures (throw TerminalError)
• Configure retry behavior per operation

Sagas & Rollback: Implement compensating transactions

• Build list of compensation functions for each step
• On terminal failure, execute compensations in reverse order
• Compensations survive crashes and always complete
• Example: undo payment, remove subscriptions on failure

Idempotency: Prevent duplicate executions

• Add Idempotency-Key header to requests
• Restate deduplicates and returns cached result
• Useful for retries and preventing race conditions

AI Agent Patterns

Prompt Chaining: Multi-step LLM pipelines

• Each step transforms previous output
• Automatic recovery from failures at any step
• Durable execution ensures no lost progress

Tool Execution: Resilient tool calling

• Wrap tool calls in durable execution
• Automatic retries on API failures
• Full execution trace for debugging

Multi-Agent Systems: Coordinate multiple specialized agents

• Call agents as tools from other agents
• Share context between agents in same process
• Handoffs and task delegation with automatic recovery

Sessions & Chat: Stateful multi-turn conversations

• Use Virtual Objects to store conversation history
• Persistent context across messages
• Concurrency control for sequential processing

Human-in-the-Loop: Pause for approvals and feedback

• Create awakeable for approval request
• Send ID to human approver
• Handler suspends without consuming resources
• Resume when approval received via API

Parallelization: Execute multiple tools concurrently

• Run multiple LLM calls or tool executions in parallel
• Deterministic recovery from failures
• Gather results from all parallel operations

Competitive Racing: Start multiple workflows, return first result

• Execute multiple agents/workflows concurrently
• Return result from first completion
• Cancel remaining operations

Admin & Introspection

Admin API (port 9070):

• Register deployments: POST /deployments
• Manage invocations: pause, resume, kill
• Query subscriptions: GET /subscriptions
• Introspection: query invocation status and service state

SQL Introspection: Query system state

• Check invocation status and progress
• Inspect Virtual Object state
• Troubleshoot blocked invocations

Restate UI: Visual debugging and monitoring

• View invocation traces and execution timeline
• Inspect service state
• Monitor handler execution
• Access at port 9070

Workflows

Building a Durable AI Agent

1. Define agent as Restate service with LLM SDK integration
2. Wrap LLM calls in ctx.run() for durability
3. Wrap tool executions in ctx.run() for automatic retries
4. Use awakeables for human approvals if needed
5. Deploy service to Restate
6. Invoke via HTTP or SDK client
7. Monitor execution in Restate UI

Processing Kafka Events

1. Start Restate Server with Kafka configuration
2. Define handler to process events
3. Register service with Restate
4. Create subscription: curl -X POST localhost:9070/subscriptions --json '{"source":"kafka://cluster/topic","sink":"service://Service/handler"}'
5. Publish events to Kafka topic
6. Restate automatically invokes handler for each event
7. Failed events automatically retry with exponential backoff

Implementing Saga Pattern

1. Define service with handler containing business logic steps
2. Create list of compensation functions for each step
3. Wrap each step in ctx.run()
4. On terminal error, execute compensations in reverse order
5. Compensations automatically recover from crashes
6. Full trace available for debugging

Building Stateful Virtual Object

1. Define Virtual Object with exclusive and shared handlers
2. Exclusive handlers: read/write state access, one at a time per key
3. Shared handlers: concurrent read-only access
4. Use ctx.get(), ctx.set(), ctx.clear() for state management
5. Invoke with key: POST /ObjectName/key/handler
6. State persists indefinitely across requests
7. Automatic consistency: at most one exclusive handler per key at a time

Integration

LLM & Agent SDKs: Restate integrates with:

• Vercel AI SDK
• OpenAI Agents SDK
• Google ADK
• LiteLLM
• Custom SDK integration via flexible programming model

Event Sources:

• Kafka topics with automatic consumer management
• HTTP webhooks via awakeables
• External APIs via service calls

Deployment Platforms:

• Kubernetes (with Restate Operator or Helm)
• AWS Lambda
• Vercel
• Cloudflare Workers
• Deno Deploy
• Docker
• Self-hosted

Observability:

• Execution traces with full timeline
• Invocation status queries
• Service state inspection
• Logging and metrics
• Distributed tracing support

Context

Durable Execution Model: Restate records all handler actions in a journal. On failure or crash, the server replays the journal to restore state and continues from where it left off. This ensures handlers always run to completion without losing progress.

Determinism Requirement: For reliable replay, operations must be deterministic. Non-deterministic operations (API calls, database writes, UUID generation) must be wrapped in ctx.run() so results are journaled and replayed identically.

State Consistency: Virtual Objects guarantee at most one exclusive handler per key executes at a time, creating a queue per key. This ensures state consistency without distributed locks.

Once-Per-ID Semantics: Workflows execute exactly once per workflow ID. Resubmitting the same workflow ID fails with “Previously accepted” error. Idempotency keys prevent duplicate execution across different invocation sources.

Failure Recovery: Restate automatically retries transient failures (network, timeouts) with exponential backoff. Terminal errors (application logic failures) stop retries. Sagas implement compensating transactions for rollback on terminal failures.

Serverless-Friendly: Handlers can suspend while waiting for external events (awakeables) without consuming resources. On function-as-a-service platforms, the function can exit and resume later when the event arrives, reducing costs.

Journal-Based Durability: Unlike traditional workflow systems requiring separate orchestrator infrastructure, Restate persists execution state in its own journal. Deploy handlers as regular application code; Restate handles durability and recovery automatically.

For additional documentation and navigation, see: https://docs.restate.dev/llms.txt