@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ja-JP/tracking.md

@@ -0,0 +1,236 @@
+---
+title: "追跡と分析"
+description: "プラグイン可能なプロバイダーによるサーバー側分析 — PostHog、Mixpanel、Amplitude、またはカスタム Webhook"
+---
+
+# 分析トラッキング
+
+1 つの機能、複数の宛先。任意のサーバー側コード (actions、プラグイン、サーバー ルート) から `track()` を呼び出すと、イベントが登録されているすべての分析プロバイダーに広がります。 SDK 依存関係、クライアント側スクリプト、ブロッキングはありません。同じ `track()` は [browser/app code](#client) でも利用でき、同じプロバイダーにルーティングされます。
+
+これは _product_ 分析です。PostHog/Mixpanel/Amplitude に流れるアプリのイベントです。独自のデータベースに保存されている*エージェント品質*指標 (トレース、コスト、評価、フィードバック) については、[Observability](/docs/observability) を参照してください。
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "order.completed",
+  { total: 49.99, items: 3 },
+  { userId: "steve@builder.io" },
+);
+```
+
+```an-diagram title="One track() call, every provider" summary="Server and client callers hit the same registry, which fans every event out to all active providers in parallel."
+{
+  "html": "<div class=\"trk\"><div class=\"diagram-col\"><div class=\"diagram-node\">Server code<br><small class=\"diagram-muted\">actions &middot; plugins &middot; routes</small></div><div class=\"diagram-node\">Browser code<br><small class=\"diagram-muted\">POST /_agent-native/track</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Provider registry</span><small class=\"diagram-muted\">fan-out, fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">PostHog</div><div class=\"diagram-box\">Mixpanel</div><div class=\"diagram-box\">Amplitude</div><div class=\"diagram-box\">Webhook</div></div></div>",
+  "css": ".trk{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.trk .diagram-col{display:flex;flex-direction:column;gap:8px}.trk .diagram-arrow{font-size:22px;line-height:1}.trk .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 組み込みプロバイダ {#built-in}
+
+環境変数を設定すると、サーバーの起動時にプロバイダーが自動登録されます。コードの変更は必要ありません。
+
+| プロバイダ     | 環境変数                                                                                       |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| ポストホッグ   | `POSTHOG_API_KEY` (必須)、`POSTHOG_HOST` (オプション、デフォルトは `https://us.i.posthog.com`) |
+| ミックスパネル | `MIXPANEL_TOKEN`                                                                               |
+| 振幅           | `AMPLITUDE_API_KEY`                                                                            |
+| Webhook        | `TRACKING_WEBHOOK_URL` (必須)、`TRACKING_WEBHOOK_AUTH` (オプションの `Authorization` ヘッダー) |
+
+複数のプロバイダーを同時にアクティブにすることができます。すべての出来事は彼ら全員に行きます。
+
+## API {#api}
+
+### `track(name, properties?, meta?)` {#track}
+
+分析イベントを発生させます。すべての登録プロバイダーにファンアウトします。
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "steve@builder.io" },
+);
+```
+
+### `identify(userId, traits?)` {#identify}
+
+特徴を持つユーザーを特定します。それをサポートするプロバイダー (PostHog、Mixpanel、Amplitude、Webhook) に転送されます。
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+```
+
+カスタム バックエンド、プロバイダー レジストリ API、またはバッチ処理/シングルトン内部が必要ですか?末尾の [Advanced: custom providers & internals](#advanced) を参照してください。
+
+## テンプレートでの track() の使用 {#templates}
+
+アクション ハンドラーから `track()` を呼び出して、ユーザーまたはエージェントのアクティビティを記録します。
+
+```ts
+// actions/create-project.ts
+import { defineAction } from "@agent-native/core/action";
+import { track } from "@agent-native/core/tracking";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Create a new project.",
+  schema: z.object({
+    name: z.string(),
+    template: z.string().optional(),
+  }),
+  run: async ({ name, template }, ctx) => {
+    const project = await db
+      .insert(projects)
+      .values({ name, template })
+      .returning();
+
+    track("project.created", { name, template }, { userId: ctx.userEmail });
+
+    return { ok: true, projectId: project[0].id };
+  },
+});
+```
+
+追跡呼び出しはファイア アンド フォーゲットです。呼び出しはすぐに返され、アクションの応答をブロックすることはありません。
+
+## クライアント側の追跡 {#client}
+
+`track()` はブラウザ/アプリ コードからも動作します。 `@agent-native/core/client` からクライアント ツインをインポートし、同じ方法で呼び出します。イベントを `POST /_agent-native/track` のフレームワーク ルートに POST し、**同じ** 登録されたサーバー側プロバイダー (PostHog、Mixpanel、Amplitude、Webhook) に転送します。ブラウザには分析 SDK は提供されず、プロバイダー キーはクライアント側で公開されません。
+
+```an-api title="The client tracking route"
+{
+  "method": "POST",
+  "path": "/_agent-native/track",
+  "summary": "Forward a browser event to the registered server-side providers",
+  "auth": "Session required + same-origin/CSRF marker (set automatically by the client helper). Not an open analytics relay.",
+  "params": [
+    { "name": "name", "in": "body", "type": "string", "required": true, "description": "Event name. Capped at 200 characters." },
+    { "name": "properties", "in": "body", "type": "object", "description": "Event properties (~16KB cap). `source: \"client\"` and the active `org_id` are added server-side." }
+  ],
+  "description": "Identity is resolved **server-side** from the session — browser code never passes a `userId`. Fire-and-forget: never blocks the UI, never throws, swallows network errors. Oversized or malformed payloads are rejected."
+}
+```
+
+```ts
+import { track } from "@agent-native/core/client";
+
+// e.g. inside a click handler or effect
+track("checkout.completed", { total: 49.99, items: 3 });
+```
+
+[server `track()`](#track) との主な違い:
+
+- **ID 引数はありません。** イベントはサーバー側でサインインしているユーザー (およびアクティブな組織、`properties` の `org_id`) に関連付けられます。ブラウザ コードは `userId` を渡すことはありません。
+- **`source: "client"`** がすべてのイベントのプロパティに追加されるため、クライアント側のイベントとサーバー側のイベントを区別できます。
+- **Fire-and-forget.** UI をブロックしたり、ネットワーク エラーをスローしたり、飲み込んだりすることはありません。
+- **認証済み、ファーストパーティのみ。** ルートにはセッションと同一オリジン/CSRF マーカー (ヘルパーによって自動的に設定される) が必要なため、オープン分析リレーとして使用することはできません。 `name` の上限は 200 文字、`properties` の上限は 16 KB です。サイズが大きすぎるペイロードや形式が不正なペイロードは拒否されます。
+
+これは、Agent Native 独自の製品分析を強化するフレームワークの内部ブラウザー テレメトリ (`trackEvent()` / 自動ページビュー — 以下の [Browser defaults](#browser-defaults) を参照) とは異なります。設定されたプロバイダーに到達する必要があるアプリ独自の分析イベントには、`track()` を使用します。
+
+## 上級: カスタムプロバイダーと内部 {#advanced}
+
+ほとんどのアプリでは、`track()` / `identify()` と組み込みプロバイダーのみが必要です。表面の残りの部分 (カスタム プロバイダーの登録、`TrackingProvider` インターフェイス、内部処理のバッチ処理、フレームワーク独自のブラウザ テレメトリ) は以下のとおりです。
+
+<details>
+<summary>ZZQ1QXZプロバイダー レジストリ API、インターフェイス、内部、およびブラウザーのデフォルト </strong>ZZQ3QXZ
+
+### `registerTrackingProvider(provider)` {#register}
+
+分析バックエンドのカスタム プロバイダーを登録します。
+
+```ts
+import { registerTrackingProvider } from "@agent-native/core/tracking";
+
+registerTrackingProvider({
+  name: "my-analytics",
+  track(event) {
+    // Send event to your backend
+    fetch("https://analytics.example.com/events", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(event),
+    }).catch(() => {});
+  },
+  identify(userId, traits) {
+    // Optional — link user identity to future events
+  },
+  flush() {
+    // Optional — called on graceful shutdown
+  },
+});
+```
+
+### `flushTracking()` {#flush}
+
+すべてのプロバイダーをフラッシュします。プロセスが終了する前に呼び出して、保留中のイベントが確実に送信されるようにします。
+
+```ts
+import { flushTracking } from "@agent-native/core/tracking";
+
+await flushTracking();
+```
+
+### `unregisterTrackingProvider(name)` {#unregister}
+
+プロバイダを名前で削除します。プロバイダが見つかって削除された場合は、`true` を返します。
+
+### `listTrackingProviders()` {#list}
+
+登録されているすべてのプロバイダの名前を返します。
+
+### TrackingProvider インターフェイス {#provider-interface}
+
+```ts
+interface TrackingProvider {
+  name: string;
+  track(event: TrackingEvent): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+interface TrackingEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp?: string;
+  userId?: string;
+}
+```
+
+`name` と `track` のみが必要です。 `identify` と `flush` はオプションです。バックエンドがユーザー ID とバッチ配信をサポートしている場合は実装してください。
+
+### 仕組み {#internals}
+
+- **バッチ処理された HTTP** — 組み込みプロバイダーはイベントをキューに入れ、10 秒ごと、または 50 個のイベントが蓄積したときのいずれか早い方でフラッシュします。これにより、データを失うことなく送信リクエストが最小限に抑えられます。
+- **SDK 依存関係はありません** — すべての組み込みプロバイダーは生の `fetch()` を使用します。 PostHog SDK、Mixpanel SDK、Amplitude SDK はありません。フレームワークを軽量に保ちます。
+- **ベストエフォート配信** — プロバイダーのエラーが捕捉され、ログに記録されます。分析統合が失敗しても、呼び出し元がクラッシュしたり、リクエストの処理がブロックされたりすることはありません。
+- **グローバル シングルトン** — レジストリは `globalThis` の `Symbol.for` キーを使用するため、複数の ESM グラフ インスタンス (開発モード Vite + Nitro、シンボリックリンク) が 1 つのプロバイダー セットを共有します。
+
+### ブラウザのデフォルト {#browser-defaults}
+
+これは、フレームワーク独自の内部テレメトリをカバーします。これは主にフレームワークの貢献者と高度なテンプレート作成者に関連します。
+
+テンプレート ルートは起動時に `configureTracking()` を 1 回呼び出します。 `trackEvent()` で送信されるブラウザ イベントには、アプリ/テンプレート コンテキストと、アプリが解決できる場合の現在の LLM 接続が自動的に含まれます。
+
+- `llm_connection` — `builder`、`anthropic`、`openai`、`google`、`none` などの正規化されたプロバイダー ラベル
+- `llm_engine` — エンジン ID (例: `builder` または `ai-sdk:openai`)
+- `llm_model` — 既知の場合は選択/デフォルトのモデル
+- `llm_connection_source` — `app_secrets`、`settings`、または `env`
+- `llm_connection_configured` — LLM 接続が利用可能かどうか
+
+フレームワークは、Connect Builder CTA からの `builder connect clicked` も追跡し、サーバー側の Builder 接続ルートは開始/成功/失敗したライフサイクル イベントを追跡します。 `configureTracking()` はフレームワークによって自動的に呼び出されます。独自のテンプレート コードで呼び出す必要はありません。
+
+</details>
+
+## 次は何ですか
+
+- [**Actions**](/docs/actions) — ほとんどの追跡通話が発信される場所
+- [**Server Plugins**](/docs/server) — `registerBuiltinProviders()` は起動時にコアルートプラグインで実行されます
+- [**Secrets**](/docs/security) — 追跡プロバイダーの API キーを管理

package/docs/content/locales/ja-JP/using-your-agent.md

@@ -0,0 +1,71 @@
+---
+title: "エージェントの使用"
+description: "エージェントとの日々の作業のループ。エージェントは、あなたが見ているものを見て、それを指示し、埋め込み、UI-light を実行し、一緒に共同編集します。"
+---
+
+# エージェントの使用
+
+エージェント ネイティブの背後にある決定的な考え方は、エージェントと UI が **対等なパートナーである**ということです。その理由については、[What Is Agent-Native?](/docs/what-is-agent-native) を参照してください。このセクションは、その約束の残り半分、つまり、エージェントがアプリの隣にドッキングされたときに実際にエージェントを操作するとどのような感じになるかについて説明します。
+
+シンプルなスルーラインがあります。エージェントは、あなたが見ているものを**見て**、あなたが望むものに**指示**し、どこにでも**埋め込む**ことができ、最適な場合は完全に**UIライト**にすることができ、同じドキュメントを同時に**共同編集**できます。それぞれがこのセクションの 1 ページです。
+
+```an-diagram title="The day-to-day loop" summary="Five ways of working with a docked agent — each is a page in this section."
+{
+  "html": "<div class=\"diagram-loop\"><div class=\"diagram-card\"><strong>Sees</strong><small class=\"diagram-muted\">your view &amp; selection</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Direct</strong><small class=\"diagram-muted\">@-mentions &amp; voice</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embed</strong><small class=\"diagram-muted\">drop into any app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>UI-light</strong><small class=\"diagram-muted\">chat is the product</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">Co-edit</span><small class=\"diagram-muted\">live, side by side</small></div></div>",
+  "css": ".diagram-loop{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-loop .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:130px;flex:1}.diagram-loop .diagram-arrow{align-self:center;font-size:22px;line-height:1}"
+}
+```
+
+## あなたが見ているものが見えます {#it-sees}
+
+エージェントはあなたの画面を見ていないわけではありません。電子メールを開くと、どのスレッドであるかがわかります。チャートを選択すると、どのチャートであるかがわかります。段落を強調表示すると、その範囲のみに作用します。この認識の共有により、毎回文脈を詳しく説明することなく、「これに返信」または「選択内容を要約」と言うことができます。
+
+これが機能するのは、現在のナビゲーションと選択が `application_state` SQL に存在し、エージェントがコンテキストの一部として読み取るためです。エージェントは同じ状態 (ビューを開いたり、行を選択したり) を元に戻すこともできるため、トランスクリプトではなく実際の UI で動作するのを確認できます。
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Shared awareness is two-way.** You and the agent both read and write `application_state`, so \"reply to this\" or \"summarize the selection\" just works — and when the agent navigates, the real UI moves with it."
+}
+```
+
+→ [**Context Awareness**](/docs/context-awareness) — ナビゲーション状態、画面表示、ナビゲーション コマンド、およびエージェントが画面と同期する方法。
+
+## あなたが指示します {#you-direct-it}
+
+ほとんどの場合、チャットに入力することでエージェントを操作します。 2 つの点で高速化が可能です。
+
+**メンション。** カスタム エージェント、接続されているエージェント、またはファイルに `@` のタグを付けて、会話に組み込みます。「`@analytics` に先週の数字を引き出してから、概要の下書きを作成します。」メンションは、作曲家から離れることなく、適切な専門家に連絡したり、適切なコンテキストを添付したりする方法です。
+
+**Voice.** 作曲家はマイクを持っています。 Builder がホストするトランスクリプションから、独自のキーの持ち込み、ブラウザのフォールバックまで、プロバイダー オプションを使用して、リクエストを入力する代わりに口述入力します。
+
+→ [**Agent Mentions**](/docs/agent-mentions) — `@` - カスタム エージェント、接続されているエージェント、チャット内のファイルについて言及します。
+→ [**Voice Input**](/docs/voice-input) — チャット コンポーザーでのディクテーションとトランスクリプションのルーティング方法。
+
+## あなたが埋め込みます {#you-embed-it}
+
+エージェントは、タブで移動できる別個のアプリではありません。これは、いくつかの React コンポーネント (サイドバー、生のパネル、`sendToAgentChat()` 呼び出し) として出荷され、任意のアプリにドロップできます。 `<AgentSidebar>` をレンダリングしてすべての画面に切り替え可能なエージェントを提供するか、ワンショットの LLM 呼び出しを実行する代わりに特定のタスクをチャットに渡すボタンを配線します。
+
+→ [**Drop-in Agent**](/docs/drop-in-agent) — `<AgentPanel>`、`<AgentSidebar>`、および `sendToAgentChat()` を任意の React アプリにマウントします。
+→ [**Agent Surfaces**](/docs/agent-surfaces) — ワークフローをヘッドレス、チャットファースト、埋め込み、または完全なアプリのいずれにするかを選択します。
+
+## UI-light に行くことができます {#ui-light}
+
+すべてのアプリに完全なダッシュボードが必要なわけではありません。エージェントが製品である場合、カスタム UI のほとんどをスキップできます。アプリを開いて必要なものを尋ね、残りはエージェントに任せます。エージェントには履歴、ワークスペース、設定などの管理画面がまだありますが、主な操作はクリックではなく会話です。
+
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — エージェントが製品全体であるアプリ。
+
+## あなたはそれを共同編集します {#you-co-edit}
+
+あなたとエージェントが同じドキュメントで作業している場合、交代する必要はありません。リアルタイムのコラボレーションにより、エージェントの編集内容は、チームメイトの場合と同じように、ライブ カーソルで上書きされずに、あなたの編集内容と並行してストリーミングされます。機能している間は入力を続けることができ、変更が発生するとその内容が反映されます。
+
+→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — 同じドキュメント内でライブ カーソルとエージェント編集を使用したマルチユーザーの共同編集。
+
+## 次は何ですか {#whats-next}
+
+- [**Context Awareness**](/docs/context-awareness) — エージェントはあなたが何を見ているのかを知っています
+- [**Agent Mentions**](/docs/agent-mentions) — `@` メンションで指示
+- [**Voice Input**](/docs/voice-input) — 話すことで指示
+- [**Drop-in Agent**](/docs/drop-in-agent) — React アプリに埋め込みます
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) — エージェントが製品の場合は UI-light に移行します
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — 同じドキュメントを一緒に共同編集します

package/docs/content/locales/ja-JP/voice-input.md

@@ -0,0 +1,81 @@
+---
+title: "音声入力"
+description: "エージェント チャット コンポーザーでの音声ディクテーション — Builder Gemini、BYOK プロバイダー、およびブラウザー Web 音声フォールバック。"
+---
+
+# 音声入力
+
+すべてのエージェント ネイティブ アプリにはチャット コンポーザーにマイクがあります。それをクリックして話すと、あなたの言葉がプロンプトに文字化されます。モバイルで便利、長いプロンプトに便利、手が他のことにあるときに便利。
+
+フレームワークはこれらすべてを自動的に処理します。 Builder に接続しているユーザーは、デフォルトで Builder がホストする Gemini Flash-Lite を取得します。それ以外の場合、ユーザーは独自のプロバイダー キーを持ち込むか、ブラウザーの音声認識にフォールバックできます。
+
+## 仕組み {#how-it-works}
+
+作曲家の音声ボタンはブラウザで音声を録音し、プロバイダを選択します。
+
+1. **Builder Gemini Flash-Lite (Builder が接続されている場合のデフォルト)。** ブラウザは `/_agent-native/transcribe-voice` にオーディオを POST し、`/_agent-native/transcribe-voice` は Gemini Flash-Lite を使用して Builder.io を介してプロキシします。 Google API キーは必要ありません。
+2. **BYOK クラウド プロバイダー。** ユーザーは [設定] から Google Gemini、Groq Whisper、または OpenAI Whisper を選択できます。このルートは、展開認証情報を共有する前に、ユーザー スコープの暗号化されたシークレットを解決します。
+3. **ブラウザ Web 音声 API (フォールバック)。** サーバー プロバイダーが利用できない場合、作曲者はブラウザの組み込み音声認識を使用できます。 Chromium ベースのブラウザ (Chrome、Edge、Arc) および Safari で動作します。精度が低くなります。ライブストリーム。
+
+プロバイダーの選択は、`voice-transcription-prefs` の下のアプリケーション状態に保存されるため、ユーザーはサイドバー設定で `"auto"` (デフォルト - 利用可能な最適なプロバイダーを選択)、`"builder-gemini"`、`"builder"`、`"gemini"`、`"groq"`、`"openai"`、または `"browser"` を強制できます。
+
+```an-diagram title="Voice transcription provider fallback" summary="The composer records audio, then walks server providers in order, dropping to the browser Web Speech API only when no server provider is available."
+{
+  "html": "<div class=\"diagram-voice\"><div class=\"diagram-node\">Mic button<br><small class=\"diagram-muted\">records webm/opus</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill accent\">1 &middot; Builder Gemini</div><small class=\"diagram-muted\">default when Builder connected</small><div class=\"diagram-pill\">2 &middot; BYOK cloud</div><small class=\"diagram-muted\">Gemini &middot; Groq &middot; OpenAI Whisper</small></div><div class=\"diagram-arrow diagram-warn\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box diagram-warn\" data-rough>3 &middot; Browser Web Speech<br><small class=\"diagram-muted\">fallback on 400 &middot; streams live</small></div></div>",
+  "css": ".diagram-voice{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-voice .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-voice .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+ルートは **同一オリジンのみ**です。クロスサイト POST は拒否されるため、攻撃者は外部ページから転写クレジットを書き込むことができません。
+
+## プロバイダの有効化 {#enabling-providers}
+
+Builder が最も簡単なパスです。設定から Builder.io に接続すると、デフォルトのプロバイダーは Builder Gemini Flash-Lite になります。 BYOK プロバイダーの場合は、[設定] → [API キー] で一致するキーを追加します。
+
+### ユーザーごと (SaaS に推奨)
+
+ユーザーは、エージェントのサイドバー設定 UI を介して独自のキーを設定します。これは、ユーザー スコープの暗号化されたシークレットとして保存されます (`readAppSecret` 経由)。各ユーザーは自分の文字起こしに対して料金を支払います。ホストへのコストはゼロです。
+
+### 共有 (内部ツール用)
+
+`GEMINI_API_KEY`、`GROQ_API_KEY`、または `OPENAI_API_KEY` を環境変数として、または `settings` テーブルに設定します。すべてのユーザーの文字起こしは共有キーにヒットします。
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Credential resolution order:** the route checks the user's own encrypted secret first, then the shared deployment key. A power user with their own key always overrides the shared one. If neither exists, the route returns a 400 the composer recognizes and silently falls back to browser Web Speech."
+}
+```
+
+## ルート {#route}
+
+```an-api title="Voice transcription route"
+{
+  "method": "POST",
+  "path": "/_agent-native/transcribe-voice",
+  "summary": "Transcribe a recorded audio clip into prompt text",
+  "auth": "Active session (Better Auth cookie). Same-origin only.",
+  "description": "The composer POSTs the recorded clip here; the route resolves a provider and returns the transcribed text. You should not call this directly.",
+  "params": [
+    { "name": "audio", "in": "body", "type": "file", "required": true, "description": "The recorded clip, webm/opus by default. Max 25 MB." },
+    { "name": "provider", "in": "body", "type": "string", "required": false, "description": "Optional override, e.g. gemini, groq, openai, builder." }
+  ],
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "Transcription succeeded", "example": "{ \"text\": \"reply to Sara that I'll be there by 3\" }" },
+    { "status": "400", "description": "No server provider configured — the composer recognizes this and falls back to Web Speech", "example": "{ \"error\": \"no_provider\" }" }
+  ]
+}
+```
+
+これを直接呼び出す必要はありません。コンポーザーが呼び出します。カスタム入力サーフェスを構築している場合は、まず `@agent-native/core/client` の共有コンポーザー/音声クライアント部分を再利用します。このルートは、マルチパート オーディオを送信する必要があるカスタム ヘルパーの下位レベルのトランスポート境界として扱います。
+
+## プロバイダーのカスタマイズ {#customizing}
+
+プロバイダー フィールドはプレーンなアプリケーション状態キーであるため、エージェントは要求に応じて変更できます (`"use the browser speech recognizer instead"`)。異なる要件を持つテンプレートを構築している場合 (オンプレミスの Whisper 導入など)、フレームワークがデフォルトをマウントする前に、独自の `transcribe-voice` ルートを登録してルート ハンドラーを交換します。
+
+## 次は何ですか
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — 音声ボタンを公開するコンポーザー
+- [**Onboarding**](/docs/onboarding) — セットアップ手順としてプロバイダー キーを登録する
+- [**Security & Data Scoping**](/docs/security) — 暗号化されたシークレットがユーザーごとにどのように保存されるか

package/docs/content/locales/ja-JP/what-is-agent-native.md

@@ -0,0 +1,202 @@
+---
+title: "Agent-Native とは何ですか?"
+description: "ほとんどの AI アプリが中途半端に構築されていると感じる理由、アプリが真のエージェントネイティブになる理由、その結果として日常のエクスペリエンスがどのようになるか"
+---
+
+# Agent-Native とは何ですか?
+
+エージェント ネイティブは、AI エージェントとその周囲の製品表面が **対等なパートナー**となるソフトウェアを構築する方法です。そのサーフェスは、1 つのカスタム アクション、リッチ チャット、または完全な UI を備えたヘッドレス エージェントにすることができます。重要な部分は、エージェントと人間が同じ actions、データベース、状態を共有するということです。
+
+このページで覚えていることが 1 つしかない場合は、これを覚えておいてください。今日のほとんどの AI アプリは、役に立つ一歩手前で止まっており、そのギャップが現在のこの分野における最大の間違いです。
+
+## ユーザーとしてどのように見えるか {#what-it-looks-like}
+
+バックグラウンド ワーカー、受信トレイ、カレンダー、フォーム ビルダー、または分析ダッシュボードを想像してください。カスタム画面がまだない場合もあります。1 つのアクションまたは 1 つのヘッドレス アプリエージェント プロンプトを実行します。場合によっては、最初の画面がチャットであ​​る場合があります。要望を尋ねると、エージェントがセットアップをガイドし、表やグラフを表示して、適切なアプリ ビューを開きます。場合によっては、チャットが完全なアプリケーションの右側にドッキングされることがあります。これらのシェイプ全体で、次のことができます。
+
+- **実際の操作から始めます。** 1 つの永続アクションは、CLI、HTTP、MCP、A2A、アプリエージェント ループ、その後 UI から実行できます。
+- **UI があるときに通常クリックするものをクリックします。** すべてのボタン、リスト、ダッシュボード、キーボード ショートカット - これらはすべて、エージェントが呼び出すことができる同じ操作を呼び出します。
+- **または、質問してください。** エージェントに「3 時までに到着するというサラからのメールへの返信」と入力します。適切なスレッドを開き、返信の下書きを作成し、それを表示して承認を求めます。まさに手動で行うのと同じです。
+- **内容を確認してください。** 電子メールを開くと、エージェントはどの電子メールであるかを認識します。チャートを選択すると、エージェントはどのチャートであるかを認識します。段落を強調表示して Cmd+I を押すと、エージェントはその段落のみに作用します。
+- **動作を確認してください。** エージェントがビューを開く、下書きを編集する、レポートを実行するなどの作業を行うと、UI がリアルタイムで更新されます。マウスでいつでも停止、リダイレクト、または引き継ぐことができます。
+- **チームメイトのように操作しましょう。** フィードバックを提供し、別のタスクをキューに入れ、指示を編集し、昨日の作業を監査します。記憶しており、時間の経過とともにワークフローが改善されます。
+
+それがエージェントネイティブが設計されたエクスペリエンスです。ここで、ほとんどの製品がそこに到達できない理由を説明します。
+
+## ほとんどの「AI アプリ」が不十分な理由 (はしごの原則) {#the-ladder}
+
+ほとんどのチームははしごのように登る段階があり、ほとんどのチームが 1 段目で止まるのが早すぎます。
+
+### ラング 1 — 単一の LLM 呼び出し (アンチパターン) {#rung-one}
+
+テキスト ボックスがプロンプトを送信し、AI が文字列を返し、それを表示します。たぶんスピナー付き。ユーザーが軌道修正する方法も、AI が行動を起こす方法も、何が起こったのか、なぜ起こったのかを確認する方法もありません。
+
+これはどこでも見かけます。「AI 機能」は、基本的に SaaS 製品に取り付けられた「要約」ボタンです。デモでは印象的に見えますが、現実が混乱した瞬間に壊れます。それは製品ではありません。それはおもちゃです。
+
+### ラング 2 — ツールを使用したチャット {#rung-two}
+
+AI が*できるようになりました*。 「メールの下書き」、「連絡先の検索」、「クエリの実行」といったツールと、目の前で機能するチャット インターフェイスがあり、ツールの呼び出しと結果が進行中に表示されます。これは、Claude、ChatGPT、および Cursor の内部の外観です。
+
+これは本当のステップアップです。しかし、それ自体は依然としてチャット ウィンドウです。適切な UI はありません。ダッシュボード、リスト、フォーム、キーボード ショートカット、チーム コラボレーションはありません。 AI が混乱すると、右ボタンをクリックするだけでなく、再入力することになります。開発者以外は、この形式で実際の作業を行うのに苦労しています。
+
+### ラング 3 — エージェント + UI が同等のパートナーとして {#rung-three}
+
+これはエージェントネイティブです。エージェントの周りに実際のフル機能のアプリを追加します。そして重要なことに、エージェントが実行できるすべてのアクションは UI のボタンでもあり、ユーザーがクリックするすべてのボタンはエージェントが使用するのと同じロジックを実行します。 1 つの実装で 2 つの方法が可能です。
+
+横線 3 に到達すると 3 つのことが変わります:
+
+- **チャットボットへのボタンの追加を停止しました。アプリにエージェントを追加しました。** これは、両面ではるかに高品質の製品です。
+- **エージェントは実際のコンテキストを持っています。** エージェントは、あなたが何を見ているのか、何を選択しているのか、何をしたのかを認識します。 UI が読み取るのと同じデータベースに書き込むため、その作業はすぐに表示されます。
+- **外部エージェントもこれを使用できます。** 他のエージェント ネイティブ アプリは、[A2A protocol](/docs/a2a-protocol) を介してこのアプリの actions を呼び出すことができます。 Claude コード、Codex、ChatGPT カスタム MCP アプリ、カーソル、およびその他の MCP ホストは、[MCP server](/docs/mcp-protocol) として駆動できます。 1 つのアプリに多数のエントリ ポイント。
+
+それは 3 番です。これはエージェントネイティブです。
+
+```an-diagram title="The Ladder Principle" summary="Most teams stop at rung 1 or 2. Agent-native is rung 3 — a real app and a real agent over one shared action surface."
+{
+  "html": "<div class=\"diagram-ladder\"><div class=\"diagram-card rung rung-3\"><span class=\"diagram-pill accent\">Rung 3 · agent-native</span><strong>Agent + UI as equal partners</strong><small class=\"diagram-muted\">One action surface. Every agent tool is also a button; every button runs the same logic the agent uses.</small></div><div class=\"diagram-card rung rung-2\"><span class=\"diagram-pill\">Rung 2</span><strong>A chat with tools</strong><small class=\"diagram-muted\">The agent can act — but it is still just a chat window. No dashboards, lists, or shortcuts.</small></div><div class=\"diagram-card rung rung-1\"><span class=\"diagram-pill warn\">Rung 1</span><strong>A single LLM call</strong><small class=\"diagram-muted\">Prompt in, string out. Impressive in a demo; breaks the moment reality gets messy.</small></div></div>",
+  "css": ".diagram-ladder{display:flex;flex-direction:column;gap:14px}.diagram-ladder .rung{display:flex;flex-direction:column;gap:6px;padding:16px 18px}.diagram-ladder .rung-2{margin-inline-end:48px}.diagram-ladder .rung-1{margin-inline-end:96px}"
+}
+```
+
+これらすべてが同じアクション定義にどのように影響するかについては、[Key Concepts — Protocols](/docs/key-concepts#protocols) を参照してください。
+
+## すべてのエージェントに UI が必要な理由 {#why-every-agent-needs-a-ui}
+
+エージェントがすべての面倒な作業を行っても、人間は依然として次のことを行う必要があります。
+
+- **動作を確認** — 進行状況、中間出力、変更内容
+- **ステアリング** — フィードバックを提供し、中断し、次のタスクをキューに入れます
+- **管理** — 命令、skills、メモリ、スケジュールされたジョブ、接続されているアカウントを編集します
+- **作業内容を検査** — ドラフトを確認し、履歴を監査し、間違いをロールバックします
+- **出力を共有** — チームメイトに送信するダッシュボード、レポート、フォーム、リンク
+
+少なくとも、「エージェントの UI」は可観測性と管理のダッシュボードです。最大でも、エージェントが副操縦士として組み込まれた完全な SaaS アプリになります。両端はエージェントネイティブとしてカウントされ、サーフェスは書き換えることなく一方から拡張できます。
+
+事前に形状を選択する必要はありません。エージェントは、ヘッドレスで実行したり、リッチ チャットの背後に座ったり、同じアクション サーフェスを中心とした完全なアプリケーション内で実行したりできます。具体的な形状と API については、[Agent Surfaces](/docs/agent-surfaces) を参照してください。
+
+## すべてのアプリがエージェントから恩恵を受ける理由 {#why-every-app-benefits-from-an-agent}
+
+裏側も同様に重要です。既存の SaaS 製品は同じ壁にぶつかり続けています。必要なものの 80% はうまく機能しますが、20% はまったく変更できません。チャット サイドバーを追加しても、この問題が解決されることはほとんどありません。通常、チャットでは、UI でできることを実際には「実行」できません。
+
+エージェントネイティブではそれが逆転します。アプリ内のすべてのアクションは一度定義され、ボタンとエージェント ツールの両方として公開されるため、エージェントは維持するための別の「AI ワールド」を必要とせずに、ボタンで実行できることすべて、さらにはそれ以上のことを実行できます。自然言語は、クリックと並んで第一級の入力になります。
+
+その議論は「エージェントが UI を置き換える」というものではありません。それは、「**エージェントは、UI を頂点として、対等なパートナーとしてアプリケーション内に属します**」です。エージェントが製品であるアプリであっても、人間が監視、設定、操作するために UI が必要です。[Agent Surfaces — Headless](/docs/agent-surfaces#headless) を参照してください。
+
+## エージェント + UI パリティ {#agent-ui-parity}
+
+これが決定的な原則です。
+
+> **UI から** — ボタンをクリックし、フォームに入力し、ビューを移動します。 UI はデータベースに書き込みます。エージェントは結果を確認します。
+>
+> **エージェントから** — 自然言語、A2A、Slack、テレグラム経由の他のエージェント。エージェントはデータベースに書き込みます。 UI は自動的に更新されます。
+
+```an-diagram title="One system, two ways in" summary="The agent and the UI write to the same actions and the same database. Whatever one does, the other sees."
+{
+  "html": "<div class=\"diagram-parity\"><div class=\"diagram-col\"><div class=\"diagram-node\">Human<br><small class=\"diagram-muted\">clicks, forms, shortcuts</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">natural language · A2A · Slack</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defined once</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">SQL database</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">UI updates live</div></div>",
+  "css": ".diagram-parity{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-parity .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-parity .diagram-arrow{font-size:22px;line-height:1}.diagram-parity .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+エージェントが下書きメールを作成すると、UI に表示されます。 「送信」をクリックすると、エージェントは送信されたことを認識します。個別の「エージェント ワールド」と「UI ワールド」は存在せず、それは 1 つのシステムです。これを機能させるアーキテクチャについては、[Key Concepts](/docs/key-concepts) を参照してください。
+
+## カスタマイズは通常電動工具用に予約されています {#workspace-customization}
+
+Claude コードのようなツールが非常に強力であると感じられる理由は、モデルではなく、**カスタマイズ レイヤー**です。プロジェクトごとの指示、skills、メモリ、サブエージェント、接続されたサービスです。コードベース、好み、チームに合わせてエージェントを形成できます。
+
+エージェント ネイティブでは、アプリを離れることなく、すべてのユーザーに同じカスタマイズ レイヤーが提供されます。各アプリには個人用 **ワークスペース** が付属しており、あなた (またはチームのメンバー) は次のことができます。
+
+- 全員のエージェントが読むチーム全体のルールを編集します
+- 設定を修正すると、エージェントに自動的に設定を記憶させます
+- 再利用可能なハウツー ガイドを `/slash` コマンドとして作成します
+- 特定のタスク用のカスタム サブエージェントを保持します (`@mentions` で呼び出されます)
+- cron でジョブを実行するようにスケジュールを設定します (例: 「毎週月曜日の朝、先週の要約」)
+- ユーザーごとの MCP サーバー経由で外部サービス (Gmail、ストライプ、Slack、内部 API) に接続
+
+ひねり: すべてはファイル システムではなくデータベースに保存されます。起動する開発環境も、ユーザーごとのコンテナもありません。すべてのユーザーは、テーブル内のすべての行であるため、自分の完全なワークスペース (個人のメモリ、個人の接続、個人の skills) を基本的に無料で利用できます。これが、実際のマルチテナント SaaS 製品内で Claude コード レベルの柔軟性を実現できる理由です。
+
+完全な概念については、[Workspace](/docs/workspace) を参照してください。
+
+## 何が違うのか {#what-makes-it-different}
+
+| アプローチ                                       | 説明                                                                                                                                                  |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **AI が組み込まれた従来のアプリ**                | AI は後付けです。オートコンプリート、概要、またはアプリ内で実際には何もできないチャット サイドバーに限定されます。                                    |
+| **純粋なチャット/エージェント インターフェイス** | 強力だがアクセスできない。ダッシュボードもワークフローも永続性もありません。開発者以外はそれらを効果的に使用できません。                              |
+| **SaaS 用 Claude コード / Codex**                | 独自のマシンを使用する開発者に最適です。マルチテナント SaaS には変換されません。開発ボックス上のユーザーごとに 1 つのコードベースでは拡張できません。 |
+| **エージェントネイティブ アプリ**                | エージェントは第一級市民です。同じデータベース、同じ状態を共有し、UI が実行できることはすべて実行でき、その逆も同様です。                             |
+
+## チーム全体の開発 {#whole-team-development}
+
+エージェントネイティブは開発者だけを対象としたものではありません。エージェントはアプリ自身のコードを編集できるため、アプリの進化は開発者のみのアクティビティではなくなります。
+
+- **デザイナー** は、エージェントを通じて実行中のアプリでデザインを直接更新します
+- **プロダクト マネージャー** は機能を追加し、フローを説明することでフローを更新します
+- **QA** はアプリをテストし、エージェントに問題のある部分を修正するよう依頼します
+- **チームの誰もが** 自然言語を通じて貢献します
+
+ビジョン: 引き継ぎを減らし、小規模なチームの仕事を 1 人で行う
+
+## フォークしてカスタマイズ {#fork-and-customize}
+
+エージェント ネイティブ アプリは、フォークとカスタマイズのモデルに従います。 **テンプレート** (カレンダー、コンテンツ、スライド、アナリティクス、メール、クリップ、デザイン、フォーム、ディスパッチ) から始めて、それを自分のものにします。それぞれは、空の足場ではなく、卸売でフォークした完全に機能する SaaS 製品です。
+
+1. [agent-native.com/templates](/templates) でテンプレートを選択してください
+2. ホストされたアプリ (例: mail.agent-native.com) としてすぐに使用します
+3. カスタマイズしたいときにフォークしてください — 「Stripe アカウントに接続する」、「コホート チャートを追加する」
+4. エージェントはニーズに合わせてコードを変更します
+5. フォークを独自のドメインにデプロイするか、agent-native.com に留まる
+
+これは共有インフラストラクチャではなく、自分のアプリであるため、エージェントは安全にコードを進化させることができます。アプリは使用するにつれて改善され続けます。全文については、[Templates](/docs/cloneable-saas) を参照してください。
+
+テンプレート全体をフォークする準備ができていませんか?すでに使用しているコーディング エージェントに **スキル** を追加して、エージェント ネイティブを試すこともできます。`npx @agent-native/core@latest skills add visual-plan` で計画スキルをインストールします。 [Skills Guide](/docs/skills-guide#app-backed-skills) を参照してください。
+
+## コンポーザブルエージェント {#composable-agents}
+
+エージェント ネイティブ アプリは相互に通信できます。メール アプリ内から、分析エージェントにタグを付けてデータをクエリし、その結果を下書きメールに含めることができます。エージェントは、他にどのようなエージェントが利用可能かを検出し、相互に仕事を引き継ぎ、結果をすでにいる UI に表示します。
+
+これは内部で [A2A](/docs/a2a-protocol) と [MCP](/docs/mcp-protocol) によって強化されています (同じ定義、複数のサーフェス)。しかしユーザーとして知っておくべきことは、「アプリでできることはすべて、アプリにヘルプを求めることができる」ということだけです。
+
+## これはコードではどのようになりますか? {#what-does-it-look-like-in-code}
+
+エージェント ネイティブ アプリを構築または拡張している場合、中心的なパターンは次のとおりです。アプリ内のすべての操作は **アクション** であり、一度定義されると、エージェントと UI の両方で使用できます。
+
+```an-annotated-code title="One action, defined once"
+{
+  "filename": "actions/reply-to-email.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Reply to an email thread\",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    // db and schema come from your app's server/db setup\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this as a tool." },
+    { "lines": "6", "label": "型付き契約", "note": "One zod `schema` validates input from **every** surface — agent, UI, HTTP, MCP, and A2A." },
+    { "lines": "7-10", "label": "One implementation", "note": "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this." }
+  ]
+}
+```
+
+```tsx
+// In any React component — same action, called from a button
+const { mutate } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+```tsx
+// And the agent panel mounted anywhere in your app
+import { AgentSidebar } from "@agent-native/core/client";
+
+<AgentSidebar />;
+```
+
+1 つのアクション、多くのサーフェス: エージェントはツールとして呼び出し、UI はタイプセーフなミューテーションとして呼び出し、[native chat](/docs/native-chat-ui) は明示的なウィジェット結果をレンダリングでき、外部エージェントは [A2A](/docs/a2a-protocol) 経由でそれに到達し、MCP ホストはアプリの [MCP server](/docs/mcp-protocol) 経由で呼び出し、オプションで MCP アプリ UI リソースと標準リモートを使用します。 MCP OAuth はフレームワークによって処理されます。完全なリファレンスについては、[Actions](/docs/actions) を参照してください。
+
+## 次は何ですか {#whats-next}
+
+- [**Getting Started**](/docs/getting-started) — start with one action, pick a template, or install a skill
+- [**Agent Surfaces**](/docs/agent-surfaces) — choose headless, rich chat, embedded sidecar, or full app
+- [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, context awareness, portability
+- [**Templates**](/docs/cloneable-saas) — templates as complete products you own
+- [**Workspace**](/docs/workspace) — the per-user customization layer (skills, memory, instructions, MCP) backed by SQL, not files
+- [**Dispatch**](/docs/dispatch) — the workspace control plane: secrets vault, Slack/email inbox, cross-app delegation
+- [**Extensions**](/docs/extensions) — sandboxed mini-apps the agent creates instantly without code changes
+- [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>` into any React app