@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ja-JP/agent-teams.md

@@ -0,0 +1,171 @@
+---
+title: "エージェント チーム"
+description: "メイン エージェントは、独自のスレッドで実行され、チャット内でインラインのライブ プレビュー チップとして表示されるサブエージェントに作業を委任します。"
+---
+
+# エージェント チーム
+
+エージェント チャットは **オーケストレーター** であり、モノリスではありません。メイン エージェントが、「このメールを私の声で書く」、「BigQuery 分析を実行する」、「この PR をレビューする」など、スペシャリストが担当する方が適切なタスクに到達すると、独自のスレッド、ツール、コンテキストでサブエージェントが生成されます。サブエージェントは、メイン チャットにインラインのライブ プレビュー **チップ**として表示されます。クリックすると、会話全体がタブとして開きます。
+
+これにより、メイン スレッドの焦点が維持され、サブエージェントが並行して実行できるようになり、委任された作業のクリーンな監査証跡が得られます。
+
+エージェント チームはコアの実行マネージャー上で実行されます。イベントはストリーミングおよび持続し、中止は SQL を通じて伝播し、タスクはサーバーレス コールド スタート後も存続します。
+
+## メンタルモデル {#mental-model}
+
+- **メイン チャット** — オーケストレーター。代表の皆さん、リクエストを読みます。重労働自体を行うことはほとんどありません。
+- **サブエージェント** — 独自のスレッド、独自のシステム プロンプト、独自のツール セットで実行されます。それぞれは、[workspace](/docs/workspace) の「カスタム エージェント」プロファイルにマッピングされます。
+- **チップ** — メイン チャットにインラインで表示される豊富なプレビュー カードで、サブエージェントの現在のステップ、ストリーミング出力、および最終的な概要が表示されます。デフォルトでは折りたたまれています。クリックすると会話全体が展開されます。
+- **双方向メッセージング** — メイン エージェントは実行中のサブエージェントにフォローアップを送信できます。サブエージェントは、曖昧な点に達した場合にメッセージを返すことができます。
+
+サブエージェントの状態は `application_state` SQL テーブル (`agent-task:<taskId>` の下) に保持されるため、タスクはサーバーレス コールド スタート後も存続し、複数のプロセスにわたって動作します。
+
+```an-diagram title="Orchestrator and specialists" summary="The main chat delegates to sub-agents that run in their own threads and report back as inline chips."
+{
+  "html": "<div class=\"at-orc\"><div class=\"diagram-card main\"><span class=\"diagram-pill accent\">Main chat</span><small class=\"diagram-muted\">orchestrator &mdash; reads your request, delegates</small></div><div class=\"at-fan\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"at-subs\"><div class=\"diagram-box\">Code review<br><small class=\"diagram-muted\">own thread &amp; prompt</small></div><div class=\"diagram-box\">BigQuery analysis<br><small class=\"diagram-muted\">own tools</small></div><div class=\"diagram-box\">Email in voice<br><small class=\"diagram-muted\">own context</small></div></div></div><div class=\"diagram-pill\">each appears inline as a live chip &#8635;</div></div>",
+  "css": ".at-orc{display:flex;flex-direction:column;align-items:center;gap:12px}.at-orc .diagram-card{padding:14px 18px;display:flex;flex-direction:column;gap:4px;align-items:center}.at-orc .at-fan{display:flex;flex-direction:column;align-items:center;gap:8px}.at-orc .diagram-arrow{font-size:22px}.at-orc .at-subs{display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.at-orc .diagram-box{text-align:center}"
+}
+```
+
+## サブエージェントをいつ生成するか {#when-to-spawn}
+
+タスクが発生した場合:
+
+- 別の **システム プロンプト** (専門家の音声またはトーン、例: 「コード レビュー」) が必要です。
+- メインコンテキストを汚染する**長時間実行**のツールチェーンが存在します。
+- メイン エージェントが実行している他の作業と**並行して**実行できます。
+- 既にカスタム エージェント プロファイルを持っている **別のチーム** によって所有されています。
+
+簡単な 1 回限りの作業のために生成しないでください。アクションを直接呼び出してください。
+
+## サブエージェントの呼び出し {#invoking}
+
+サブエージェントを開始する 3 つの方法 (最も明示的なものから順に):
+
+### 1. `@mention` カスタム エージェント {#mention}
+
+ユーザーがチャット コンポーザーに `@agent-name` と入力します。ワークスペースのサブエージェントのドロップダウンが表示されます。 1 つを選択するとチップが挿入されます。送信時に、メイン エージェントはメッセージをそのサブエージェントに委任します。
+
+カスタム エージェントは、`agents/<slug>.md` (YAML フロントマターを含む Markdown ファイル) のワークスペースに存在します。形式については、[Custom Agents](/docs/workspace#custom-agents) を参照してください。
+
+### 2.メインエージェントは自動的に委任します {#auto-delegate}
+
+フレームワークはメイン エージェントに `agent-teams` ツールを提供します。モデルは、タスクが登録されたサブエージェント プロファイルに適合すると判断すると、`action: "spawn"` とオプションの `agent` パラメーターを使用してツールを呼び出し、`agents/*.md` からプロファイルを指定します。チップが現れます。サブエージェントが実行されます。メイン エージェントは待機 (または並行して続行) し、サブエージェントが終了したときに結果を組み込みます。
+
+完全な `agent-teams` アクション セットは次のとおりです:
+
+| アクション    | 目的                                             |
+| ------------- | ------------------------------------------------ |
+| `spawn`       | 新しいサブエージェント タスクを開始する          |
+| `status`      | 実行中のサブエージェントの進行状況を確認する     |
+| `read-result` | 完成したサブエージェントの出力を取得する         |
+| `send`        | 実行中のサブエージェントにメッセージを送信します |
+| `list`        | 現在のユーザーのすべてのタスクを表示             |
+
+### 3.プログラムによるスポーン {#programmatic-spawn}
+
+フレームワークレベルの統合の場合は、`@agent-native/core/server` の `spawnTask()` を使用します。
+
+```ts
+import { spawnTask } from "@agent-native/core/server";
+
+const task = await spawnTask({
+  description: "Draft an outreach email to this lead",
+  instructions: "Match Steve's voice from memory/MEMORY.md.",
+  ownerEmail: user.email,
+  systemPrompt: mailAgentSystemPrompt,
+  actions: mailActions,
+  // Pass either apiKey or engine — engine takes precedence.
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional if engine is provided
+  parentSend: emit, // streaming sender for the parent chat response
+});
+```
+
+ほとんどのアプリ コードはこれを直接呼び出しません。フレームワークは、`@mentions` および `agent-teams` ツールの内部でこれを呼び出します。新しいエントリ ポイント (サブエージェントとして実行されるバックグラウンド ジョブを開始するボタンなど) を接続する場合にのみ、`spawnTask()` にアクセスしてください。
+
+## タスクのライフサイクル {#lifecycle}
+
+```an-diagram title="What spawnTask() does" summary="Each spawn creates a thread, persists state to SQL, and streams chip events through to completion."
+{
+  "html": "<div class=\"at-life\"><div class=\"diagram-box\"><code>spawnTask()</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">create thread</span><small class=\"diagram-muted\">new row in <code>chat_threads</code>, description as first message</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">persist state</span><small class=\"diagram-muted\"><code>agent-task:&lt;id&gt;</code> &rarr; <code>application_state</code>, status=running</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">stream</span><small class=\"diagram-muted\"><code>agent_task_started</code> &rarr; chip appears; <code>agent_task_step</code> &rarr; chip updates live</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">complete</span><small class=\"diagram-muted\">status=completed, write summary + preview, emit <code>agent_task_done</code></small></div></div>",
+  "css": ".at-life{display:flex;flex-direction:column;align-items:stretch;gap:6px;max-width:560px}.at-life .diagram-card{display:flex;flex-direction:column;gap:3px;padding:10px 14px}.at-life .diagram-box{align-self:flex-start}.at-life .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+親エージェントはいつでも、`sendToTask(taskId, message)` 経由でサブエージェントを再開してフォローアップできます。サブエージェントにエラーが発生した場合、`markTaskErrored(taskId, reason)` は失敗を記録し、ユーザーに表示します。
+
+双方向メッセージングは永続的です。実行中のサブエージェントに対する親のフォローアップは次のとおりです。
+タスクのライフサイクルを通じて配信されます。サブエージェントが
+現在のステップでは、キューに入れられたままにして安全な場所で適用される必要があります
+継続ポイント。サブエージェントは、説明が必要な場合にメッセージを返信することもできます
+目に見えないようにブロックする代わりに。
+
+## タスク状態の読み取り {#reading-state}
+
+サーバー コードまたは他の actions から:
+
+```ts
+import { getTask, listTasks } from "@agent-native/core/server";
+
+const task = await getTask(taskId); // single task
+const tasks = await listTasks(); // all tasks for the user (sorted newest first)
+```
+
+`AgentTask` キー フィールド:
+
+```ts
+interface AgentTask {
+  taskId: string;
+  threadId: string;
+  description: string;
+  status: "running" | "completed" | "errored";
+  preview: string; // short one-liner for the chip
+  summary: string; // full summary once completed
+  currentStep: string; // latest step label (updated while running)
+  createdAt: number;
+  // Additional fields: parentThreadId, name, updatedAt, startedAt,
+  // completedAt, runId, error
+}
+```
+
+## カスタム エージェント プロファイル {#profiles}
+
+サブエージェントはカスタム エージェント プロファイルにマップされます。ワークスペース内の `agents/<slug>.md` にある Markdown ファイルは、`@mention` ドロップダウンに表示され、委任ターゲットとして機能します。 [Workspace — Custom Agents](/docs/workspace#custom-agents) は完全なフォーマット (フロントマター、`tools`、`delegate-default`、モデル オーバーライド) を所有します。
+
+## 委任デプスガード {#depth-guard}
+
+サブエージェントはサブエージェントを生成する可能性がありますが、これは暴走/コストのリスクです。制限のない委任の連鎖が無限に広がる可能性があります。このフレームワークは、ツールレベルの保護とは独立して、**委任の深さのハードキャップ**をサーバー側で強制します。
+
+トップレベルのチャットは深さ `0` です。それが生成するサブエージェントの深さは `1` です。そのサブエージェントはもう一度出現する可能性があります (深さ `2`)。深さ `3` サブエージェントを作成するスポーンは **拒否**されます。デフォルトの上限は **2** です。
+
+```an-diagram title="Delegation depth guard (default cap 2)" summary="Each level may spawn one deeper until the cap; a spawn past it is refused server-side."
+{
+  "html": "<div class=\"at-depth\"><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 0</span><strong>Top-level chat</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 1</span><strong>Sub-agent</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card warn\"><span class=\"diagram-pill warn\">depth 2</span><strong>Sub-agent's sub-agent</strong><small class=\"diagram-muted\">at the cap &mdash; may NOT spawn</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">depth 3</span><strong>Refused</strong><small class=\"diagram-muted\">server-side error</small></div></div>",
+  "css": ".at-depth{display:flex;flex-direction:column;gap:8px}.at-depth .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.at-depth .rung-1,.at-depth .diagram-card:nth-child(2){margin-inline-start:24px}.at-depth .diagram-card:nth-child(3){margin-inline-start:48px}.at-depth .diagram-card:nth-child(4){margin-inline-start:72px}"
+}
+```
+
+強制はアンビエントです。各サブエージェントは、自身の深さを記録する `AsyncLocalStorage` 内で実行されるため、その実行から推移的に到達した `spawnTask` は、親の深さを読み取り、上限に達すると拒否します。たとえ `agent-teams` ツールが、それを持っているはずのないサブエージェントに渡されたとしてもです。この決定は、純粋で単体テスト可能な `evaluateSubagentDepth(parentDepth)` として公開されます。生成を拒否すると、明確なエラーが返されます: _「委任の深さの制限に達しました (最大 N)。別のサブエージェントを生成できません。」_
+
+### キャップの構成 {#depth-guard-config}
+
+`AGENT_NATIVE_MAX_SUBAGENT_DEPTH` を使用してデプロイ時にデフォルトをオーバーライドします。
+
+| 値           | 効果                                                                                                                                                      |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _(未設定)_   | `2` のデフォルトの上限。                                                                                                                                  |
+| `0`          | **サブエージェントは生成されません** - 最上位エージェントがすべての作業を行います。                                                                       |
+| `1`…`16`     | これだけのレベルの委任。                                                                                                                                  |
+| 無効 / `>16` | 非整数/負の/NaN 値は `2` にフォールバックします。 `16` より上のものはすべて `16` に固定されるため、タイプミスによってガードが無効になることはありません。 |
+
+```bash
+AGENT_NATIVE_MAX_SUBAGENT_DEPTH=1   # sub-agents allowed, but they can't sub-delegate
+```
+
+サブエージェントが上限以下の場合、フレームワークはランタイム コンテキストに行を挿入し、サブエージェントがどの程度の深さにいるのか、さらに委任できるかどうかを通知します。これにより、モデルは予算を適切に消費します。
+
+## 次は何ですか
+
+- [**Workspace — Custom Agents**](/docs/workspace#custom-agents) — プロファイル形式
+- [**A2A Protocol**](/docs/a2a-protocol) — 「サブエージェント」が完全に別のアプリ内に存在する場合
+- [**Actions**](/docs/actions) — サブエージェントが呼び出すツール

package/docs/content/locales/ja-JP/agent-web-surfaces.md

@@ -0,0 +1,161 @@
+---
+title: "公的エージェントのウェブ"
+description: "パブリック ルートを、エージェントによるクロール可能、読み取り可能、引用可能にし、必要に応じて呼び出し可能にします (robots.txt、llms.txt、マークダウン ミラー、JSON-LD、およびパブリック MCP サーフェス)。"
+---
+
+# 公的エージェントのウェブ
+
+パブリック エージェント Web により、エージェントがパブリック Agent-Native ルートを簡単にクロール、読み取り、引用、呼び出しできるようになります。目標は、すべてのアプリのエンドポイントを公開することではありません。目標は、明示的な制御の背後でプライベート データとツールへのアクセスを維持しながら、すでに公開されているページのクリーンな公開面を公開することです。
+
+ドキュメント サイトはリファレンス実装です。本日発送します:
+
+- デフォルトで取得は許可するがトレーニングを禁止するクローラー ポリシーを備えた `/robots.txt`。
+- ソース ファイルが公開する場合、絶対正規 URL および `lastmod` を含む `/sitemap.xml`。
+- エージェントフレンドリーなコンテンツ検出のための `/llms.txt` および `/llms-full.txt`。
+- Markdown ミラー (`/docs/getting-started.md` など)。
+- 実稼働ビルド後のパブリック ドキュメント ページに対する `Accept: text/markdown` 応答。
+- 基本組織、Web サイト、ページのメタデータ用の JSON-LD。
+- 上記のすべてをチェックする監査 CLI (`npx @agent-native/core@latest audit-agent-web`)。
+
+`publicMcp: true` を設定すると、オプトインされた actions がパブリック MCP エンドポイントとしてさらに公開され、外部エージェントがそれらを直接呼び出すことができるようになります ([MCP Protocol](/docs/mcp-protocol) を参照)。
+
+```an-diagram title="What a public route publishes" summary="A public route fans out into agent-friendly representations. Reading the route is separate from calling tools — tool access stays opt-in."
+{
+  "html": "<div class=\"diagram-web\"><div class=\"diagram-box\" data-rough>Public route<br><small class=\"diagram-muted\">derived from route access settings</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">robots.txt</span><span class=\"diagram-pill\">sitemap.xml</span><span class=\"diagram-pill\">llms.txt</span><span class=\"diagram-pill\">.md mirror</span><span class=\"diagram-pill\">JSON-LD</span><span class=\"diagram-pill\">text/markdown</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col gate\"><span class=\"diagram-pill warn\">Tools stay private</span><small class=\"diagram-muted\">publicMcp + publicAgent.expose required</small></div></div>",
+  "css": ".diagram-web{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-web .diagram-arrow{font-size:22px;line-height:1}.diagram-web .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}.diagram-web .gate{display:flex;flex-direction:column;gap:4px;align-items:flex-start}"
+}
+```
+
+## 構成 {#config}
+
+既存のワークスペース アプリ構成の下 (アプリの `agent-native` キーの下の `package.json`、または同等の `workspace.agentWeb`、`agentWeb`、または `root.agentWeb`) に `agentWeb` を追加します。パブリック ルート リストは依然としてアプリのルート アクセス設定から派生します。 `agentWeb` は、パブリック サーフェスがエージェントに対してどのように表示されるかを制御します。
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin/*"],
+      "agentWeb": {
+        "discoverable": true,
+        "markdownTwins": true,
+        "llmsTxt": true,
+        "jsonLd": true,
+        "publicAgentCard": true,
+        "publicMcp": false,
+        "crawlerPolicy": "discoverable-no-training",
+        "crawlers": {
+          "training": "disallow",
+          "search": "allow",
+          "userTriggered": "allow",
+          "codingAgents": "allow",
+          "autonomousAgents": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+ほとんどのアプリでは、デフォルトのままにしておきます。アプリにパブリック ルートがある場合、`discoverable` はデフォルトでオンになります。デフォルトのクローラ ポリシーは「検出可能ですがトレーニングは不可能」です。検索、ユーザー トリガーによる取得、コーディング エージェント、自律型ブラウジング エージェントが許可されます。トレーニング クローラーは許可されません。
+
+## 信頼できる情報源のルート {#route-source}
+
+エージェント Web ディスカバリはルート アクセス モデルに従います:
+
+- パブリック アプリは、`protectedPaths` を除くすべてのルートを公開します。
+- 内部アプリは `publicPaths` のみを公開します。
+- パブリック共有ページとフォーム ページはエージェントが読み取ることができます。
+- 近くのページが公開されているという理由だけで、送信されたプライベート データ、認証されたダッシュボード、ユーザー/組織の状態が含まれることはありません。
+
+これにより、混合アプリが自然に保たれます。フォーム アプリはパブリック フォーム ページを公開し、送信内容を非公開に保つことができます。コンテンツ アプリは、公開された投稿を公開し、エディターを非公開に保つことができます。ドキュメント サイトでは、管理ツール以外のすべてを公開できます。
+
+## 公開ページは公開ツールではありません {#public-tools}
+
+公開ページへのアクセスと公開ツールへのアクセスは別のものです。ルートがパブリックであるということは、エージェントがそのルートを HTML、Markdown、サイトマップ エントリ、llms エントリ、および構造化データとして読み取ることができることを意味するだけです。
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "**A public page is not a public tool.** Making a route crawlable never exposes an action. Tool access requires an explicit `publicAgent.expose` opt-in on the action *and* `publicMcp: true` on the app."
+}
+```
+
+パブリック エージェント プロトコルを通じてアクションを公開するには、アクションをオプトインする必要があります。
+
+```an-annotated-code title="Opting one safe action onto the public surface"
+{
+  "filename": "actions/search-docs.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Search published docs\",\n  readOnly: true,\n  publicAgent: {\n    expose: true,\n    readOnly: true,\n    requiresAuth: false,\n    isConsequential: false,\n    title: \"Search published docs\",\n  },\n  run: async (args) => {\n    // ...\n  },\n});",
+  "annotations": [
+    { "lines": "4", "label": "Explicit opt-in", "note": "Without `publicAgent.expose === true`, the action never appears on any public agent surface — no matter how public its routes are." },
+    { "lines": "5-7", "label": "Self-describe safety", "note": "Mark it read-only, declare whether it needs auth, and flag whether it is consequential. Public MCP excludes consequential/write actions unless policy explicitly allows them." }
+  ]
+}
+```
+
+`agentWeb.publicMcp` はデフォルトでは `false` のままです。パブリック MCP が有効な場合、サーバーは `publicAgent.expose === true` を持つ actions のみを公開する必要があり、アクションと認証ポリシーで明示的に許可されていない限り、引き続き consequential を除外するか、actions を書き込む必要があります。
+
+## ビルド時ファイル {#build-time}
+
+`@agent-native/core/agent-web` のフレームワーク ユーティリティは、1 つのページ リストから共通ファイルを生成します。
+
+```ts
+import {
+  buildAgentWebStaticFiles,
+  normalizeAgentWebConfig,
+} from "@agent-native/core/agent-web";
+
+const config = normalizeAgentWebConfig(
+  { crawlerPolicy: "discoverable-no-training" },
+  { hasPublicRoutes: true },
+);
+
+const files = buildAgentWebStaticFiles({
+  siteName: "My Agent-Native App",
+  siteUrl: "https://example.com",
+  description: "Public docs for my app.",
+  config,
+  pages: [
+    {
+      path: "/docs",
+      title: "Docs",
+      description: "Start here.",
+      markdown: "# Docs\n\nStart here.\n",
+      markdownPath: "/docs/getting-started.md",
+      lastmod: new Date(),
+    },
+  ],
+});
+```
+
+Vite アプリは、実稼働ビルド中に `@agent-native/core/vite` の `createAgentWebVitePlugin` を使用して、これらのファイルを `public`、`dist`、`dist/client`、`dist/server/public`、または `build/client` に書き込むことができます。
+
+## サイトを監査する {#audit}
+
+展開されたサイトまたはローカル実稼働サーバーに対して CLI 監査を使用します。
+
+```bash
+npx @agent-native/core@latest audit-agent-web --url https://www.agent-native.com
+```
+
+監査では以下がチェックされます:
+
+- SSR - 可視 HTML。
+- 正規の URL。
+- JSON-LD。
+- `robots.txt` ポリシーと絶対サイトマップ URL。
+- 絶対サイトマップ エントリ。
+- `/llms.txt` および `/llms-full.txt`。
+- Markdown ミラー。
+- `Accept: text/markdown`.
+- 共通エージェント取得ユーザー エージェントに対して偶発的な 401/403 ブロックが発生することはありません。
+
+必要なパブリック サーフェスが欠落している場合、監査はゼロ以外で終了します。
+
+## 次は何ですか
+
+- [**Actions**](/docs/actions) — actions をパブリック エージェント プロトコルにオプトインする方法
+- [**MCP Protocol**](/docs/mcp-protocol) — `publicMcp: true` が有効にする MCP サーフェス
+- [**Deployment**](/docs/deployment) — これらの静的ファイルがビルド中に書き込まれる場所

package/docs/content/locales/ja-JP/audit-log.md

@@ -0,0 +1,111 @@
+---
+title: "監査ログ"
+description: "誰がどのアプリ データをいつ変更したか、それがあなたかエージェントかどうかに関する永続的な追加専用の記録。アクションの継ぎ目で自動的にキャプチャされます。"
+---
+
+# 監査ログ
+
+すべてのエージェント ネイティブ アプリは、すぐに使用できる監査ログを取得します。これは、**誰がどのアプリ データを、いつ、どこから、いつ、どの実行で変更したかについての、耐久性があり、完全で、アクセス スコープが設定された追加専用の記録です。** キャプチャはアクション シームで自動的に行われます。コードを書く必要はありません。
+
+エージェントはユーザーに代わってデータを変更できるため、監査ログがここで答える見出しの質問は、単に「誰がこの記録を編集したか」ではなく、**「それは私ですか、それともエージェントですか、そしてどの順番でそれが引き起こされましたか?」** というものであり、フレームワーク内の他のシステムはこれに答えることができません。
+
+## 監査、可観測性、追跡 {#which}
+
+3 つのシステムが、3 つの異なる理由で「何が起こったか」を記録します。質問に応じて選択してください:
+
+| システム                                 | 質問の答え                                                                                         | 忠実度                                     | 観客                               |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------- |
+| **監査ログ** (このページ)                | 「誰が、いつ、この記録を変更したのはエージェントですか?」                                          | **完全、耐久性、範囲指定**                 | ユーザー、管理者、エージェント自体 |
+| **[Observability](/docs/observability)** | 「なぜエージェントはそのようなことをしたのですか?そしてそれにはどれくらいの費用がかかりましたか?」 | サンプリングされたスパン テレメトリ        | 開発者                             |
+| **[Tracking](/docs/tracking)**           | 「人々は製品をどのように使用していますか?」                                                        | 外部 SaaS へのファイア アンド フォーゲット | PM / 成長                          |
+
+サンプリングされた監査ログや分析プロバイダーに送信された監査ログは役に立ちません。重要なのは、監査ログが完全で、ローカルで、クエリ可能であるということです。したがって、これは他の 2 つのモードではなく、独自のサブシステムです。
+
+## 自動的にキャプチャされるもの {#captured}
+
+**変更** アクション (読み取り専用 `GET` ではないもの) が実行されると、フレームワークは以下を使用して `agent_audit_log` に 1 行を追加します。
+
+- **Action** — アクション名 (例: `delete-recording`)。
+- **俳優** — `agent`、`human`、または `system`、および俳優の電子メール — **エージェントの通話の場合でも**入力されるため、「alice@ の代理を務めるエージェント、…」が得られます。
+- **リンクの実行** — コール (ツール コール) をトリガーしたエージェント `threadId` / `turnId`。したがって、突然変異は正確なエージェント ターンまで遡ります。
+- **サーフェス** — `tool` (エージェント)、`frontend`、`http`、`cli`、`mcp`、または `a2a`。
+- **結果** — `success`、`error` (エラー コードあり)、または `denied` (人間の承認ゲートによってブロックされている)。
+- **入力** — 認証情報形式の値 [redacted](#privacy) を持つ呼び出し引数。
+- **ターゲットと所有者** — アクションによって変更されたリソース。[scope reads](#reading) に使用されます。
+
+配線は必要ありません。キャプチャは `defineAction` に透過的に接続されます。読み取り専用の actions はスキップされ、ログのあふれを避けるために、いくつかの高頻度フレームワーク actions (アプリ状態同期、コンテキスト Xray、ナビゲーション) がデフォルトでスキップされます。
+
+## アクションによって何が変わったかを宣言する {#target}
+
+デフォルトでは、イベントの範囲は **アクター** に限定されます。あなた自身の変更と、あなたに代わってエージェントの変更が表示されます。 **所有者**の証跡にも表示される*shared*リソースに変更を加え、リソースごとにイベントにラベルを付けるには、`target` を宣言します。
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({
+      type: "recording",
+      id: args.id,
+      // Optional — defaults to the actor. Set when editing someone else's resource.
+      ownerEmail: result?.ownerEmail,
+      visibility: "org",
+    }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => {
+    /* ...delete... */
+  },
+});
+```
+
+`audit` 内のすべてはオプションです。最小限の有用な追加は `target: () => ({ type, id })` です。
+
+### チューニングキャプチャ {#tuning}
+
+| オプション           | 効果                                                                                   |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `audit.target`       | イベントにリソースとスコープを使用してラベルを付け、その所有者に読み取ります。         |
+| `audit.summary`      | 人間が読める短いイベントの行。                                                         |
+| `audit.onRead`       | 機密性の高い**読み取り**を監査します（秘密のアクセス、一括エクスポート）。             |
+| `audit.enabled`      | `true` はキャプチャを強制します。 `false` はノイズの多い突然変異をオプトアウトします。 |
+| `audit.recordInputs` | `false` は、(すでに編集された) 引数のキャプチャをスキップします。                      |
+
+## 軌跡を読む {#reading}
+
+2 つの読み取り actions は、エージェント ** および ** すべてのアプリのフロントエンドで使用でき、呼び出し元に対して SQL にスコープされます。これらは別のテナントの行を返すことはありません。
+
+- **`list-audit-events`** — `targetType` / `targetId`、`actorKind` (`agent` | `human` | `system`)、`status`、`threadId` / `turnId`、`action`、でフィルターします。 `sinceMs`、`limit`。
+- **`get-audit-event`** — ID による 1 つのイベント (編集された入力ペイロードを含む)。
+
+`useActionQuery` を使用して UI から `list-audit-events` を呼び出して、アクティビティ フィードまたは「誰がこれを変更したか」行を作成します。監査テーブルへのフェッチを手動で書き込まないでください。
+
+```tsx
+import { useActionQuery } from "@agent-native/core/client";
+
+const { data } = useActionQuery("list-audit-events", {
+  targetType: "recording",
+  targetId: recordingId,
+});
+// data.events → [{ action, actorKind, actorEmail, turnId, status, summary, createdAt }, …]
+```
+
+エージェントは同じアクションを呼び出すことができます。「この録音で何を変更しましたか?」と尋ねます。そしてそれは道から答えます。
+
+## プライバシーと保持 {#privacy}
+
+- **Redaction** — 入力が保存される前に、資格情報の形式のキーと値 (トークン、シークレット、パスワード、ベアラー文字列) が削除され、サイズ超過のペイロードが切り捨てられます。監査ログがシークレットの二次ストアになることはありません。 `summary` テキストにも機密データが含まれないようにしてください。
+- **追加のみ** — 監査行の更新または削除アクションはありません。唯一の削除は保持パージであり、これによりログが監査証跡として信頼できるものになります。
+- **テナント分離** — 読み取りの範囲は呼び出し元の ID と組織に限定されます。アイデンティティがない場合、何も一致しません。
+
+環境経由で設定:
+
+- `AGENT_NATIVE_AUDIT_RETENTION_DAYS` — 行を保持する期間 (デフォルトは `365`; `0` = 永久に保持)。
+- `AGENT_NATIVE_AUDIT_ENABLED=false` — グローバルキルスイッチ。
+
+## 次は何ですか
+
+- [**Actions**](/docs/actions) — キャプチャが行われる `defineAction` シーム
+- [**Human-in-the-Loop Approvals**](/docs/human-approval) — ゲート付き actions、`denied` として記録
+- [**Security & Data Scoping**](/docs/security) — 所有権モデルの監査読み取り再利用
+- [**Observability**](/docs/observability) — エージェント実行テレメトリ (その他の「何が起こったのか」)