メインコンテンツへスキップ
TypeScript Agent SDK でツールを使うエージェントを実行し、各ステップの後に状態を保存します。こうすると、クラッシュや再起動をしたプロセスが止まったところから再開できます。完成すると、検索ツールでドキュメントに関する質問に答え、各実行を .agent-runs/<run id>.json に書き込み、ID を渡すとその実行を再開するスクリプトが 1 つできます。 このスクリプトは例示用で、ファイルストアは 1 台のマシン向けです。本番環境では同じ load/save の組を残し、保存先をデータベースにしてください。Phaseo は Agent SDK の実行を保存しません。

作成する

1

インストールする

@phaseo/agent-sdk をインストールすると @phaseo/sdk も一緒にインストールされます。キーを設定します。
2

エージェントを書く

agent.ts
3

実行する

再開を試すには、最初の checkpoint の行が出た後に Ctrl+C でスクリプトを止め、出力された実行 ID(UUID)を渡します。

動作を確認する

  • スクリプトはステップごとに checkpoint を 1 回出力し、続いて実行 ID、completed、phaseo.app/docs の URL を含む回答を出力します。
  • .agent-runs/<run id>.json には、実行 ID、ステータス、メッセージ履歴、各ステップのツール呼び出しと結果、最終出力が入ります。
  • 中断した実行の後で再開コマンドを実行すると、新しい実行を始めるのではなく、同じ実行 ID の実行が完了します。
  • 各モデルターンは 設定 → 利用状況 → ログ に表示されます。照合できるように、各リクエスト ID の隣に実行 ID をログに記録してください。

保存される状態の中身

保存される各結果は AgentRunResult 全体です。run(ID、ステータス、メッセージ、使用量、一時停止の情報)、Gateway のリクエスト ID とツール呼び出しを持つ steps、実行完了後の output が含まれます。continueRun() はこれをそのまま受け取るか、runId と state を受け取って自分で load() を呼び出します。 プロセスが止まったときに実行中だったツール呼び出しは、すでに効果を及ぼしている場合があるため、ツールは冪等にしてください。SDK は、結果を得られなかった呼び出しの履歴を修復してから続行します。一時停止と承認については状態と承認で説明しています。

慎重に拡張する

ワークフローごとにエージェントを 1 つにし、ツールの一覧は短く保ち、実行ごとに実行 ID とリクエスト ID を含むログ行を 1 行残してください。承認のための一時停止や、ツールを共有する複数のエージェントが必要になったら、この Gateway クライアントと状態の組を残したまま、その周りに組み立ててください。コードレビューエージェントは承認のための一時停止を追加し、並列ツールはツールを並行して実行します。リクエストの既定値を共有するには、固定のモデルの代わりにプリセットを呼び出してください。
最終更新日 2026年11月5日