SNA とは？

SNA (Skills-Native Application) は、エージェントランタイムの上に プロダクトを作るための SDK です。アプリが LLM API を直接呼ぶ代わりに 小さなサーバへリクエストすると、そのサーバが Claude Code、 Codex、OpenCode プロセスを管理します。SNA は 3 つのランタイムを 1 つの正規化 API で扱います。

SNA がなぜ始まったのかは 出発点 に 短くまとめています。

構造

your app
   │
   │  HTTP (request/response, ordering)
   │  WS   (live events, fanout)
   ▼
SNA server  ──spawn──►  claude-code | codex | opencode
   │
   ▼
SQLite (canonical history)

サーバを 1 つ起動し、セッション を 1 つまたは複数開きます。各 セッションでは、実際の CLI バイナリ（claude、codex、opencode） が子プロセスとして spawn されます。SNA は各ランタイムのイベント、 履歴、権限モデルを同じ形にそろえるため、アプリコードがランタイム別の 分岐で散らかりません。

用語の基準: 公開ドキュメントでは Claude Code、Codex、OpenCode のような 実行対象を ランタイム と呼びます。ただし既存 SDK との互換性のため、 API フィールド名の provider、providerOptions、modelProvider は そのまま残しています。

どんな問題を解くのか

公式 LLM API はステートレスな completion には向いています。ですが、 プロダクトが次の要件を持つと実装が一気に複雑になります。

• ツール、ファイル編集、承認のある長期稼働エージェント: 結局 Claude Code や Codex のループを自分で再実装することになります。
• 同じエージェントを別のランタイムへ切り替える: コード編集は Claude、画像生成は Codex、コスト最適化は OpenCode のように分けたくても、 ランタイムを変えるたびに統合コードを書き直すことになります。
• ランタイム切り替え後も続く会話履歴: ネイティブフォーマットは 相互運用しないため、1 つのランタイムに固定するか、切り替えのたびに 文脈を失うことになります。
• ユーザーに同じに見える権限フロー: Claude の PreToolUse フック と Codex の JSON-RPC 承認はプロトコルも UX も異なります。

SNA はこれらの問題を、"実際の CLI をそのまま使う" という方針で 解きます。CLI 群はすでに難しい部分（ツールディスパッチ、 サンドボックス、権限ゲート、履歴）を処理しています。SNA はそれらを ラップし、1 つのアプリコードベースで 3 つのランタイムすべてに 対応できるようにします。

モデル API や SDK で直接作る場合との違い

モデル API やベンダ SDK は、ステートレスなモデル呼び出しには 適したレイヤーです。ただし、それ自体はエージェントランタイムでは ありません。API の上に直接作る場合、プロダクト側が API キー管理、 ツールのオーケストレーションループ、承認 UX、ファイル編集処理、 ストリーミングイベントの形式、再試行、履歴フォーマットを自分で 持つことになります。

SNA は別の経路を取ります。各ランタイムが提供する エージェント CLI harness をオーケストレーションします。この harness は、モデルを作っている会社が 自社モデルに最も合うように調整している実行層です。コンテキストをどう準備するか、 ツールをどう呼ぶか、権限をどう要求するか、サンドボックス境界をどう守るか、 長く続く作業をどう回復するかが、すでに組み込まれています。SNA はその harness を捨てず、アプリから見える API だけを 1 つの形にそろえます。

SNA でも、実行環境には CLI のインストールと認証が必要です。違いは、 プロダクトが低レベルの completion API の上に各 model vendor の agent harness を 作り直さなくてよい点です。

得られるもの

• 1 つの正規化された会話モデル。 メッセージは 2 つの軸を 持つフラットブロックとして保存されます: actor (user/assistant/system) × kind (text/thinking/tool_use/tool_result/status/error)。 ランタイムネイティブの形式は、必要に応じてここから派生します。設計背景は Actor と kind にあります。
• キャッシュに乗りやすいセッション継続。 通常の流れでは、同じ SNA セッションに次のターンを agent.send で送るだけです。SNA が アクティブなランタイムネイティブの会話/thread を維持し、プロセスを 作り直す必要がある時だけ正規化履歴から再開します。アプリ側で履歴を ロードし直したり、プロンプトを再送したり、キャッシュキーを直接 設定したりする必要はありません。
• 3 層アトリビューション。 すべてのブロックが provider (ランタイム)、modelProvider (ベンダ)、model (スラッグ) を 記録します。セッション途中で何を切り替えても、各ブロックの出どころは 保たれます。
• 正規化されたイベントプロトコル。 WebSocket または SSE 上の 15 種類のイベントタイプ: assistant_delta、tool_use、 permission_needed、complete など。
• 正規化された権限フロー。 1 つの API が Claude の PreToolUse フックと Codex の JSON-RPC 承認の両方を公開します。アプリの承認 ダイアログはランタイムによって変わりません。
• 再起動不要のランタイム制御。 スレッド途中でモデル、権限 モード、作業ディレクトリを変更できます。Restart と resume が正規化 ブロックからランタイムネイティブ履歴を再構築します。
• 一級の単発 API。 completion() と runOnce() は、セッション 管理なしで単発呼び出しを処理します。自動補完やチャット命名のような 短い単一プロンプト作業に適しており、ストリーミングコールバックも オプションで使えます。

誰のためのもの

• エージェント CLI の上にチャットや copilot を載せるプロダクト ビルダー。 SNA はアプリとランタイムの境界です。アプリは UI を担当し、 SNA はランタイム接続を担当します。
• マルチランタイムアプリ。 Claude Code、Codex、OpenCode の中 からユーザーに選ばせたい、または自動ルーティングしたいが、 ランタイムごとに統合コードを分岐させたくない場合。
• Electron / デスクトップアプリ。 エージェントをローカルに 組み込みます。ローンチャがサーバを子プロセスとして fork し、 asar-unpacked パスの処理やネイティブバインディングの検出まで行います。

これではない もの

• ホスト型 LLM エンドポイントではありません。 SNA は自身が動く ホスト上で実際の CLI を spawn します。バイナリと認証情報はユーザーが 提供します。
• エージェントフレームワークではありません。 エージェントの作り方は 説明しません。それは Claude Code / Codex / OpenCode の役割であり、 SNA はアプリがそれらを操作できるようにする層です。
• 下層 CLI の挙動を隠すラッパーではありません。 Claude Code が ファイルを編集した場合は、実際の編集が見えます。Codex が画像を生成した 場合は、実際のファイルパスが返ります。SNA は形を正規化しますが、 意味は正規化しません。

SNA と Zed の Agent Client Protocol を比較するなら、 SNA と ACP もあわせて見てください。

次の行先

5 分間のハンズオンは はじめに にあります。 サーバを起動し、セッションを開き、プロンプトを送信して、イベントを 確認する流れを扱います。その後は 中心モデル で セッションモデル、正規化履歴、ランタイムを続けて確認してください。 ワイヤリファレンスは API Spec にまとめています。