Design, build, run, and test Restate durable services, virtual objects, workflows, and AI agents across TypeScript, Python, Java, and Go. This skill should be used when the user mentions "restate", "durable execution", "virtual object", "restate service", "restate workflow", or "durable agent" or wants to build resilient backend services, AI agents, or workflows with automatic failure recovery. Also use when converting existing applications or migrating from workflow orchestrators to Restate. Use proactively when a project contains restate dependencies in package.json, requirements.txt, pyproject.toml, pom.xml, build.gradle, or go.mod.
Restate is a durable execution runtime. It records every step of a handler in a journal, so if the process crashes, the handler replays from the journal and resumes exactly where it left off. Services are regular applications using the Restate SDK (TypeScript, Python, Java, Go) that run behind a Restate Server (a single Rust binary on ports 8080 for ingress and 9070 for admin UI).
Detect context
Scan the project to determine the SDK and context:
Detect SDK:
package.json with @restatedev/restate-sdk -> TypeScript
requirements.txt or pyproject.toml with restate-sdk -> Python
pom.xml or build.gradle with dev.restate -> Java
go.mod with github.com/restatedev/sdk-go -> Go
If no SDK detected, check for project files to determine language, then ask the user
Detect existing Restate code: Grep for @restatedev, restate-sdk, dev.restate.sdk, github.com/restatedev
Detect AI frameworks: @ai-sdk/, openai-agents, google-adk, pydantic-ai, langchain, langgraph
Detect workflow orchestrators: temporalio, @temporalio, aws-cdk/aws-stepfunctions, etc.
Core reference (always load)
After detecting the SDK, always load the SDK reference:
references/<sdk>/api-and-pitfalls.md - Setup, API patterns, determinism rules, error handling, and pitfalls for the detected SDK
references/ai-agents.md, then the relevant framework reference
Always verify before finishing
All checks below are mandatory.
All side effects, external I/O, and DB calls wrapped in ctx.run()
No native random, time, sleep, or UUID -- use ctx helpers
Restate concurrency combinators only (no Promise.all, asyncio.gather/wait, CompletableFuture, goroutines + channels, select)
No ctx operations inside ctx.run()
TerminalError raised for non-retryable failures
Python: no bare except:
AI agents: load references/ai-agents.md, journal every LLM call and tool side effect, and set bounded retry policies
Virtual Objects: no deadlock cycles
Service registered and invoked via curl or the UI
Replay test - required on any handler logic change
Any change to handler business logic (new ctx operations, reordered steps, new ctx.run() blocks, new branches) must be covered by a Testcontainers test with always-replay enabled, and that test must pass before declaring the work done. Always-replay forces every journaled step to replay on every invocation, so non-determinism fails the test instead of failing in production on retry.
TypeScript: alwaysReplay: true in RestateTestEnvironment.start
Python: always_replay=True in restate.create_test_harness
Java / Go: RESTATE_WORKER__INVOKER__INACTIVITY_TIMEOUT=0m on the Restate container
See the Testing section of references/<sdk>/api-and-pitfalls.md for the working scaffold.
1---2name: building-restate-services-23description: Design, build, run, and test Restate durable services, virtual objects, workflows, and AI agents across TypeScript, Python, Java, and Go. This skill should be used when the user mentions "restate", "durable execution", "virtual object", "restate service", "restate workflow", or "durable agent" or wants to build resilient backend services, AI agents, or workflows with automatic failure recovery. Also use when converting existing applications or migrating from workflow orchestrators to Restate. Use proactively when a project contains restate dependencies in package.json, requirements.txt, pyproject.toml, pom.xml, build.gradle, or go.mod.4---56# Restate78Restate is a durable execution runtime. It records every step of a handler in a journal, so if the process crashes, the handler replays from the journal and resumes exactly where it left off. Services are regular applications using the Restate SDK (TypeScript, Python, Java, Go) that run behind a Restate Server (a single Rust binary on ports 8080 for ingress and 9070 for admin UI).910## Detect context1112Scan the project to determine the SDK and context:13141. **Detect SDK**:15 - `package.json` with `@restatedev/restate-sdk` -> TypeScript16 - `requirements.txt` or `pyproject.toml` with `restate-sdk` -> Python17 - `pom.xml` or `build.gradle` with `dev.restate` -> Java18 - `go.mod` with `github.com/restatedev/sdk-go` -> Go19 - If no SDK detected, check for project files to determine language, then ask the user20212. **Detect existing Restate code**: Grep for `@restatedev`, `restate-sdk`, `dev.restate.sdk`, `github.com/restatedev`22233. **Detect AI frameworks**: `@ai-sdk/`, `openai-agents`, `google-adk`, `pydantic-ai`, `langchain`, `langgraph`24254. **Detect workflow orchestrators**: `temporalio`, `@temporalio`, `aws-cdk/aws-stepfunctions`, etc.2627## Core reference (always load)2829After detecting the SDK, always load the SDK reference:3031- `references/<sdk>/api-and-pitfalls.md` - Setup, API patterns, determinism rules, error handling, and pitfalls for the detected SDK3233## Context-based references (load when relevant)3435| Context | Reference |36|---------|-----------|37| Design a new application, choose service types | `references/design-and-architecture.md` |38| Add concurrency limits, multi-tenant fairness, cost controls, scopes, or limit keys | `references/flow-control-and-scopes.md` |39| Convert from a workflow orchestrator or existing app | `references/translate-to-restate.md` |40| Invoking services, interacting with invocations (cancel, attach, idempotency, sends, Kafka) | `references/invocation-lifecycle.md` |41| Design an AI agent, choose a durability boundary, or use an unsupported LLM / agent SDK | `references/ai-agents.md` |42| Build AI agent with Vercel AI SDK | `references/ts/restate-vercel-ai-agents.md` |43| Build AI agent with OpenAI Agents SDK | `references/python/restate-openai-agents-agents.md` |44| Build AI agent with Google ADK | `references/python/restate-google-adk-agents.md` |45| Build AI agent with Pydantic AI | `references/python/restate-pydantic-ai-agents.md` |46| Build AI agent with LangChain or LangGraph | `references/python/restate-langchain-agents.md` |47| Debug errors, stuck invocations, journal mismatches | `references/debug-applications.md` |48| Testing, deployment, server config, Kafka, advanced topics | Use the bundled **restate-docs** MCP server |49| Code examples and templates | `github.com/restatedev/examples`, `github.com/restatedev/ai-examples` |5051## Before-you-design checklist5253Before designing any Restate service architecture, check:5455| Question | Consult |56|-------------------------------------------------------------------|---------|57| Restate service types, stateful entities, keying, concurrency? | `references/design-and-architecture.md` |58| Concurrency limits, tenant isolation, or downstream protection? | `references/flow-control-and-scopes.md` |59| Non-Restate orchestrator in the project? | `references/translate-to-restate.md` |60| Invoking, cancelling, deduplicating, or attaching to invocations? | `references/invocation-lifecycle.md` |61| Error handling, compensation, sagas? | [Error handling guide](https://docs.restate.dev/guides/error-handling), [Sagas guide](https://docs.restate.dev/guides/sagas) |62| AI agent or LLM calls? | `references/ai-agents.md`, then the relevant framework reference |6364## Always verify before finishing6566**All checks below are mandatory**.6768- [ ] All side effects, external I/O, and DB calls wrapped in `ctx.run()`69- [ ] No native random, time, sleep, or UUID -- use ctx helpers70- [ ] Restate concurrency combinators only (no `Promise.all`, `asyncio.gather`/`wait`, `CompletableFuture`, goroutines + channels, `select`)71- [ ] No ctx operations inside `ctx.run()`72- [ ] `TerminalError` raised for non-retryable failures73- [ ] Python: no bare `except:`74- [ ] AI agents: load `references/ai-agents.md`, journal every LLM call and tool side effect, and set bounded retry policies75- [ ] Virtual Objects: no deadlock cycles76- [ ] Service registered and invoked via curl or the UI7778### Replay test - required on any handler logic change7980Any change to handler business logic (new `ctx` operations, reordered steps, new `ctx.run()` blocks, new branches) must be covered by a Testcontainers test with **always-replay** enabled, and that test must pass before declaring the work done. Always-replay forces every journaled step to replay on every invocation, so non-determinism fails the test instead of failing in production on retry.8182- TypeScript: `alwaysReplay: true` in `RestateTestEnvironment.start`83- Python: `always_replay=True` in `restate.create_test_harness`84- Java / Go: `RESTATE_WORKER__INVOKER__INACTIVITY_TIMEOUT=0m` on the Restate container8586See the Testing section of `references/<sdk>/api-and-pitfalls.md` for the working scaffold.
Run npx skillmds@latest add restatedev/building-restate-services-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Design, build, run, and test Restate durable services, virtual objects, workflows, and AI agents across TypeScript, Python, Java, and Go. This skill should be used when the user mentions "restate", "durable execution", "virtual object", "restate service", "restate workflow", or "durable agent" or wants to build resilient backend services, AI agents, or workflows with automatic failure recovery. Also use when converting existing applications or migrating from workflow orchestrators to Restate. Use proactively when a project contains restate dependencies in package.json, requirements.txt, pyproject.toml, pom.xml, build.gradle, or go.mod. It is listed under AI & ML on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
restatedev (@restatedev) published this skill. Their other Agent Skills are listed on their SkillMD profile.
restatedev