@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,294 @@
+---
+title: "可観測性"
+description: "エージェント トレース、評価、フィードバック、A/B 実験、組み込みダッシュボードはすべて構成なしで実行できます。"
+---
+
+# エージェントの可観測性
+
+すべてのエージェント ネイティブ アプリは、すぐに利用できる可観測性を備えています。トレース、自動評価、ユーザー フィードバック、A/B テストは構成なしで機能します。すべてのデータはアプリ独自の SQL データベースに保存されます。
+
+このページでは、_エージェントの品質_ メトリクス (データベースに保存されているトレース、コスト、評価、フィードバック) について説明します。 _product_ 分析 (PostHog/Mixpanel/Amplitude に流れるアプリのイベント) については、[Tracking](/docs/tracking) を参照してください。
+
+## 「評価」/「可観測性」と呼ばれるものが 3 つあります。どれが必要ですか? {#which}
+
+これら 3 つのページは混同しやすいです。質問に応じて選択してください:
+
+| ページ                                                 | 質問の答え                                                       | 実行時                                            | 懸念                  |
+| ------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------- | --------------------- |
+| **可観測性評価** (このページ、_Evals_ タブ)            | 「実際の本番稼働の結果はどうでしたか?」                          | パッシブ、毎回の実行後 (LLM 判定者がサンプリング) | 品質                  |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)          | 「エージェントはこの固定入力に対して正しいことを行いますか?」    | アクティブ、決定論的、CI/デプロイ ゲート          | 品質                  |
+| **[Observational Memory](/docs/observational-memory)** | 「この長いスレッドは安くてウィンドウ内に留まっているのですか？」 | 長いスレッドでのバックグラウンド圧縮              | コスト / コンテキスト |
+
+可観測性と CI 評価ゲートは両方とも品質\_スコアを付けますが、反対の端からのものです。つまり、実際のトラフィックの受動的な事後スコアリングと、固定入力でのアクティブな合否チェックです。観察記憶は質とは無関係です。それはトークンのコストとコンテキスト ウィンドウのプレッシャーに関するものです。
+
+## 自動的にキャプチャされるもの {#captured}
+
+ユーザーがメッセージを送信すると、フレームワークは以下を自動的に記録します。
+
+- **トークンの使用法** — 入力、出力、キャッシュ読み取り、キャッシュ書き込み
+- **コスト** — トークン数とモデル価格から計算
+- **レイテンシ** — ツール呼び出しごとの合計継続時間と時間
+- **ツール呼び出し** — どの actions が呼び出されたか、成功/エラー ステータス、期間
+- **自動評価** — 実行ごとに 5 つの品質スコアが計算されます
+
+コードを変更する必要はありません。インストルメンテーションは透過的に `production-agent.ts` にフックします。
+
+```an-diagram title="Every run feeds the loop" summary="One agent run produces a trace, automated scores, and a feedback hook — all stored in the app's own SQL and surfaced on the dashboard. Experiments split traffic across config variants."
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">Agent run<br><small class=\"diagram-muted\">production-agent.ts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Captured automatically</span><small class=\"diagram-muted\">tokens &middot; cost &middot; latency &middot; tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Traces &amp; spans</div><div class=\"diagram-box\">Evals (5 scorers + LLM judge)</div><div class=\"diagram-box\">Feedback &amp; frustration index</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Dashboard<br><small class=\"diagram-muted\">scoped to the signed-in user</small></div></div>",
+  "css": ".obs-loop{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.obs-loop .diagram-col{display:flex;flex-direction:column;gap:8px}.obs-loop .diagram-arrow{font-size:22px;line-height:1}.obs-loop .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## ダッシュボード {#dashboard}
+
+単一のルートを持つ任意のテンプレートにダッシュボードを追加します。
+
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+すべてのデータのスコープはサインインしているユーザーに限定されます。現在、クロスユーザー管理ビューはありません。
+
+ダッシュボードには 5 つのタブがあります:
+
+| タブ               | それが示すもの                                                                      |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| **概要**           | 主要な指標 — 実行、コスト、レイテンシ、ツールの成功率、満足度、評価スコア           |
+| **会話**           | 個々のスパン (agent_run、llm_call、tool_call) へのドリルダウンを含むトレース リスト |
+| **評価**           | 基準別の自動評価スコア、時間の経過に伴う傾向                                        |
+| **実験**           | ステータスバッジ付きの A/B テストリスト、信頼区間付きのバリアント結果               |
+| **フィードバック** | 賛成/下流、カテゴリの内訳、フラストレーション スコア                                |
+
+## ユーザーからのフィードバック {#feedback}
+
+### 明示的なフィードバック
+
+チャット UI 内のすべてのエージェント メッセージで、親指アップ/ダウン ボタンがインラインでレンダリングされます。 「低評価」を選択すると、カテゴリのポップオーバーが開きます (不正確、役に立たない、間違ったツール、遅すぎる)。これは自動的に `AssistantChat.tsx` に配線されます。
+
+### 暗黙のフィードバック (フラストレーション指数)
+
+フレームワークは会話信号から不満指数 (0 ～ 100) を計算します。
+
+| 信号           | 重量 | 検出するもの                                     |
+| -------------- | ---- | ------------------------------------------------ |
+| 言い換え       | 30%  | ユーザーが同様のメッセージを繰り返す             |
+| 再試行パターン | 20%  | 「もう一度試してください」、「いいえ、違います」 |
+| 放棄           | 20%  | セッションは応答後すぐに終了します               |
+| 感情           | 15%  | 否定的な言語パターン                             |
+| 長さのトレンド | 15%  | メッセージの長さの短縮                           |
+
+スコアの解釈: 0 ～ 20 = 健康、20 ～ 40 = 摩擦、40 ～ 60 = 不満、60+ = セッションの中断。
+
+## 自動評価 {#evals}
+
+エージェントが実行されるたびに 5 つの決定的スコアラーが実行されます:
+
+| 基準                | 測定内容                                                          | スコア範囲 |
+| ------------------- | ----------------------------------------------------------------- | ---------- |
+| `tool_success_rate` | エラーなしのツール呼び出しの割合                                  | 0-1        |
+| `step_efficiency`   | ツールを使用した実行に対して過度の LLM 反復にペナルティを与えます | 0-1        |
+| `latency_score`     | 10 秒/ツールのベースラインに対して正規化                          | 0-1        |
+| `cost_efficiency`   | コストベースラインに対して正規化                                  | 0-1        |
+| `error_recovery`    | エージェントはツールエラーから回復しましたか?                     | 0 または 1 |
+
+### LLM 裁判官として (オプション)
+
+`evalSampleRate` を設定して、サンプリングされた LLM ベースの評価を有効にします。
+
+```ts
+import { putSetting } from "@agent-native/core/settings";
+
+await putSetting("observability-config", {
+  enabled: true,
+  evalSampleRate: 0.05, // 5% of runs
+});
+```
+
+カスタム基準では自然言語ルーブリックを使用します。
+
+```ts
+const criteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
+};
+```
+
+## A/B テスト {#experiments}
+
+さまざまなモデル、温度、またはエージェント構成をテストします:
+
+```ts
+// Create via API
+POST /_agent-native/observability/experiments
+{
+  "name": "model-a-vs-b",
+  "variants": [
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
+  ],
+  "metrics": ["cost", "latency", "satisfaction"]
+}
+
+// Start the experiment
+PUT /_agent-native/observability/experiments/:id
+{ "status": "running" }
+```
+
+`<your-model-id>` / `<other-model-id>` の代わりに、エンジンが受け入れる実際のモデル識別子を使用します (モデル名は頻繁に変更されます。現在の ID についてはプロバイダー/エンジンを確認してください)。エージェント ループはユーザーのバリアントを自動的に解決し、構成のオーバーライドを適用します。割り当てでは一貫したハッシュが使用されます。同じユーザーは常に同じバリアントを取得します。
+
+```an-diagram title="Consistent-hash variant assignment" summary="Each user hashes to a stable variant, the loop applies that variant's config override, and results roll up per variant with confidence intervals."
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">User id<br><small class=\"diagram-muted\">consistent hash</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill\">control &middot; 50%</span><small class=\"diagram-muted\">config override A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">config override B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Results per variant<br><small class=\"diagram-muted\">cost &middot; latency &middot; satisfaction</small></div></div>",
+  "css": ".exp{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.exp .diagram-col{display:flex;flex-direction:column;gap:8px}.exp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.exp .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 構成 {#config}
+
+すべての設定は `observability-config` キーに保存されます:
+
+```ts
+{
+  enabled: true,           // Master switch
+  capturePrompts: false,   // Store prompt content in traces
+  captureToolArgs: false,  // Store action input arguments
+  captureToolResults: false, // Store action results
+  evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
+  exporters: []            // OTLP export targets
+}
+```
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Content is **redacted by default** — only token counts, costs, and timing are stored. `capturePrompts`, `captureToolArgs`, and `captureToolResults` are opt-in; turn them on only when you need prompt/argument content for debugging."
+}
+```
+
+## API エンドポイント {#api}
+
+すべて `/_agent-native/observability/` で自動マウントされます:
+
+| メソッド | パス                       | 目的                           |
+| -------- | -------------------------- | ------------------------------ |
+| GET      | `/`                        | 概要統計                       |
+| GET      | `/traces`                  | トレース概要のリスト           |
+| GET      | `/traces/:runId`           | トレースの詳細 (概要 + スパン) |
+| GET      | `/traces/:runId/evals`     | 実行の評価                     |
+| POST     | `/feedback`                | フィードバックを送信           |
+| GET      | `/feedback`                | フィードバックの一覧表示       |
+| GET      | `/feedback/stats`          | フィードバックの集約           |
+| GET      | `/satisfaction`            | 満足度スコア                   |
+| GET      | `/evals/stats`             | 評価統計                       |
+| POST     | `/experiments`             | 実験を作成                     |
+| GET      | `/experiments`             | 実験のリスト                   |
+| GET      | `/experiments/:id`         | 実験の詳細を取得               |
+| PUT      | `/experiments/:id`         | 実験を更新                     |
+| POST     | `/experiments/:id/results` | 計算結果                       |
+| GET      | `/experiments/:id/results` | 結果を取得                     |
+
+すべてのエンドポイントは、`?since=N` (ms タイムスタンプ) および `?limit=N` クエリ パラメーターをサポートします。
+
+## 外部プラットフォームへのエクスポート {#export}
+
+Langfuse、Datadog、Grafana、または任意の OTel 互換バックエンドにトレースを送信します。
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer sk-..." },
+    },
+  ],
+});
+```
+
+フレームワークは、OpenTelemetry GenAI 仕様と互換性のある `gen_ai.*` セマンティック規約スパンを発行します。
+
+## OpenTelemetry スパン {#otel}
+
+上記の `exporters` 構成 (社内トレースを OTLP エンドポイントに送信する) とは別に、エージェント ループは、実行、モデル呼び出し、ツール呼び出しごとに **ライブ OpenTelemetry スパン** を出力することもできます。そのため、すでに OTel コレクターを実行しているホストは、残りの分散トレースと一緒にエージェント アクティビティを確認できます。
+
+このレイヤーは **オプションであり、デフォルトでは何も操作されません**:
+
+- `@opentelemetry/api` は **オプションの依存関係**です。インストールされていない場合、ヘルパーはサイレントな no-ops に低下します。エージェント ループには何もスローされません。
+- API パッケージが存在する場合でも、デフォルトの no-op トレーサが同梱されます。スパンは、**ホストが `TracerProvider`** (`@opentelemetry/sdk-node` などを介して) を登録した場合にのみ実際になります。このフレームワークは、意図的に重い SDK/エクスポーター パッケージに依存したり、プロバイダー自体を登録したりしません。インストルメンテーションは埋め込みアプリによってオプトインされます。
+
+したがって、OTel を配線していない場合のコストは、呼び出しごとにキャッシュされたプロパティを数回読み取ることになります。これを有効にするには、API パッケージと SDK をインストールし、他のノード サービスの場合と同じ方法でサーバー起動時にプロバイダーを登録します。
+
+エージェント ループは 3 種類のスパンを出力します。
+
+| スパン      | いつ                          | 属性                                                              |
+| ----------- | ----------------------------- | ----------------------------------------------------------------- |
+| `agent.run` | エージェントの実行ごとに 1 回 | `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model` |
+| `tool.call` | アクション呼び出しごとに 1 回 | `tool.name`、および成功/エラーステータス                          |
+| `llm.call`  | モデル呼び出しごと            | タイミング + OK/エラーステータス                                  |
+
+スパンは OK/ERROR ステータスで終了し、失敗した場合はエラー メッセージを記録します。ゼロ/センチネルの属性値はプルーニングされ、スパンがノイズで乱雑にならないようにします。この OTel レイヤーは、上記のダッシュボードを強化する社内の `agent_trace_spans` / `agent_trace_summaries` テーブルに純粋に追加されます。両方とも同じ実行イベントから生成されます。
+
+## エラー報告 (Sentry) {#sentry}
+
+DSN が設定されている場合、Nitro ルート ハンドラーをエスケープするサーバー側エラーは Sentry に報告されます。これがないと、SDK は黙って何も操作しないため、dev で環境変数を設定しないままにしても安全です。ブラウザーとサーバーのイベントは同じ Sentry プロジェクトに送信できます。所有権、ボリューム、クォータ、またはアラート ルーティングに関して運用を分離する必要がある場合にのみ、それらを別のプロジェクトに分割してください。
+
+| 表面               | SDK               | 環境変数                                                           | メモ                                                                                 |
+| ------------------ | ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| ブラウザ / SPA     | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`、`SENTRY_CLIENT_DSN`、または `SENTRY_DSN` | クライアント内の未処理のエラーとルート変更のブレッドクラムをキャプチャします。       |
+| Nitro サーバー     | `@sentry/node`    | `SENTRY_SERVER_DSN` または `SENTRY_DSN`                            | 5xx 応答と Nitro ライフサイクル エラーをキャプチャします。リクエストごとのユーザー。 |
+| `agent-native` CLI | `@sentry/node`    | _ハードコード化_                                                   | 公開された CLI バイナリからのクラッシュ レポート。ユーザーは構成できません。         |
+
+### サーバー側の構成 {#sentry-config}
+
+デプロイ環境 (Netlify ダッシュボード、Cloudflare シークレットなど) で `SENTRY_SERVER_DSN` または共有 `SENTRY_DSN` を設定します。フレームワークは、次の Nitro プラグインを自動マウントします。
+
+1. 起動時に `Sentry.init` を 1 回呼び出します (べき等 - 複数のプラグインから呼び出しても安全です)。
+2. すべての API/フレームワーク リクエストで `getSession(event)` 経由でユーザーを解決し、`id` / `email` / `username` と `orgId` タグを Sentry のリクエストごとの分離スコープに添付します。追加の DB ヒットを避けるために、静的アセット パスはスキップされます。
+3. 検索可能な `route`、`method`、および `userAgent` タグを使用して、すべてのフレームワーク ルート 5xx をキャプチャします。
+
+オプションのノブ:
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE` (浮動小数点 `0`–`1`) — パフォーマンス トレースをオプトインします。デフォルトは `0` (エラーのみ) です。無効な値は `0` に固定されます。
+- `AGENT_NATIVE_RELEASE` — `release` タグをオーバーライドします。デフォルトは `agent-native-server@<core-version>` です。
+
+### テンプレート
+
+すべてのテンプレートはこれを自動的に継承します。インポートするものは何もありません。 SSR アプリの場合、実行時に `SENTRY_CLIENT_DSN`、`VITE_SENTRY_CLIENT_DSN`、または共有 `SENTRY_DSN` が利用可能な場合、サーバーは小さなブラウザー構成スクリプトを挿入するため、ブラウザーのキャプチャは Vite ビルド時環境に限定されません。カスタム動作（追加のタグ、テンプレートごとに異なる DSN、ハード無効化された Sentry）が必要なテンプレートは、独自のプラグインを `server/plugins/sentry.ts` からエクスポートすることでオーバーライドできます。
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+CLI のハードコードされた DSN は意図的です。公開されたバイナリは、どの環境で実行されるかに関係なく、クラッシュする必要があります。サーバー モジュールは、エラーが Sentry に到達するかどうかをオペレータが決定する顧客環境内で実行されるため、DSN をハードコードすることはありません。
+
+### プライバシーと PII {#privacy}
+
+サーバーと CLI は両方とも、`sendDefaultPii: false` と以下を削除する `beforeSend` フックで初期化されます。
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address` (同意なしで自動収集)
+- `contexts.runtime_env` (プロセス環境スナップショット)
+- トップレベルの例外タイプが `ValidationError` であるイベント (バグではなく、予想されるユーザー入力の拒否として扱われます)。
+
+`setUser({ id, email, username })` 経由で明示的に設定された ID フィールドは保持されます。
+
+## 次は何ですか
+
+- [**Tracking**](/docs/tracking) — アプリ独自のイベントの製品分析 (PostHog、Mixpanel、Amplitude)
+- [**Actions**](/docs/actions) — トレース内のツール呼び出しとして表示される操作
+- [**Security**](/docs/security) — データのスコープと資格情報の処理

package/docs/content/locales/ja-JP/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "観察記憶"
+description: "バックグラウンドの 3 層圧縮 (最近の未加工→観察→反映) により、短い会話に影響を与えることなく、長いエージェント スレッドを安価に、プロンプト キャッシュの安定性を保ちます。"
+---
+
+# 観察記憶
+
+長時間実行されるエージェント スレッドは、すべてのメッセージ、すべてのツール呼び出し、すべての結果など、膨大なトランスクリプトを蓄積します。各ターンでその履歴全体をモデルに再生するとコストがかかり、最終的にはコンテキスト ウィンドウが開いてしまいます。 **Observational Memory (OM)** は、長いスレッドの古い部分を日付付きの階層化された概要に圧縮するため、モデルは何が起こったのかをトークン コストのほんの一部で把握しながら、最新のターンはそのまま残ります。
+
+OM は完全に自動であり、所有者限定です。 **短いスレッドは影響を受けません**: スレッドが最初の圧縮しきい値を超えるまで、OM は何も行われず、コンテキストはバイト単位で、それが無い場合と同じになります。
+
+## 3 つの層 {#tiers}
+
+OM は、最も蒸留されたスレッドから最新のスレッドまでの 3 つの層として長いスレッドを表します。
+
+| ティア                   | それは何ですか                                                                                                                      |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **反射**                 | 大きくなった観察記録を凝縮した最高レベル。長い弧の概要。                                                                            |
+| **観察結果**             | 一連の生のメッセージを、何が起こったかをコンパクトに記録した、高密度で日付の入ったエントリ。                                        |
+| **最近の生のメッセージ** | 最後の N ターンは **逐語** 維持され、折りたたまれることはありません。そのため、エージェントは常に最新のコンテキストを確認できます。 |
+
+```an-diagram title="Three tiers, distilled to recent" summary="The older prefix folds into dated observations and a long-arc reflection; only the most recent turns stay verbatim."
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Reflections</span><small class=\"diagram-muted\">long-arc summary, condensed from the observation log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observations</span><small class=\"diagram-muted\">dense, dated entries folding stretches of raw messages</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Recent raw messages</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — never folded</small></div></div>",
+  "css": ".om{display:flex;flex-direction:column-reverse;align-items:stretch;gap:8px}.om .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.om .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+各ターンで、読み取り側はこれらを単一の自己ラベル付き `[Observational Memory]` ブロックにアセンブルします。このブロックは生の古いプレフィックスを置き換え、最近の生のウィンドウをそのまま保持し、圧縮されたレコードを信頼できるものとして扱うようにモデルに指示します (完了した作業をやり直さず、記録された決定、名前、日付、ステータスを信頼します)。
+
+## 圧縮の実行方法 {#compaction}
+
+2 つのパスは、クリーン ターン後の **ファイア アンド フォーゲット、ベスト エフォート** ステップとして実行されるため、ユーザーに表示される応答に遅延が追加されることはなく、失敗は無視されます。
+
+1. **Observer** — スレッドの _unobserved_ メッセージが監視トークンのしきい値を超えると、それらのメッセージは 1 つの高密度の監視エントリに折りたたまれます。
+2. **リフレクター** — 永続化された観測ログ自体がリフレクション トークンのしきい値を超えると、観測結果がより高いレベルのリフレクションに凝縮されます。
+
+```an-diagram title="Two best-effort passes after a clean turn" summary="Each pass no-ops below its threshold, so running the compactor every turn is cheap. Failures are swallowed and never add latency."
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">Clean turn ends<br><small class=\"diagram-muted\">fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observer</span><small class=\"diagram-muted\">unobserved tokens &gt; 30k? &rarr; fold into one observation</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Reflector</span><small class=\"diagram-muted\">observation log &gt; 40k? &rarr; condense into a reflection</small></div></div>",
+  "css": ".om-pass{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.om-pass .diagram-node,.om-pass .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.om-pass .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+どちらもしきい値以下では no-op を通過するため、ターンごとにコンパクターを呼び出すのはコストがかかりません。 OM は揮発性の未処理のプレフィックスを安定した圧縮されたテキストに置き換えるため、長いスレッドのターンにわたってプロンプトを**キャッシュ安定**に保ちます。
+
+OM データは、アプリ独自の SQL データベースに存在し、所有者 (存在する場合は組織) にスコープ設定されます。これは、フレームワークの残りの部分と同じスコープ モデルです。ユーザー間で共有されることはありません。
+
+## 構成 {#config}
+
+デフォルトは保守的です。オペレーターは、`AGENT_NATIVE_OM_*` 環境変数を使用してデプロイ時に圧縮をダイヤルできます (アプリ コードの再デプロイは必要ありません)。無効な値または欠落している値は、常に名前付きのデフォルトに戻ります。
+
+| 環境変数                                      | デフォルト | それが制御するもの                                                                           |
+| --------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000`    | オブザーバーがメッセージを 1 つの観測にまとめるようにトリガーする未観測メッセージ トークン。 |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000`    | リフレクターが反射に凝縮するきっかけとなる観察ログ トークン。                                |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`       | 最新のメッセージのうち、そのままのメッセージがいくつあるか (観測値に組み込まれていない)。    |
+
+オブザーバーとリフレクターの出力上限 (4000 / 2000 トークン) は、それ自体による単一の圧縮パスが予算を超過するのを防ぎます。 `resolveObservationalMemoryConfig({ ... })` を介してコード内で調整できますが、環境公開はできません。
+
+> [!TIP]
+> しきい値を下げて、より早く圧縮します (長いスレッドが安くなり、要約が少し多くなります)。圧縮する前にコンテキスト内でより多くの生の履歴を保持するためにそれらを上げます。ワークフローでより長い逐語的末尾が必要な場合は、`AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` を高く設定します。
+
+## それが始まるとき {#when}
+
+OM は、少なくとも 1 つの観測または反映が生成されるのに十分な期間、スレッドの動作を変更するだけです。具体的には:
+
+- 真新しい、または短いスレッド: OM エントリがまだありません → コンテキストは変更されていない単純なトランスクリプトです。
+- 監視しきい値を超えた長いスレッド: 古いプレフィックスは圧縮された `[Observational Memory]` ブロックに置き換えられ、最近の未加工の末尾はそのまま残り、トークンの使用量は大幅に減少します。
+
+注入はベストエフォートかつ境界安全です。安全なトリム ポイントが見つからない場合 (保留中のツール使用/結果のペアがウィンドウの端にある場合など)、OM は保留中のツール結果をドロップするリスクを冒すのではなく、トリミングせずにメモリ ブロックを*追加的に*注入します。
+
+## 関連
+
+- [**Using Your Agent**](/docs/using-your-agent) — アプリの隣にドッキングされているエージェントを操作する日常的なループ。
+- [**Observability**](/docs/observability) — OM の節約が示される、実行ごとのトークンとコストのメトリクス。
+- [**Custom Agents & Teams**](/docs/agent-teams) — 長時間のサブエージェント実行は、同じ圧縮の恩恵を受けます。

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

@@ -0,0 +1,216 @@
+---
+title: "オンボーディングと API キー"
+description: "初回実行構成のセットアップ チェックリスト — API キー、OAuth、プロバイダー接続"
+---
+
+# オンボーディング
+
+エージェント ネイティブ フレームワークに基づいて構築されたアプリを初めて開くと、
+**セットアップ** チェックリスト。初回実行時の設定を近い状態に保ちます
+エージェント チャットに: AI エンジンを接続し、オプションでアプリを共有に向けます
+インフラストラクチャを構築し、必要な場合にのみプロバイダを追加します。
+
+```an-diagram title="The setup checklist" summary="Only Connect an AI engine is required. The panel tracks completion and auto-hides once everything required is done."
+{
+  "html": "<div class=\"ob\"><div class=\"diagram-card\"><span class=\"diagram-pill warn\">required</span><strong>Connect an AI engine</strong><small class=\"diagram-muted\">Connect Builder (one click) or paste an LLM key</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Database</strong><small class=\"diagram-muted\">set <code>DATABASE_URL</code></small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Authentication</strong><small class=\"diagram-muted\">OAuth / access token</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Email delivery</strong><small class=\"diagram-muted\">Resend / SendGrid</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">all required done &rarr; panel auto-hides</div></div>",
+  "css": ".ob{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.ob .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 14px}.ob .diagram-arrow{font-size:22px}"
+}
+```
+
+## エンドユーザー向け
+
+### 何が表示されるか
+
+- エージェント チャットの上にある **[セットアップ**] パネルに、「AI を接続する」などのチェックリストが表示されます
+  エンジン」、「電子メール配信」など
+- 上部のカウンター (例: 「1/4」) は、準備ができているステップの数を示します。
+- 現在のステップが展開されます。完了したステップには緑色のチェックが表示され、そのままになります
+  開くと読めます。
+- 必要な手順には、小さな赤い**必須**の錠剤が表示されます。パネルは表示されたままになります
+  必要な手順がすべて完了するまで
+- 必要な作業がすべて完了すると、パネルは自動的に非表示になります。
+- 右上の山型マークを使用してパネル全体を折りたたむことができます。または
+  下部の **設定を非表示** で完全に非表示になります。
+
+### 各ステップの完了方法
+
+ステップでは 1 つ以上の **メソッド** - 同じ条件を満たすためのさまざまな方法が提供されます
+要件。プライマリ パスが最初に表示されます。セカンダリ パスはコンパクトに保たれます
+ステップに複数の同等のプロバイダーがある場合、ピッカーまたは開示の背後。
+
+- **サービスに接続します (ワンクリック)** — 例: _管理対象の Builder_ に接続
+  AI ゲートウェイ。ボタンをクリックするとウィンドウが開き、サインインするとウィンドウが閉じます。
+  そしてステップは完了としてマークされます。コピーするキーはありません。
+- **API キーを貼り付けるか、フォームに記入します** — 例: LLM プロバイダー、データベースを選択してください。
+  OAuth プロバイダー、または電子メール プロバイダー、値を貼り付け、**保存** をクリックします。
+  秘密フィールドではパスワード入力が使用されるため、値は画面に表示されません。保存しました
+  値はローカルの `.env` (またはワークスペース設定) に入力されます — を参照
+  住んでいる場所の [Security](/docs/security)。
+- **リンクを開く** — 一部の手順では、サインイン ページまたはドキュメントが示されています。クリック
+  **続行**し、新しいタブでフローを終了します。
+- **エージェントに問い合わせる** — いくつかの手順で「エージェントにセットアップしてもらう」オプションが提供されます。
+  これをクリックすると、エージェントがチャットに応答し、必要な手順を案内します
+  外部セットアップ (OAuth 認証情報の作成など)。
+
+### 通常表示される組み込みのステップ
+
+- **AI エンジンを接続します** (必須) - 唯一の必須ステップです。接続
+  ワンクリック管理ゲートウェイの場合は Builder、またはセカンダリ プロバイダー キーを開きます
+  独自の LLM キーを選択して貼り付けます。
+- **データベース** (オプション) — 特定のデータベースを使用する場合は、`DATABASE_URL` を設定します。
+  SQL データベース接続文字列。
+- **認証** (オプション) — 組み込みの電子メール/パスワード アカウントは
+  デフォルト。これらのパスが必要な場合にのみ、OAuth またはアクセス トークン サインインを追加します。
+- **電子メール配信** (オプション) — 導入前のパスワード リセットに役立ちます。
+  チームへの招待、通知の共有。すでに使用しているプロバイダを使用します。
+  ローカル開発はこれなしでも実行できます。
+
+テンプレートは、これらに独自のステップを追加できます。 CRM テンプレートは
+「Connect Gmail」を追加すると、ドキュメント テンプレートに「デフォルトのワークスペースを選択」が追加される場合があります。参照
+サインイン設定の詳細については [Authentication](/docs/authentication)。
+
+### チェックリストに戻る
+
+[**設定を非表示**] をクリックすると、そのブラウザ セッションのパネルが消えます。
+まだ完了していない必要な手順は、次回のロード時に再び表示されます。 1 回
+必要な作業はすべて完了し、パネルは永久に自動的に非表示になります。何もありません
+やるべきことが残っています。
+
+## 開発者向け
+
+テンプレートを作成している場合は、オンボーディング ステップを登録して、
+ユーザーのサイドバーのチェックリスト。フレームワークはレンダリングと完了を処理します
+追跡と解雇 — あなたはそのステップが何であるか、そしてそれがどのようなものであるかを宣言するだけです
+満足です。
+
+システムは**自動マウント**されています。テンプレートを取得するために何も配線する必要はありません
+4 つの組み込みステップ (LLM、データベース、認証、電子メール)。アプリ固有の追加
+steps (Gmail, Slack, Notion, etc.), call `registerOnboardingStep()` from a
+サーバープラグイン。
+
+### 自動マウントされたルート
+
+すべてのルートは `/_agent-native/onboarding/` の下に存在します:
+
+| ルート                                              | 目的                                    |
+| --------------------------------------------------- | --------------------------------------- |
+| `GET /_agent-native/onboarding/steps`               | 完了ステータスを含むステップのリスト    |
+| `POST /_agent-native/onboarding/steps/:id/complete` | ステップを完了としてマークする (上書き) |
+| `POST /_agent-native/onboarding/dismiss`            | オンボーディング バナーを閉じる         |
+| `POST /_agent-native/onboarding/reopen`             | 明確な解雇 (パネルの再表示)             |
+| `GET /_agent-native/onboarding/dismissed`           | 読み取り却下 + allComplete フラグ       |
+
+```an-api title="List onboarding steps"
+{
+  "method": "GET",
+  "path": "/_agent-native/onboarding/steps",
+  "summary": "List all registered steps with their completion status",
+  "description": "Drives the sidebar checklist — returns each step's id, title, methods, required flag, and whether `isComplete` currently passes.",
+  "responses": [
+    { "status": "200", "description": "Array of steps with completion status for the current user/app." }
+  ]
+}
+```
+
+### テンプレートからステップを追加する
+
+```an-annotated-code title="Registering a custom onboarding step"
+{
+  "filename": "server/plugins/my-onboarding.ts",
+  "language": "ts",
+  "code": "import { defineNitroPlugin } from \"@agent-native/core/server\";\nimport { registerOnboardingStep } from \"@agent-native/core/onboarding\";\nimport { listOAuthAccounts } from \"@agent-native/core/oauth-tokens\";\n\nexport default defineNitroPlugin(() => {\n  registerOnboardingStep({\n    id: \"gmail\",\n    order: 100,\n    title: \"Connect Gmail\",\n    description: \"Grant read/send access so the agent can work with email.\",\n    methods: [\n      {\n        id: \"oauth\",\n        kind: \"link\",\n        primary: true,\n        label: \"Sign in with Google\",\n        payload: { url: \"/_agent-native/google/auth-url?scope=mail\", external: false },\n      },\n      {\n        id: \"delegate\",\n        kind: \"agent-task\",\n        label: \"Let the agent set it up\",\n        badge: \"beta\",\n        payload: { prompt: \"Walk me through connecting Gmail. Set env vars as needed.\" },\n      },\n    ],\n    isComplete: async () => {\n      const accounts = await listOAuthAccounts(\"google\");\n      return accounts.length > 0;\n    },\n  });\n});",
+  "annotations": [
+    { "lines": "5", "label": "Auto-mounted", "note": "Register from a Nitro plugin — the framework handles rendering, completion tracking, and dismissal." },
+    { "lines": "7", "label": "Stable id", "note": "Re-registering with the same `id` after defaults load overrides a built-in step." },
+    { "lines": "12-19", "label": "Primary method", "note": "`primary: true` marks the big CTA. `kind: \"link\"` sends the user into the OAuth flow." },
+    { "lines": "20-26", "label": "Delegate path", "note": "`kind: \"agent-task\"` hands the setup to the agent chat with a prompt." },
+    { "lines": "28-31", "label": "Completion check", "note": "`isComplete` runs server-side. OAuth tokens live in the `oauth_tokens` store — check it, not `process.env.GMAIL_REFRESH_TOKEN`." }
+  ]
+}
+```
+
+### オンボーディングでのワークスペース接続の確認
+
+外部サービス (Slack、Google Workspace、GitHub、HubSpot など) と対話するテンプレートを構築する場合は、ワークスペースがすでに接続されており、そのプロバイダー接続がアプリケーションに許可されているかどうかを確認する必要があります。これにより、中央の管理された接続が存在する場合、ユーザーはローカル環境変数で資格情報 (API キーやリフレッシュ トークンなど) を複製する必要がなくなります。
+
+接続カタログ APIs を使用して、`isComplete` コールバックで接続の準備状況を確認できます。
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+// Inside registerOnboardingStep:
+isComplete: async () => {
+  // Check if a managed workspace connection exists and is ready
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+    appId: "mail",
+    templateUse: "mail",
+    provider: "gmail",
+  });
+  const connection = catalog.providers[0];
+
+  if (
+    connection?.readiness.status === "ready" &&
+    connection.workspaceConnection.grantState === "granted"
+  ) {
+    return true;
+  }
+
+  // Fall back to local environment variable check
+  return !!process.env.GMAIL_REFRESH_TOKEN;
+};
+```
+
+接続プロバイダーのカタログ メソッドの完全なリストについては、[Workspace Connections](/docs/workspace-connections) ドキュメントを参照してください。
+
+### メソッドの種類
+
+| 種類               | ペイロード                                            | 用途                                                                |
+| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------- |
+| `link`             | `{ url, external? }`                                  | ユーザーを OAuth フロー ページまたはドキュメント ページに送信します |
+| `form`             | `{ fields, writeScope? }`                             | 環境変数 (キー、シークレット、URL) を収集する                       |
+| `builder-cli-auth` | `{ scope: "llm" \| "browser" \| "image-generation" }` | Connect Builder (unlocks shared infra)                              |
+| `agent-task`       | `{ prompt }`                                          | 対応するエージェント チャットにプロンプトを送信します               |
+
+`primary: true` フラグは、メソッドをそのステップの大きな CTA としてマークします。
+セットアップ パスを表示する必要がある場合は、`badge: "soon"` と `disabled: true` を使用します
+利用可能になる前に
+
+### 組み込みステップ
+
+| ID         | 必須   | 説明                                                           |
+| ---------- | ------ | -------------------------------------------------------------- |
+| `llm`      | はい   | Builder 接続またはプロバイダー LLM キー                        |
+| `database` | いいえ | デフォルトのデータベースまたは任意の SQL `DATABASE_URL`        |
+| `auth`     | いいえ | 組み込みアカウント、オプションの OAuth またはアクセス トークン |
+| `email`    | いいえ | トランザクション電子メールの再送信または SendGrid              |
+
+これらはいずれも、その後に同じ `id` で再登録することで上書きできます。
+デフォルトでロードされます。
+
+### クライアントの使用状況
+
+パネルはすでに `<AgentPanel>` 内にあります。カスタム レイアウトを構築するには:
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```
+
+ステップ値が保存される場所とシークレットの処理方法の背景については、
+[Security](/docs/security)を参照。エンドユーザー メッセージングのタッチポイント (招待、
+パスワードのリセット）は、**電子メール配信** ステップに依存します。
+[Messaging](/docs/messaging).