@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ja-JP/messaging.md

@@ -0,0 +1,461 @@
+---
+title: "メッセージ"
+description: "Slack、電子メール、テレグラム、または WhatsApp からエージェントと会話します。同じエージェント、同じメモリ、同じツールを使用します。"
+---
+
+# メッセージング
+
+エージェントを Slack、電子メール、テレグラム、または WhatsApp に接続すると、すでに使用しているアプリからエージェントとチャットできるようになります。同じエージェント、同じメモリ、同じツール、同じスレッドであり、より多くの場所からアクセスできるだけです。
+
+> **ディスパッチ テンプレートを使用しますか?** これらすべては **[設定] → [メッセージング]** で設定されます。クリックして各プラットフォームに接続します。独自のテンプレートをカスタマイズまたは構築する場合を除き、このページの残りの部分を読む必要はありません。 [Dispatch](/docs/dispatch) または [Dispatch template reference](/docs/template-dispatch) を参照してください。
+
+## あなたにできること {#what-you-can-do}
+
+- **エージェントにメール** を `agent@yourcompany.com` のようなアドレスに送信します。エージェントは同僚と同じようにスレッド内で返信します。
+- **エージェント**をスレッドに CC してください。エージェントは内容を読んで、質問するとすぐに参加します。
+- **Slack** でエージェントに DM するか、任意のチャネルで `@mention` してください。
+- **携帯電話から Telegram または WhatsApp** でエージェントにメッセージを送信します。
+- **同じエージェント、同じ記憶。** Slack で話した内容は、後で電子メールで送信したときに記憶されます。 Web チャットと外部メッセージは 1 つのスレッド履歴を共有します。
+- 一方向のアプリ内アラート (ベルのアイコン、webhooks) については、[Notifications](/docs/notifications) を参照してください。
+
+```an-diagram title="Many channels, one agent" summary="Every platform fans into the same agent loop and the same SQL thread history — so a Slack DM and an email continue the same conversation."
+{
+  "html": "<div class=\"msg-fanin\"><div class=\"diagram-col\"><div class=\"diagram-node\">Slack</div><div class=\"diagram-node\">Email</div><div class=\"diagram-node\">Telegram</div><div class=\"diagram-node\">WhatsApp</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">One agent loop</span><small class=\"diagram-muted\">same memory · same tools</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>One SQL thread history<br><small class=\"diagram-muted\">web chat + external messages share it</small></div></div>",
+  "css": ".msg-fanin{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.msg-fanin .diagram-col{display:flex;flex-direction:column;gap:8px}.msg-fanin .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Slack をセットアップ {#slack}
+
+### 必要なもの
+
+- アプリをインストールできる Slack ワークスペース (管理者アクセス)
+- 約 5 分
+
+### ステップ
+
+1. **[api.slack.com/apps](https://api.slack.com/apps)** に移動し、**新しいアプリの作成** → **最初から** をクリックします。名前を付けて (例: 「エージェント」)、ワークスペースを選択します。
+2. 左側のサイドバーで、**OAuth と権限** を開きます。 **ボット トークン スコープ** の下に、以下を追加します。
+   - `chat:write` — エージェントがメッセージを送信できるようにします
+   - `app_mentions:read` — エージェントがいつ @ メンションされたかを確認できるようにします (オプション)
+   - `im:history` — エージェントに送信された DM を読めるようにします
+   - `assistant:write` — オプション。 Slack がアシスタント スレッドでネイティブの「考え中...」ステータスを表示できるようにします
+   - `users:read.email` — オプション。 Mail などのテンプレートは、ドラフト キュー ID について Slack 送信者の電子メールを検証するのに役立ちます
+3. そのページの上部にある [**ワークスペースにインストール**] をクリックします。 Slack は、`xoxb-` で始まる **ボット ユーザー OAuth トークン**を提供します。コピーしてください。
+4. サイドバーの **基本情報** に移動し、**署名シークレット**をコピーします。
+5. アプリの設定 (またはホスティング プロバイダーの環境変数パネル) を開き、以下を貼り付けます。
+   - `SLACK_BOT_TOKEN` — `xoxb-…` トークン
+   - `SLACK_SIGNING_SECRET` — 署名シークレット
+   - `SLACK_ALLOWED_TEAM_IDS` — 本番環境で推奨。イベントの送信を許可するカンマ区切りの Slack ワークスペース/チーム ID
+   - `SLACK_ALLOWED_API_APP_IDS` — マルチワークスペース アプリに推奨。この署名シークレットの使用を許可されるカンマ区切りの Slack アプリ ID
+6. Slack に戻り、**イベント サブスクリプション** を開き、オンに切り替えて、次のリクエスト URL を貼り付けます。
+
+   ```テキスト
+   https://your-app.example.com/_agent-native/integrations/slack/webhook
+   ```
+
+   次に、**ボット イベントに登録する** で、`message.im` (DM 用) を追加し、オプションで `app_mention` (チャンネル メンション用) を追加します。保存します。
+
+7. Slack でボットに DM を送信します。応答するはずです。
+
+### オプション: アプリの展開
+
+Slack アプリ展開により、アプリは Slack の通常のリンク プレビューをよりリッチなリンク プレビューに置き換えることができます
+プレビュー。 Clips はこれを Loom スタイルの再生可能なビデオ プレビューに使用します。
+
+アプリを展開する必要がある場合は、次の追加のボット スコープを追加します。
+
+- `links:read` — 登録されたドメインが投稿されたときに Slack がアプリに通知できるようにします
+- `links:write` — アプリで Slack のデフォルトのプレビューを置き換えます
+- `links.embed:write` — アプリに承認されたメディア/プレーヤー URL を埋め込みます
+
+次に、`link_shared` イベントに登録し、パブリック アプリ ドメインを登録します
+**App Unfurl ドメイン** の下。クリップのみの再生可能なプレビューの場合は、Slack
+イベント サブスクリプション URL のリクエスト:
+
+```text
+https://your-clips.example.com/api/slack/unfurl
+```
+
+Slack アプリには 1 つのイベント API リクエスト URL があります。同じ Slack アプリが
+エージェント チャット イベントとクリップの両方が展開され、Slack イベントを小さなネットワーク経由でルーティングします
+メッセージ イベントを `/_agent-native/integrations/slack/webhook` に送信するディスパッチャ
+および `link_shared` イベントを Clips unfurl ハンドラーに送信します。
+
+### ヒント
+
+- **チャンネルメンション** — ノイズを避けるため、ボットは @ メンションされた場合にのみチャンネル内で応答します。
+- **DM** — すべての DM はエージェントとのプライベートな会話として扱われます。
+- **同じ ID、すべてのチャネル** — Slack ユーザーがアプリの登録ユーザーと同じメールアドレスを持っている場合、エージェントはそれらを同一人物として扱います。
+- **運用許可リスト** — 有効な署名シークレットが予期しないワークスペースで再利用されないように、`SLACK_ALLOWED_TEAM_IDS` を設定し、共有 Slack アプリの場合は `SLACK_ALLOWED_API_APP_IDS` を設定します。
+- **Clips アプリの展開** — Slack 用のインストール可能な Agent-Native Clips は、`SLACK_CLIENT_ID`、`SLACK_CLIENT_SECRET`、`SLACK_SIGNING_SECRET`、および `/api/slack/oauth/callback` を使用します。接続された各 Slack ワークスペースは、`app_secrets` で独自の暗号化されたボット トークンを取得します。 `SLACK_BOT_TOKEN` は、従来の単一ワークスペースのフォールバックにすぎません。
+
+## テレグラムを設定する {#telegram}
+
+### 必要なもの
+
+- 携帯電話の Telegram アプリ
+- 約 3 分
+
+### ステップ
+
+1. テレグラムを開いて **[@BotFather](https://t.me/BotFather)** とメッセージを送信します。
+2. `/newbot` を送信し、プロンプトに従ってボットに名前を付けます。 BotFather は **HTTP API トークン**で応答します。コピーしてください。
+3. アプリの環境変数で、次のように設定します。
+   - `TELEGRAM_BOT_TOKEN` — BotFather からのトークン
+4. デプロイ後、`POST`ing によって Webhook を次の場所にあるアプリに登録します。
+
+   ```テキスト
+   POST https://your-app.example.com/_agent-native/integrations/telegram/setup
+   ```
+
+   これは、アプリの Webhook にメッセージを送信するように Telegram に指示します。これを行う必要があるのは、展開ごとに 1 回だけです。
+
+5. Telegram でボットを見つけて (BotFather から提供されたユーザー名を検索して)、メッセージを送信します。
+
+## 電子メールを設定する {#email}
+
+電子メールは最も強力な統合です。エージェントは独自のアドレスを取得し、スレッド内で返信し、会話に CC することができ、送信者の電子メールを ID として使用します。 `/link` コマンドは必要ありません。
+
+### 必要なもの
+
+- あなたが管理するドメイン (または、無料の再送信サブドメインを使用できます。以下を参照)
+- 受信メールと送信メールを処理するための **Resend** または **SendGrid** を備えたアカウント
+- 約 10 分
+
+### 手順 (再送信あり - 最も簡単)
+
+1. **[resend.com](https://resend.com)** でサインアップしてください。無料利用枠で始めるには十分です。
+2. エージェントの電子メール アドレスがどのように表示されるかを選択します:
+   - **最も簡単:** 空き `<your-slug>.resend.app` アドレスを使用します。DNS は必要ありません。
+   - **ブランド:** Resend の **ドメイン** ページにカスタム ドメイン (`yourcompany.com` など) を追加し、DNS の手順に従います。
+3. 再送信で、**Webhooks** → **エンドポイントの追加** を開き、次の場所を指定します。
+
+   ```テキスト
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
+
+   **`email.received`** イベントに登録します。再送信すると署名シークレットが得られますので、それをコピーしてください。
+
+4. アプリの環境変数で、次のように設定します。
+   - `EMAIL_AGENT_ADDRESS` — エージェントがメールを受信するアドレス (例: `agent@yourcompany.com`)
+   - `RESEND_API_KEY` — 再送信 API キー
+   - `EMAIL_INBOUND_WEBHOOK_SECRET` — 再送信からの署名シークレット (推奨、署名検証に使用)
+
+5. エージェントのアドレスに電子メールを送信します。同じスレッドで返信されます。
+
+### ステップ (SendGrid を使用)
+
+1. **[sendgrid.com](https://sendgrid.com)** でサインアップしてください。
+2. 受信メールが SendGrid に流れるように、ドメインの MX レコードを追加します。
+   ```テキスト
+   MX yourcompany.com → mx.sendgrid.net (優先度 10)
+   ```
+3. **[設定] → [受信解析]** を開き、**[ホストと URL の追加]** をクリックして、宛先を次のように設定します。
+
+   ```テキスト
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
+
+4. 環境変数を設定します:
+   - `EMAIL_AGENT_ADDRESS` — エージェントが受信するアドレス
+   - `SENDGRID_API_KEY` — SendGrid API キー
+   - `EMAIL_INBOUND_WEBHOOK_SECRET` — 署名付き webhooks を設定した場合のオプションの Svix 署名シークレット
+
+5. エージェントのアドレスに電子メールを送信します。
+
+### ヒント
+
+- **エージェントをCC**してスレッドに組み込みます。エージェントが CC されると、すべてに返信するため、スレッド全体が応答を確認できます。
+- **スレッド処理は正常に機能します** — エージェントは標準の `Message-ID` / `In-Reply-To` / `References` ヘッダーを使用するため、返信はどの電子メール クライアントでも適切なスレッドに留まります。
+- **ID は送信者の電子メールです。** `alice@acme.com` がエージェントにメールを送信する場合、それが彼女の ID です。リンクやサインアップ フローはありません。
+- **リッチ応答** — エージェントの応答のマークダウンは、電子メールでは HTML として表示されます。
+- **許可されたドメイン** — 統合の構成で `allowedDomains` を設定することで、エージェントに電子メールを送信できる人を制限します。他のドメインからのメッセージは破棄されます。
+- **レート制限** — 送信者ごとに 1 時間あたり 20 件の受信メッセージ。
+
+## WhatsApp をセットアップする {#whatsapp}
+
+### 必要なもの
+
+- メタ (Facebook) 開発者アカウント
+- ボット専用の電話番号
+- 約 15 分 (Meta のセットアップが最も手順が多い)
+
+### ステップ
+
+1. **[Meta Developer Portal](https://developers.facebook.com/)** に移動し、**アプリの作成** をクリックして、**ビジネス** タイプを選択します。
+2. **WhatsApp** 製品をアプリに追加し、送信者として使用する電話番号を構成します。
+3. WhatsApp 設定ページから、次のものを取得します。
+   - **アクセス トークン** (一時的なものはテストには適しています。公開する前に永続的なトークンを生成してください)
+   - **電話番号 ID**
+4. 検証トークンとして使用するランダムな文字列を選択します。下の 2 つの場所に同じ値を入力します。
+5. アプリの環境変数で、次のように設定します。
+   - `WHATSAPP_ACCESS_TOKEN` — アクセス トークン
+   - `WHATSAPP_PHONE_NUMBER_ID` — 電話番号 ID
+   - `WHATSAPP_VERIFY_TOKEN` — 選択したランダムな文字列
+6. Meta の WhatsApp 設定に戻り、Webhook セクションを開いて次のように設定します。
+
+   ```テキスト
+   コールバック URL: https://your-app.example.com/_agent-native/integrations/whatsapp/webhook
+   トークンの検証: WHATSAPP_VERIFY_TOKEN として設定したのと同じランダムな文字列
+   ```
+
+   `messages` フィールドを購読します。
+
+7. ボットの電話番号に WhatsApp メッセージを送信します。
+
+## エージェントの中央受信箱として Dispatch を使用する {#dispatch}
+
+複数のエージェント ネイティブ アプリ (メール、カレンダー、分析など) を実行している場合、推奨されるパターンは、**[Dispatch](/docs/dispatch)** でメッセージングを設定し ([template reference](/docs/template-dispatch) も参照)、[A2A](/docs/a2a-protocol) 経由で作業をドメイン アプリにルーティングすることです。
+
+これが良い理由:
+
+- **1 つのエージェント、1 つの受信箱。** すべてのチャネル (Slack、電子メール、テレグラム、WhatsApp) が Dispatch に流れます。統合のセットアップは 1 回だけです。
+- **代理人を派遣します。** 「先週のサインアップを要約してください」と依頼する — 派遣は分析エージェントに電話します。 「アリスへの返信の下書き」を依頼します。ディスパッチはメール エージェントに電話します。
+- **設定ではなくクリックです。** Dispatch の **[設定] → [メッセージング]** ページには、env-var フィールドが組み込まれたすべてのプラットフォームの接続ボタンがあります。
+
+オーケストレーターが必要ない場合は、このページの環境変数を使用して、単一のテンプレートでメッセージングを直接接続できます。
+
+---
+
+## 開発者向け {#for-developers}
+
+以下はすべて技術リファレンスです。上記のセットアップ手順が完了している場合は、統合プラグインをカスタマイズするか、独自のアダプターを構築する場合を除き、ここで終了できます。
+
+### 仕組み {#how-it-works}
+
+受信プラットフォーム webhooks はクロスプラットフォーム SQL キュー パターンを使用するため、プラットフォーム固有のバックグラウンド実行 API に依存することなく、すべてのサーバーレス ホスト (Netlify、Vercel、Cloudflare Workers、Fly、Render、Node) で動作します。
+
+1. プラットフォーム `POST` から `/_agent-native/integrations/<platform>/webhook`。ハンドラーは署名を検証し、ペイロードを解析して `IncomingMessage` にし、**`status='pending'` を使用して `integration_pending_tasks` に行を挿入**します。
+2. ハンドラーはファイア アンド フォーゲット `POST /_agent-native/integrations/process-task` を起動し、Slack の 3 秒以内の SLA 以内にすぐに `200` を返します。
+3. プロセッサ エンドポイントは、独自のフル タイムアウト バジェットを使用して **新しい関数の実行** で実行されます。これはタスクをアトミックに要求し (`pending` → `claimPendingTask` 経由の `processing`)、エージェント ループを実行し、アダプターを通じて応答をポストし、タスク `completed` をマークします。
+4. 定期的な再試行ジョブ (`startPendingTasksRetryJob`、60 秒ごと) は、`pending` >90 秒または `processing` >5 分でスタックしたタスクをスイープし、プロセッサを再起動します。試行回数は 3 回に制限され、その後は `failed` とマークされました。
+
+```an-diagram title="Inbound webhook lifecycle" summary="The webhook only verifies, enqueues, and returns 200. A fresh function execution drains the queue and runs the agent loop, with a 60s retry job as the safety net."
+{
+  "html": "<div class=\"msg-flow\"><div class=\"msg-row\"><div class=\"diagram-node\">Platform<br><small class=\"diagram-muted\">Slack · email · etc.</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><strong>/webhook</strong><br><small class=\"diagram-muted\">verify signature + parse</small><br><span class=\"diagram-pill\">INSERT pending task</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">return 200</div></div><div class=\"msg-fire\"><span class=\"diagram-muted\">fire-and-forget</span> <span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</span></div><div class=\"msg-row\"><div class=\"diagram-box\" data-rough><strong>/process-task</strong><br><small class=\"diagram-muted\">fresh execution · own timeout</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">claim</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">agent loop</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">adapter.sendResponse</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">completed</div></div><div class=\"diagram-panel msg-retry\" data-rough><span class=\"diagram-pill warn\">every 60s</span> <span class=\"diagram-muted\">retry job sweeps stuck tasks (pending &gt;90s · processing &gt;5min) and re-fires /process-task &mdash; capped at 3 attempts, then <strong>failed</strong></span></div></div>",
+  "css": ".msg-flow{display:flex;flex-direction:column;gap:12px}.msg-flow .msg-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.msg-flow .msg-fire{display:flex;align-items:center;gap:8px;padding-inline-start:12px}.msg-flow .msg-retry{display:flex;align-items:center;gap:8px;flex-wrap:wrap}"
+}
+```
+
+インバウンドとアウトバウンドの会話は同じ SQL スレッド内で行われるため、ウェブ UI から Slack DM を継続したり、その逆も可能です。
+
+```an-api
+{
+  "method": "POST",
+  "path": "/_agent-native/integrations/slack/webhook",
+  "summary": "Slack Events API inbound webhook",
+  "description": "Receives Slack events (DMs and channel `app_mention`s). Verifies the request signature, parses the payload into an `IncomingMessage`, inserts a `pending` row into `integration_pending_tasks`, fires the fresh-execution processor, and returns **200 immediately** — well inside Slack's 3-second SLA. The same route shape exists per platform under `/_agent-native/integrations/<platform>/webhook`.",
+  "auth": "HMAC-SHA256 of the raw body using `SLACK_SIGNING_SECRET`, checked against the `X-Slack-Signature` header. In production also gated by `SLACK_ALLOWED_TEAM_IDS` / `SLACK_ALLOWED_API_APP_IDS`.",
+  "params": [
+    { "name": "X-Slack-Signature", "in": "header", "type": "string", "required": true, "description": "Slack request signature, verified before any processing." },
+    { "name": "X-Slack-Request-Timestamp", "in": "header", "type": "string", "required": true, "description": "Timestamp used in the signature base string." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"type\": \"event_callback\",\n  \"team_id\": \"T0123\",\n  \"api_app_id\": \"A0123\",\n  \"event\": {\n    \"type\": \"message\",\n    \"channel_type\": \"im\",\n    \"user\": \"U0123\",\n    \"text\": \"summarize last week's signups\"\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "Acknowledged immediately. The agent loop runs in the separate /process-task execution. The first time a Request URL is saved, Slack POSTs a `url_verification` challenge and the adapter replies with the `challenge` value automatically.", "example": "{ \"ok\": true }" },
+    { "status": "401", "description": "Signature verification failed, or the team/app id is not in the production allowlist." }
+  ]
+}
+```
+
+#### このパターンを使用する理由 (プラットフォームネイティブのショートカットではない) {#why-this-pattern}
+
+サーバーレス関数は、応答が送信された瞬間にフリーズします。 fire-and-forget Promise、遅延された LLM 呼び出し、実行中のツールなど、まだ実行中のものはすべて、実行中に強制終了されます。エージェント ループを存続させる唯一の方法は、**新しい** 関数の実行を開始することです。これは、自己起動型 `/process-task` POST が行うことです。
+
+NOT は次のいずれかの代替手段を使用してください:
+
+- **Netlify バックグラウンド関数** — Netlify のみ。`-background.ts` ファイル名サフィックスが必要で、他のホストごとに機能しません。
+- **Cloudflare `event.waitUntil()`** — CF ワーカーのみ。ポータブルではありません。
+- **Vercel `after()` / Fluid** — Vercel のみ、特定のランタイムの背後でゲートされます。
+- **`return` 後の Naked fire-and-forget Promise** — 関数がフリーズするとサイレントに強制終了されます。ログにエラーはありませんが、ユーザーが応答を受け取らないだけです。
+
+SQL キュー + セルフ Webhook + 再試行ジョブの組み合わせは、サポートされているすべてのホストで同様に動作する唯一のものです。再試行ジョブはセーフティ ネットです。関数がフリーズする前に最初のディスパッチがフラッシュされるとは決して想定しないでください。
+
+### 統合プラグイン {#plugin}
+
+カスタム バージョンが存在しない場合、プラグインは自動マウントされます。カスタマイズするには、以下を作成します。
+
+```ts
+// server/plugins/integrations.ts
+import { createIntegrationsPlugin } from "@agent-native/core/server";
+import { scriptRegistry } from "../../agent.config";
+
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+});
+```
+
+どのプラットフォームがアクティブになるかは、どの環境変数が設定されているかによって異なります。プラグインは、`/_agent-native/integrations/` の下にそれぞれの Webhook ルートを登録します。
+
+### Webhook URL {#webhook-urls}
+
+```text
+/_agent-native/integrations/slack/webhook
+/_agent-native/integrations/telegram/webhook
+/_agent-native/integrations/whatsapp/webhook
+/_agent-native/integrations/email/webhook
+```
+
+Telegram は、ワンタイム セットアップ エンドポイントも公開します。
+
+```text
+POST /_agent-native/integrations/telegram/setup
+```
+
+### 環境変数 {#env-vars}
+
+| プラットフォーム | 必須                                                                                | オプション                                            |
+| ---------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Slack            | `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`                                           | `SLACK_ALLOWED_TEAM_IDS`, `SLACK_ALLOWED_API_APP_IDS` |
+| 電報             | `TELEGRAM_BOT_TOKEN`                                                                | —                                                     |
+| メール           | `EMAIL_AGENT_ADDRESS`、および `RESEND_API_KEY` または `SENDGRID_API_KEY` のいずれか | `EMAIL_INBOUND_WEBHOOK_SECRET`                        |
+| WhatsApp         | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`        | —                                                     |
+
+すべての資格情報は環境変数内に存在します。データベースやソース コードには決して存在しません。サイドバー設定 UI またはホスティング プロバイダーの環境パネルを使用します。
+
+### スレッドとアイデンティティ {#threading-and-identity}
+
+各外部会話は、エージェント ネイティブ データベース内の永続スレッドにマップされます。
+
+- **Slack DM** → Slack ユーザーごとに 1 つのスレッド。
+- **Slack チャンネル @mention** → チャンネルごとに 1 つのスレッド。
+- **テレグラム チャット** → テレグラム チャットごとに 1 つのスレッド。
+- **WhatsApp での会話** → WhatsApp 番号ごとに 1 つのスレッド。
+- **電子メール** → `Message-ID` / `In-Reply-To` / `References` ヘッダーから派生したスレッド。
+
+外部スレッドは、ソース プラットフォームのタグが付けられて、Web 発のスレッドと並んで Web UI に表示されます。 ID 解決: Slack/メール ユーザーが登録ユーザーと一致すると (通常はメールで)、そのアカウントにリンクされます。
+
+### セキュリティ {#security}
+
+すべての受信 Webhook は処理前に署名検証されます。
+
+- **Slack** — `SLACK_SIGNING_SECRET` を使用したボディの HMAC ～ SHA256。`X-Slack-Signature` ヘッダーに対してチェックされます。初めてリクエスト URL を Slack のイベント サブスクリプション パネルに保存すると、Slack はそれに `url_verification` チャレンジを POST します。フレームワークのアダプターはこれを検出し、自動的に `challenge` 値を返します。そのため、ユーザー側で特別な作業を行わなくても、URL は Slack で緑色に変わります。
+- **Telegram** — Webhook の登録時に設定されるシークレット トークン。
+- **WhatsApp** — Meta の検証チャレンジ (`WHATSAPP_VERIFY_TOKEN` を使用) とペイロード署名。
+- **電子メール** — `EMAIL_INBOUND_WEBHOOK_SECRET` が設定されている場合の Svix スタイルの署名検証 (Resend と SendGrid は両方ともこの形式を使用します)。シークレットが設定されていない場合、Webhook は受け入れられますが、警告が記録されます。
+
+電子メール アダプタは次のことも強制します。
+
+- **許可されたドメイン** — 統合の `integration_configs` 行のオプションの `allowedDomains` 配列。リスト外の送信者は削除されます。
+- **レート制限** — SQL キューに基づくレート制限は、送信者ごとに 1 時間あたり 20 件の受信メッセージです。
+
+### プロアクティブな送信 {#proactive-sends}
+
+エージェントは、`"slack"`、`"telegram"`、`"whatsapp"`、または `"email"` の `platform` フィールドを使用して `send-platform-message` アクションを呼び出すことで、独自のイニシアチブでメッセージ (通知、リマインダー、スケジュールされた概要) を送信できます。このアクションは `packages/dispatch/src/actions/send-platform-message.ts` の Dispatch パッケージ内に存在し、任意のテンプレートにコピー/適応させることができます。
+
+### カスタム アダプター {#custom-adapters}
+
+新しいメッセージング プラットフォームを追加するには、`PlatformAdapter` インターフェイスを実装します。
+
+```ts
+import type { H3Event } from "h3";
+import type {
+  PlatformAdapter,
+  IncomingMessage,
+  OutgoingMessage,
+} from "@agent-native/core/server";
+import type { EnvKeyConfig } from "@agent-native/core/server";
+
+const myAdapter: PlatformAdapter = {
+  platform: "discord",
+  label: "Discord",
+
+  // Env keys this adapter needs (rendered in the settings UI)
+  getRequiredEnvKeys(): EnvKeyConfig[] {
+    return [
+      { key: "DISCORD_BOT_TOKEN", label: "Discord Bot Token", required: true },
+    ];
+  },
+
+  // Handle platform-specific verification challenges (e.g. Slack's
+  // url_verification). Return { handled: true, response } to short-circuit.
+  async handleVerification(event: H3Event) {
+    return { handled: false };
+  },
+
+  // Validate the webhook request signature
+  async verifyWebhook(event: H3Event): Promise<boolean> {
+    // Validate signature headers; return true if authentic
+    return true;
+  },
+
+  // Parse the webhook payload into a normalized IncomingMessage.
+  // Return null to silently ignore the event (bot messages, edits, etc.).
+  async parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null> {
+    return {
+      platform: "discord",
+      externalThreadId: "channel-or-thread-id",
+      text: "the user's message",
+      senderId: "discord-user-id",
+      platformContext: { channelId: "channel-id" },
+      timestamp: Date.now(),
+    };
+  },
+
+  // Format plain agent text into a platform-appropriate OutgoingMessage.
+  // opts.threadDeepLinkUrl, when provided, is a URL back to the originating
+  // thread in the dispatch UI — render it as a button (Slack) or inline link.
+  formatAgentResponse(
+    text: string,
+    opts?: { threadDeepLinkUrl?: string },
+  ): OutgoingMessage {
+    return { text, platformContext: {} };
+  },
+
+  // Post the agent's response back to the platform
+  async sendResponse(
+    message: OutgoingMessage,
+    context: IncomingMessage,
+  ): Promise<void> {
+    // Call the platform's API, using context.platformContext for routing
+  },
+
+  // Return current connection/configuration status for the settings UI.
+  // baseUrl is the app's public URL, used for status checks that need it.
+  async getStatus(baseUrl?: string) {
+    return {
+      platform: "discord",
+      label: "Discord",
+      enabled: true,
+      configured: !!process.env.DISCORD_BOT_TOKEN,
+    };
+  },
+};
+```
+
+統合プラグインに登録します。
+
+```ts
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  adapters: [myAdapter],
+});
+```
+
+リファレンス実装は `packages/core/src/integrations/adapters/` (`slack.ts`、`telegram.ts`、`whatsapp.ts`、`email.ts`) にあります。電子メール アダプターは、署名検証、スレッド化、レート制限、HTML レンダリングを含む最も完全な例です。
+
+### ディスパッチ + A2A 継続による信頼性 {#reliability}
+
+[Dispatch](/docs/dispatch) が [A2A](/docs/a2a-protocol#continuations) 経由で別のアプリにリクエストを委任すると、ダウンストリーム エージェントが実行中にクラッシュした場合でも、継続回復フローによりユーザーは Slack/電子メール返信を受け取ることが保証されます。元の Webhook タスクは、継続が解決されるか、再試行スイープによってスタックとしてマークされるまで、`processing` に残ります。いずれにせよ、プラットフォームのスレッドは沈黙するのではなく、最終的な応答を受け取ります。
+
+これは、Dispatch が前面に配置された複数アプリのワークスペースが、メッセージングに直接接続された単一のテンプレートよりも復元力が高いことを意味します。1 つのダウンストリーム アプリで障害が発生すると、応答がドロップされるのではなく、適切なエラー メッセージが表示されます。配達保証の詳細については、[A2A continuations](/docs/a2a-protocol#continuations) を参照してください。
+
+### よくある落とし穴 {#pitfalls}
+
+- **リクエスト本文を二重に読み取らないでください。** h3 v2 のボディ ストリームは 1 回のみ消費します。フレームワークが `event.node.req.body` を解析した後で `readBody(event)` を呼び出すと (またはその逆)、2 回目の読み取りでリクエストが無期限にハングします。これは、Resend と SendGrid で最も頻繁に発生します。どちらも受信ペイロードをストリーミングし、ダングリング読み取りが解決されず、プラットフォームがタイムアウトし、重複を排除するまで Webhook が再試行されます。フレームワークの Webhook ハンドラーを独自のミドルウェアでラップする場合は、ハンドラーに再解析させるのではなく、`incoming` オプションを介して、既に解析された `IncomingMessage` を渡します。
+- **Webhook ハンドラー内でエージェント ループを実行しないでください。** ハンドラーはキューに入れて返す必要があります。エージェント ループはプロセッサの新たな実行で実行されます。これをインラインにすると、サーバーレスのフリーズにより実行が強制終了されることが保証されます。さらに、公開ゲートウェイ統合 (Netlify や Vercel など) では、厳格な HTTP タイムアウト制限 (Netlify の 10 秒のリクエスト制限など) が強制されます。エージェントの実行とツールの実行にはこの時間枠よりも時間がかかることが多いため、Webhook リクエスト内でループを同期的に実行しようとすると、ゲートウェイが接続を終了し、実行が中止され、応答がドロップされます。 HMAC 署名付きセルフ Webhook `/process-task` キュー パターンは、完全なエージェント ループを安全に実行しながらゲートウェイ制限を満たす唯一の方法です。
+- **コールド スタートでは重複排除メモリに依存しないでください。** 重複排除キーは、インプロセス マップではなく、SQL `(platform, external_event_key)` の一意のインデックスに存在します。キューを置き換える場合は、SQL レベルの重複排除を維持しないと、Slack の再試行が重複してエージェントの重複実行がトリガーされます。
+- **セルフ Webhook URL を到達可能な状態に保ちます。** プロセッサー URL は、`APP_URL` / `URL` / `DEPLOY_URL` / `BETTER_AUTH_URL` から構築され、受信リクエスト ヘッダーにフォールバックします。ホスト名が書き換えられたプレビュー展開では、これらのいずれかを明示的に設定しないと、ディスパッチが 404 に達します。
+
+### こちらもご覧ください {#see-also}
+
+- [Dispatch](/docs/dispatch) — アプリ全体で中央受信トレイを使用するための概念の概要
+- [Dispatch template reference](/docs/template-dispatch) — マルチアプリ ワークスペースに推奨される中央受信トレイ
+- [A2A Protocol](/docs/a2a-protocol) — 継続リカバリを含む、Dispatch デリゲートが他のエージェントにどのように機能するか
+- [Agent Mentions](/docs/agent-mentions) — Web チャット内の `@` メンション エージェント

package/corpus/core/docs/content/locales/ja-JP/migration-workbench.md

@@ -0,0 +1,33 @@
+---
+title: "Agent-Native への移行 (/移行)"
+description: "移行は、別個のアプリではなく、Agent-Native コード ワークスペースに組み込まれた /merge 目標です。完全なガイドについては、Agent-Native コード UI を参照してください。"
+---
+
+# Agent-Native への移行 (/移行)
+
+移行は **個別の製品やテンプレートではありません** - 組み込まれているものです
+[Agent-Native Code](/docs/code-agents-ui) ワークスペース内の `/migrate` ゴール。
+通常のコード セッションとして実行され、再開、接続、検査、停止が可能です。
+
+```an-diagram title="/migrate is a Code session, not a separate app" summary="A path, URL, or description goes in; the run shares the same store, transcript, and controls as every other Code session, and can emit a portable dossier."
+{
+  "html": "<div class=\"diagram-migrate\"><div class=\"diagram-col\"><div class=\"diagram-pill\">./local-app</div><div class=\"diagram-pill\">https://example.com</div><div class=\"diagram-pill\">--describe \\\"...\\\"</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">/migrate goal</span><small class=\"diagram-muted\">same store · transcript · run controls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\" data-rough>Migrated app</div><div class=\"diagram-pill ok\">--emit dossier</div></div></div>",
+  "css": ".diagram-migrate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-migrate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-migrate .diagram-arrow{font-size:22px;line-height:1}.diagram-migrate .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+```bash
+npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
+npx @agent-native/core@latest code /migrate https://example.com --describe "marketing site plus dashboard"
+npx @agent-native/core@latest migrate ./my-next-app --out ../migrated-app   # shortcut into the same goal
+```
+
+完全ガイド — 入力形状 (パス / URL / 説明)、`--emit` ドシエ
+プラン モードと自動モード、実行コントロール、認証情報、デスクトップ ディープ リンク、および
+`@agent-native/migrate` パッケージのエクスポート — に存在します
+[Agent-Native Code UI → Migrating to Agent-Native](/docs/code-agents-ui#migrate).
+
+> [!NOTE]
+> 従来の非表示の `migration` 詳細アプリは削除されました。コードを使用してください
+> ワークスペース、デスクトップ コード タブ、またはサポートされるように出力されたドシエ
+> 面。