Terminal
Terminal/Skill
Guides an agent through designing, building, running and testing Restate durable services, workflows and AI agents in TypeScript, Python, Java or Go.
By Restate
Works with
npx skills add restatedev/skills --skill building-restate-servicesRestate 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).
Scan the project to determine the SDK and context:
Detect SDK:
package.json with @restatedev/restate-sdk -> TypeScriptrequirements.txt or pyproject.toml with restate-sdk -> Pythonpom.xml or build.gradle with dev.restate -> Javago.mod with github.com/restatedev/sdk-go -> GoDetect 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.
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| Context | Reference |
|---|---|
| Design a new application, choose service types | references/design-and-architecture.md |
| Add concurrency limits, multi-tenant fairness, cost controls, scopes, or limit keys | references/flow-control-and-scopes.md |
| Convert from a workflow orchestrator or existing app | references/translate-to-restate.md |
| Invoking services, interacting with invocations (cancel, attach, idempotency, sends, Kafka) | references/invocation-lifecycle.md |
| Design an AI agent, choose a durability boundary, or use an unsupported LLM / agent SDK | references/ai-agents.md |
| Build AI agent with Vercel AI SDK | references/ts/restate-vercel-ai-agents.md |
| Build AI agent with OpenAI Agents SDK | references/python/restate-openai-agents-agents.md |
| Build AI agent with Google ADK | references/python/restate-google-adk-agents.md |
| Build AI agent with Pydantic AI | references/python/restate-pydantic-ai-agents.md |
| Build AI agent with LangChain or LangGraph | references/python/restate-langchain-agents.md |
| Debug errors, stuck invocations, journal mismatches | references/debug-applications.md |
| Testing, deployment, server config, Kafka, advanced topics | Use the bundled restate-docs MCP server |
| Code examples and templates | github.com/restatedev/examples, github.com/restatedev/ai-examples |
| Complete TypeScript agent reference architecture | restatedev/agent |
Before designing any Restate service architecture, check:
| Question | Consult |
|---|---|
| Restate service types, stateful entities, keying, concurrency? | references/design-and-architecture.md |
| Concurrency limits, tenant isolation, or downstream protection? | references/flow-control-and-scopes.md |
| Non-Restate orchestrator in the project? | references/translate-to-restate.md |
| Invoking, cancelling, deduplicating, or attaching to invocations? | references/invocation-lifecycle.md |
| Error handling, compensation, sagas? | Error handling guide, Sagas guide |
| AI agent or LLM calls? | references/ai-agents.md, then the relevant framework reference |
All checks below are mandatory.
ctx.run()Promise.all, asyncio.gather/wait, CompletableFuture, goroutines + channels, select)ctx.run()TerminalError raised for non-retryable failuresexcept:references/ai-agents.md, journal every LLM call and tool side effect, and set bounded retry policiesAny 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.
alwaysReplay: true in RestateTestEnvironment.startalways_replay=True in restate.create_test_harnessRESTATE_WORKER__INVOKER__INACTIVITY_TIMEOUT=0m on the Restate containerSee the Testing section of references/<sdk>/api-and-pitfalls.md for the working scaffold.