@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/agent-teams.md

@@ -0,0 +1,171 @@
+---
+title: "대리인 팀"
+description: "주 에이전트 위임은 자체 스레드에서 실행되고 채팅에 실시간 미리보기 칩 인라인으로 표시되는 하위 에이전트와 작업합니다."
+---
+
+# 대리인 팀
+
+에이전트 채팅은 단일체가 아닌 **조정자**입니다. 기본 에이전트가 전문가가 담당하는 것이 더 나은 작업("내 목소리로 이 이메일 작성", "BigQuery 분석 실행", "이 PR 검토")을 수행하면 자체 스레드, 도구, 컨텍스트에서 하위 에이전트가 생성됩니다. 하위 에이전트는 기본 채팅에 실시간 미리보기 **칩** 인라인으로 표시됩니다. 전체 대화를 탭으로 열려면 클릭하세요.
+
+이렇게 하면 기본 스레드에 집중하고 하위 에이전트를 병렬로 실행할 수 있으며 위임된 모든 작업에 대한 명확한 감사 추적을 제공합니다.
+
+Agent Teams는 핵심 실행 관리자에서 실행됩니다. 이벤트 스트리밍 및 지속, 중단은 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}
+
+작업이 수행될 때 생성:
+
+- 다른 **시스템 프롬프트**(전문 음성 또는 톤, 예: "코드 검토")가 필요합니다.
+- 주 컨텍스트를 오염시키는 **장기 실행** 도구 체인이 있습니다.
+- 주 에이전트가 수행하는 다른 작업과 **동시** 실행할 수 있습니다.
+- 이미 맞춤 상담원 프로필이 있는 **다른 팀**이 소유하고 있습니다.
+
+사소한 일회성 작업을 위해 생성하지 말고 직접 액션을 호출하세요.
+
+## 하위 에이전트 호출 {#invoking}
+
+하위 에이전트를 시작하는 세 가지 방법(가벼운 것부터 가장 명확한 것까지):
+
+### 1. `@mention` 맞춤형 에이전트 {#mention}
+
+사용자가 채팅 작성기에 `@agent-name`를 입력합니다. 작업 영역 하위 에이전트 드롭다운이 나타납니다. 하나를 선택하면 칩이 삽입됩니다. 제출 시 주 에이전트는 해당 하위 에이전트에게 메시지를 위임합니다.
+
+사용자 정의 에이전트는 YAML 머리말이 포함된 Markdown 파일인 `agents/<slug>.md`의 작업 공간에 있습니다. 형식은 [Custom Agents](/docs/workspace#custom-agents)를 참조하세요.
+
+### 2. 주 대리인이 자동으로 위임 {#auto-delegate}
+
+프레임워크는 주 에이전트에게 `agent-teams` 도구를 제공합니다. 모델이 작업이 등록된 하위 에이전트 프로필에 적합하다고 판단하면 `action: "spawn"` 및 `agents/*.md`에서 프로필 이름을 지정하는 선택적 `agent` 매개 변수를 사용하여 도구를 호출합니다. 칩이 나타납니다. 하위 에이전트가 실행됩니다. 기본 에이전트는 대기(또는 병렬로 이동)하고 하위 에이전트가 완료되면 결과를 통합합니다.
+
+전체 `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}
+
+하위 에이전트는 사용자 지정 에이전트 프로필(`@mention` 드롭다운에 표시되고 위임 대상 역할을 하는 작업 공간의 `agents/<slug>.md`에 있는 Markdown 파일)에 매핑됩니다. [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) — when the "sub-agent" lives in a different app entirely
+- [**Actions**](/docs/actions) — 하위 에이전트가 호출하는 도구

package/docs/content/locales/ko-KR/agent-web-surfaces.md

@@ -0,0 +1,161 @@
+---
+title: "공무원 웹"
+description: "공개 경로를 에이전트(robots.txt, llms.txt, 마크다운 미러, JSON-LD 및 공개 MCP 표면)가 크롤링, 읽기, 인용 및 선택적으로 호출할 수 있도록 만듭니다."
+---
+
+# 공무원 웹
+
+공개 에이전트 웹을 사용하면 에이전트가 공개 Agent-Native 경로를 쉽게 크롤링하고, 읽고, 인용하고, 호출할 수 있습니다. 목표는 모든 앱 엔드포인트를 공개하는 것이 아닙니다. 목표는 이미 공개된 페이지에 대해 깨끗한 공개 표면을 게시하는 동시에 개인 데이터 및 도구 액세스를 명시적인 제어로 유지하는 것입니다.
+
+문서 사이트는 참조 구현입니다. 오늘 배송됩니다:
+
+- 검색을 허용하지만 기본적으로 학습을 허용하지 않는 크롤러 정책이 있는 `/robots.txt`.
+- 소스 파일이 노출될 때 절대 표준 URL 및 `lastmod`가 포함된 `/sitemap.xml`.
+- 상담원 친화적인 콘텐츠 검색을 위한 `/llms.txt` 및 `/llms-full.txt`.
+- `/docs/getting-started.md`와 같은 Markdown 미러.
+- 프로덕션 빌드 후 공개 문서 페이지에 대한 `Accept: text/markdown` 응답.
+- 기본 조직, 웹사이트 및 페이지 메타데이터용 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}
+
+기존 작업 공간 앱 구성 아래에 `agentWeb`를 추가합니다(앱의 `agent-native` 키 아래 `package.json` 또는 이에 상응하는 `workspace.agentWeb`, `agentWeb` 또는 `root.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}
+
+에이전트 웹 검색은 경로 액세스 모델을 따릅니다.
+
+- 공개 앱은 `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만 노출해야 하며 작업 및 인증 정책에서 명시적으로 허용하지 않는 한 결과적 제외 또는 actions를 작성해야 합니다.
+
+## 빌드타임 파일 {#build-time}
+
+`@agent-native/core/agent-web`의 프레임워크 유틸리티는 하나의 페이지 목록에서 공통 파일을 생성합니다.
+
+```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 블록이 발생하지 않습니다.
+
+필요한 공개 표면이 누락된 경우 감사는 0이 아닌 값으로 종료됩니다.
+
+## 다음 단계
+
+- [**Actions**](/docs/actions) — 공공 에이전트 프로토콜에 actions를 선택하는 방법
+- [**MCP Protocol**](/docs/mcp-protocol) — `publicMcp: true`가 활성화하는 MCP 표면
+- [**Deployment**](/docs/deployment) — 빌드 중에 이러한 정적 파일이 작성되는 위치

package/docs/content/locales/ko-KR/audit-log.md

@@ -0,0 +1,111 @@
+---
+title: "감사 로그"
+description: "누가, 언제, 어떤 앱 데이터를 변경했는지, 본인인지 에이전트인지에 대한 지속 가능한 추가 전용 기록으로 작업 연결에서 자동으로 캡처됩니다."
+---
+
+# 감사 로그
+
+모든 에이전트 기반 앱은 즉시 감사 로그를 얻습니다. **누가 어떤 앱 데이터를 언제, 어디서, 그리고 에이전트였을 때 실행**에 대한 내구성 있고 완전하며 액세스 범위가 지정된 추가 전용 기록입니다. 캡처는 작업 연결에서 자동으로 수행됩니다. 당신은 그것에 대한 코드를 작성하지 않습니다.
+
+에이전트가 사용자를 대신하여 데이터를 변경할 수 있기 때문에 여기에서 감사 로그가 대답하는 헤드라인 질문은 "이 기록을 편집한 사람"이 아니라 **"나 또는 에이전트였으며 어느 차례에 발생했나요?"**입니다. 프레임워크의 다른 시스템에서는 이에 답할 수 없습니다.
+
+## 감사 vs. 관찰 가능성 vs. 추적 {#which}
+
+세 가지 시스템은 세 가지 다른 이유로 "무슨 일이 일어났는지"를 기록합니다. 질문하고 있는 항목을 선택하세요.
+
+| 시스템                                   | 답변하는 질문                                      | 충실성                                     | 관객                          |
+| ---------------------------------------- | -------------------------------------------------- | ------------------------------------------ | ----------------------------- |
+| **감사 로그**(이 페이지)                 | "이 기록을 누가, 언제, 변경했습니까?"              | **완전하고 내구성이 있으며 범위가 지정됨** | 사용자, 관리자, 에이전트 자체 |
+| **[Observability](/docs/observability)** | "Why did the agent do that, and what did it cost?" | 샘플링된 범위 원격 측정                    | 개발자                        |
+| **[Tracking](/docs/tracking)**           | "사람들이 제품을 어떻게 사용하고 있나요?"          | 외부 SaaS에 대한 실행 후 잊어버리기        | 오후 / 성장                   |
+
+샘플링되거나 분석 제공업체에 전달된 감사 로그는 쓸모가 없습니다. 요점은 그것이 완전하고, 로컬이며, 쿼리 가능하다는 것입니다. So it's its own subsystem, not a mode of the other two.
+
+## 자동으로 캡처되는 내용 {#captured}
+
+When any **mutating** action runs (anything that isn't a read-only `GET`), the framework appends one row to `agent_audit_log` with:
+
+- **Action** — the action name (e.g. `delete-recording`).
+- **배우** — `agent`, `human` 또는 `system` 및 배우의 이메일 — **에이전트 통화의 경우에도** 채워지므로 "에이전트, alice@을 대신하여 작업, …"이 표시됩니다.
+- **연결 실행** — 호출(도구 호출)을 트리거한 에이전트 `threadId` / `turnId`이므로 돌연변이는 정확한 에이전트 차례까지 추적됩니다.
+- **Surface** — `tool` (agent), `frontend`, `http`, `cli`, `mcp`, or `a2a`.
+- **Outcome** — `success`, `error` (with an error code), or `denied` (blocked by a human-approval gate).
+- **Inputs** — the call arguments, with credential-shaped values [redacted](#privacy).
+- **대상 및 소유자** — [scope reads](#reading)에 사용되는 작업이 변경된 리소스입니다.
+
+No wiring needed — the capture hooks into `defineAction` transparently. 로그 범람을 방지하기 위해 읽기 전용 actions를 건너뛰고 몇 가지 빈도가 높은 프레임워크 actions(앱 상태 동기화, context-xray, 탐색)를 기본적으로 건너뜁니다.
+
+## 행동이 무엇을 변경했는지 선언 {#target}
+
+By default an event is scoped to the **actor** — you see your own changes and the agent's changes on your behalf. To make a change to a _shared_ resource also appear in the **owner's** trail, and to label events by resource, declare a `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}
+
+- **수정** — 입력 내용이 저장되기 전에 자격 증명 형태의 키와 값(토큰, 비밀, 비밀번호, 전달자 문자열)이 제거되고 크기가 너무 큰 페이로드가 잘립니다. 감사 로그는 결코 보조 비밀 저장소가 되지 않습니다. `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) — the ownership model audit reads reuse
+- [**Observability**](/docs/observability) — 에이전트 실행 원격 측정(다른 하나는 "무슨 일이 일어났는가")