building-restate-services

Restate

Restate は永続実行ランタイムです。ハンドラーの各ステップをジャーナルに記録するため、プロセスがクラッシュしても、ハンドラーはジャーナルから再実行され、中断した箇所から正確に処理を再開します。サービスは Restate SDK（TypeScript、Python、Java、Go）を使用する通常のアプリケーションで、Restate Server（ポート 8080 でイングレス、9070 で管理 UI を提供する単一の Rust バイナリ）の背後で実行されます。

コンテキストを検出する

プロジェクトをスキャンして、SDK とコンテキストを判断します。

1. SDK を検出する：

   • @restatedev/restate-sdk を含む package.json → TypeScript
   • restate-sdk を含む requirements.txt または pyproject.toml → Python
   • dev.restate を含む pom.xml または build.gradle → Java
   • github.com/restatedev/sdk-go を含む go.mod → Go
   • SDK が検出されない場合は、プロジェクトファイルを確認して言語を判断し、ユーザーに尋ねます

2. 既存の Restate コードを検出する：@restatedev、restate-sdk、dev.restate.sdk、github.com/restatedev を grep します

3. AI フレームワークを検出する：@ai-sdk/、openai-agents、google-adk、pydantic-ai、langchain、langgraph

4. ワークフローオーケストレーターを検出する：temporalio、@temporalio、aws-cdk/aws-stepfunctions など

コアリファレンス（常に読み込む）

SDK の検出後、SDK のリファレンスを必ず読み込みます。

• references/<sdk>/api-and-pitfalls.md - 検出された SDK のセットアップ、API パターン、決定性ルール、エラー処理、注意点

コンテキストに基づくリファレンス（関連する場合に読み込む）

コンテキスト	リファレンス
新しいアプリケーションを設計する、サービスの種類を選ぶ	references/design-and-architecture.md
並行処理の制限、マルチテナントの公平性、コスト管理、スコープ、または制限キーを追加する	references/flow-control-and-scopes.md
ワークフローオーケストレーターまたは既存アプリから移行する	references/translate-to-restate.md
サービスを呼び出す、呼び出しを操作する（キャンセル、アタッチ、冪等性、送信、Kafka）	references/invocation-lifecycle.md
AI エージェントを設計する、永続性の境界を選ぶ、または未対応の LLM／エージェント SDK を使用する	references/ai-agents.md
Vercel AI SDK で AI エージェントを構築する	references/ts/restate-vercel-ai-agents.md
OpenAI Agents SDK で AI エージェントを構築する	references/python/restate-openai-agents-agents.md
Google ADK で AI エージェントを構築する	references/python/restate-google-adk-agents.md
Pydantic AI で AI エージェントを構築する	references/python/restate-pydantic-ai-agents.md
LangChain または LangGraph で AI エージェントを構築する	references/python/restate-langchain-agents.md
エラー、停止した呼び出し、ジャーナルの不一致をデバッグする	references/debug-applications.md
デプロイを登録する、呼び出しを調査または管理する、状態を読み取りまたは編集する、サーバーにクエリする	Restate CLI
テスト、デプロイ、サーバー設定、Kafka、高度なトピック	同梱の restate-docs MCP サーバーを使用します
コード例とテンプレート	restate example --list --json、github.com/restatedev/examples、github.com/restatedev/ai-examples
TypeScript エージェントの完全なリファレンスアーキテクチャ	restatedev/agent

Restate CLI

実行中の Restate Server を操作するには、restate CLI を使用します。デプロイメントの登録、呼び出しの確認と管理、状態の読み取りと編集、SQL によるサーバー内部の照会を行えます。 CLI は自分自身について説明するので、コマンドやフラグを推測するのではなく、何を実行すべきか CLI に尋ねてください。

• restate --help では、エージェントが CLI をどのように使うべきかを確認できます。restate <command> --help では、コマンドのフラグと使用例を確認できます。
• restate search <what you want to do> では、タスクに適したコマンド、フラグ、または SQL テーブルを検索できます。たとえば、restate search retry a failed invocation のように指定します。
• restate sql --help では SQL による内部調査用のテーブルが一覧表示され、restate sql describe <table> では各テーブルの列が表示されます。
• コマンドで対応できない操作には、restate openapi で Admin API の仕様を出力します。

実行時には、次の点に注意してください。

• 常に --json を指定してください。エラーも含め、出力全体が標準出力に単一の JSON ドキュメントとして出力され、コマンドが確認を求めることはありません。エラーには kind が含まれ、多くの場合、次に実行するコマンドを示す next_steps も含まれます。
• 何かを変更するコマンド（登録、キャンセル、停止、削除、状態の編集など）は、--json だけでは変更を適用しません。"applied": false と apply_command を含む変更予定を出力し、終了コード 3 で終了します。変更予定をユーザーに提示してから、--yes を付けて再実行してください。適用せずにプレビューするには --dry-run を使用します。
• CLI が接続しているサーバーを確認するには、restate whoami --json を実行してください。デフォルトではローカルサーバー（localhost:9070 の Admin API）に接続します。

これらの機能には CLI バージョン 1.8 以降が必要です。restate search が存在しない場合は、CLI のアップグレードをユーザーに依頼してください。

設計前のチェックリスト

Restate サービスのアーキテクチャを設計する前に、次の点を確認してください。

質問	参照先
Restate のサービスタイプ、ステートフルエンティティ、キー設定、並行性について	references/design-and-architecture.md
並行性の上限、テナント分離、下流サービスの保護について	references/flow-control-and-scopes.md
プロジェクト内の Restate 以外のオーケストレーターについて	references/translate-to-restate.md
呼び出しの実行、キャンセル、重複排除、呼び出しへの接続について	references/invocation-lifecycle.md
エラー処理、補償、Saga について	エラー処理ガイド、Saga ガイド
AI エージェントまたは LLM 呼び出しについて	references/ai-agents.md、続いて関連するフレームワークのリファレンス

完了前に必ず確認

以下のチェック項目はすべて必須です。

• すべての副作用、外部 I/O、DB 呼び出しが ctx.run() でラップされている
• ネイティブの乱数、時刻、スリープ、UUID を使用していない。ctx ヘルパーを使用する
• Restate の並行処理コンビネーターのみを使用している（Promise.all、asyncio.gather／wait、CompletableFuture、goroutine とチャネル、select は使用しない）
• ctx.run() 内で ctx 操作を行っていない
• リトライ不可能な失敗には TerminalError を送出している
• Python：裸の except: を使用していない
• AI エージェント：references/ai-agents.md を読み込み、すべての LLM 呼び出しとツールの副作用をジャーナルに記録し、上限のあるリトライポリシーを設定している
• Virtual Objects：デッドロックの循環がない
• サービスを登録し、curl または UI 経由で呼び出している

リプレイテスト — ハンドラーのロジックを変更した場合は必須

ハンドラーのビジネスロジックを変更する場合（新しい ctx 操作、ステップの並べ替え、新しい ctx.run() ブロック、新しい分岐の追加など）は、always-replay を有効にした Testcontainers テストでカバーし、そのテストが通るまで作業を完了したと見なしてはいけません。Always-replay を有効にすると、呼び出しのたびにジャーナルに記録されたすべてのステップがリプレイされるため、非決定性がある場合、本番環境でのリトライ時ではなくテストで失敗します。

• TypeScript：RestateTestEnvironment.start で alwaysReplay: true を設定
• Python：restate.create_test_harness で always_replay=True を設定
• Java / Go：Restate コンテナで RESTATE_WORKER__INVOKER__INACTIVITY_TIMEOUT=0m を設定

動作するスキャフォールドについては、references/<sdk>/api-and-pitfalls.md の Testing セクションを参照してください。