@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/tracking.md

@@ -0,0 +1,236 @@
+---
+title: "추적 및 분석"
+description: "플러그형 제공자를 통한 서버 측 분석 — PostHog, Mixpanel, Amplitude 또는 사용자 정의 웹훅"
+---
+
+# 분석 추적
+
+하나의 기능, 여러 대상. 서버 측 코드(actions, 플러그인, 서버 경로)에서 `track()`를 호출하면 이벤트가 등록된 모든 분석 제공자에게 전달됩니다. SDK 종속성, 클라이언트 측 스크립트, 차단이 없습니다. 동일한 `track()`는 [browser/app code](#client)에서도 사용할 수 있으며 동일한 제공업체로 라우팅됩니다.
+
+이것은 _제품_ 분석입니다. 즉, 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}
+
+env var를 설정하면 공급자가 서버 시작 시 자동 등록됩니다. 코드 변경이 필요하지 않습니다.
+
+| 제공자     | 환경 변수                                                                              |
+| ---------- | -------------------------------------------------------------------------------------- |
+| 포스트호그 | `POSTHOG_API_KEY`(필수), `POSTHOG_HOST`(선택사항, 기본값은 `https://us.i.posthog.com`) |
+| 믹스패널   | `MIXPANEL_TOKEN`                                                                       |
+| 진폭       | `AMPLITUDE_API_KEY`                                                                    |
+| 웹훅       | `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`의 프레임워크 경로에 게시하고 **동일** 등록된 서버 측 공급자(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`는 ~16KB로 제한됩니다. 크기가 너무 크거나 형식이 잘못된 페이로드는 거부됩니다.
+
+이는 Agent Native의 자체 제품 분석을 지원하는 프레임워크의 내부 브라우저 원격 측정(`trackEvent()` / 자동 페이지뷰 - 아래 [Browser defaults](#browser-defaults) 참조)과 다릅니다. 구성된 제공업체에 도달해야 하는 앱 자체 분석 이벤트에 `track()`를 사용하세요.
+
+## 고급: 맞춤형 공급자 및 내부 {#advanced}
+
+대부분의 앱에는 `track()` / `identify()` 및 내장 공급자만 필요합니다. 사용자 지정 공급자 등록, `TrackingProvider` 인터페이스, 내부 일괄 처리 및 프레임워크의 자체 브라우저 원격 측정 등 나머지 표면은 다음과 같습니다.
+
+<details>
+<summary><strong>Provider-registry API, 인터페이스, 내부 및 브라우저 기본값</strong></summary>
+
+### `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 없음, 진폭 SDK 없음. 프레임워크를 가볍게 유지합니다.
+- **최선을 다한 전달** — 공급자 오류가 포착되어 기록됩니다. 실패한 분석 통합은 호출자와 충돌하거나 요청 처리를 차단하지 않습니다.
+- **글로벌 싱글톤** — 레지스트리는 `globalThis`에서 `Symbol.for` 키를 사용하므로 여러 ESM 그래프 인스턴스(개발 모드 Vite + Nitro, 심볼릭 링크)가 하나의 공급자 세트를 공유합니다.
+
+### 브라우저 기본값 {#browser-defaults}
+
+여기에는 프레임워크 기여자 및 고급 템플릿 작성자와 주로 관련된 프레임워크 자체의 내부 원격 측정이 포함됩니다.
+
+템플릿 루트는 시작 시 `configureTracking()`를 한 번 호출합니다. `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/ko-KR/using-your-agent.md

@@ -0,0 +1,71 @@
+---
+title: "에이전트 사용"
+description: "에이전트와 함께 작업하는 일상적인 루프: 에이전트는 사용자가 보고 있는 것을 보고, 지시하고, 삽입하고, UI-light로 이동하고, 함께 공동 편집합니다."
+---
+
+# 에이전트 사용
+
+에이전트 네이티브의 기본 아이디어는 에이전트와 UI가 **동등한 파트너**라는 것입니다. 그 이유는 [What Is Agent-Native?](/docs/what-is-agent-native)를 참조하세요. 이 섹션은 그 약속의 나머지 절반, 즉 앱 옆에 도킹된 에이전트와 실제로 작업하는 느낌에 관한 것입니다.
+
+간단한 통과선이 있습니다. 상담원은 귀하가 보고 있는 내용을 **보고** 원하는 방향으로 **지시**하고, 어디에든 **삽입**할 수 있으며, 더 적합할 때는 완전히 **UI-light**할 수 있으며, 동일한 문서를 동시에 **공동 편집**할 수 있습니다. 각각은 이 섹션의 페이지입니다.
+
+```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}
+
+대부분의 경우 채팅에 입력하여 상담원을 조종합니다. 이를 더 빠르게 만드는 두 가지 요소가 있습니다.
+
+**멘션.** 사용자 지정 에이전트, 연결된 에이전트 또는 `@`가 포함된 파일에 태그를 지정하여 대화에 가져옵니다. "`@analytics`가 지난 주 번호를 가져온 다음 요약 초안을 작성하도록 합니다." 멘션은 작성자를 떠나지 않고도 올바른 전문가에게 연락하거나 올바른 맥락을 첨부하는 방법입니다.
+
+**음성.** 작곡가에게 마이크가 있습니다. Builder의 호스팅된 텍스트 변환부터 자체 키 가져오기, 브라우저 대체에 이르기까지 다양한 제공업체 옵션을 사용하여 요청을 입력하는 대신 받아쓰기하세요.
+
+→ [**Agent Mentions**](/docs/agent-mentions) — `@`-사용자 정의 에이전트, 연결된 에이전트 및 채팅 파일을 언급합니다.
+→ [**Voice Input**](/docs/voice-input) — 채팅 작성기의 받아쓰기 및 전사 라우팅 방법.
+
+## 삽입 {#you-embed-it}
+
+에이전트는 탭하여 이동할 수 있는 별도의 앱이 아닙니다. 사이드바, 원시 패널 및 `sendToAgentChat()` 호출과 같은 소수의 React 구성 요소로 제공되며 모든 앱에 드롭됩니다. `<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/ko-KR/voice-input.md

@@ -0,0 +1,81 @@
+---
+title: "음성 입력"
+description: "에이전트 채팅 작성기의 음성 받아쓰기 — Builder Gemini, BYOK 제공자 및 브라우저 웹 음성 대체"
+---
+
+# 음성 입력
+
+모든 에이전트 기반 앱에는 채팅 작성기에 마이크가 있습니다. 클릭하고 말하면 단어가 프롬프트에 기록됩니다. 모바일에서 유용하고, 긴 프롬프트에 유용하며, 손이 다른 것에 있을 때 유용합니다.
+
+프레임워크는 이 모든 것을 자동으로 처리합니다. Builder에 연결된 사용자는 기본적으로 Builder에서 호스팅되는 Gemini Flash-Lite를 얻습니다. 그렇지 않으면 사용자가 자신의 공급자 키를 가져오거나 브라우저 음성 인식으로 돌아갈 수 있습니다.
+
+## 작동 방식 {#how-it-works}
+
+작곡가의 음성 버튼은 브라우저에서 오디오를 녹음한 다음 제공자를 선택합니다.
+
+1. **Builder Gemini Flash-Lite(Builder가 연결된 경우 기본값).** 브라우저는 Gemini Flash-Lite를 사용하여 Builder.io를 통해 프록시되는 `/_agent-native/transcribe-voice`에 오디오를 게시합니다. Google API 키가 필요하지 않습니다.
+2. **BYOK 클라우드 제공업체.** 사용자는 설정에서 Google Gemini, Groq Whisper 또는 OpenAI Whisper를 선택할 수 있습니다. 경로는 공유 배포 자격 증명보다 먼저 사용자 범위의 암호화된 비밀을 확인합니다.
+3. **브라우저 웹 음성 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/ko-KR/what-is-agent-native.md

@@ -0,0 +1,202 @@
+---
+title: "Agent-Native란 무엇인가요?"
+description: "대부분의 AI 앱이 절반만 구축된 것처럼 느껴지는 이유, 앱을 진정한 에이전트 기반으로 만드는 요소, 그리고 결과적으로 일상적인 경험이 어떤 모습인지."
+---
+
+# Agent-Native란 무엇인가요?
+
+에이전트 네이티브는 AI 에이전트와 그 주변의 제품 표면이 **동등한 파트너**인 소프트웨어를 구축하는 방법입니다. 해당 표면은 하나의 사용자 지정 작업, 풍부한 채팅 또는 전체 UI를 갖춘 헤드리스 에이전트일 수 있습니다. 중요한 부분은 에이전트와 인간이 동일한 actions, 데이터베이스 및 상태를 공유한다는 것입니다.
+
+이 페이지에서 한 가지만 기억한다면 다음을 기억하세요. 오늘날 대부분의 AI 앱은 유용성에 한 발짝도 미치지 못하며, 그 격차가 현재 이 분야의 가장 큰 실수입니다.
+
+## 사용자의 모습 {#what-it-looks-like}
+
+백그라운드 작업자, 받은 편지함, 달력, 양식 작성기 또는 분석 대시보드를 상상해 보세요. 아직 사용자 정의 화면이 없는 경우도 있습니다. 즉, 하나의 작업 또는 하나의 헤드리스 앱 에이전트 프롬프트를 실행합니다. 때로는 첫 번째 화면이 채팅입니다. 원하는 것을 물어보면 상담원이 설정을 안내하고 표나 차트를 표시하고 올바른 앱 보기를 엽니다. 때로는 채팅이 전체 애플리케이션의 오른쪽에 고정되어 있는 경우도 있습니다. 이러한 도형 전체에서 다음을 수행할 수 있습니다.
+
+- **실제 작업부터 시작하세요.** CLI, HTTP, MCP, A2A, 앱 에이전트 루프 및 나중에 UI에서 하나의 지속 가능한 작업을 실행할 수 있습니다.
+- **UI가 있을 때 일반적으로 클릭하는 모든 항목을 클릭하세요.** 모든 버튼, 목록, 대시보드, 키보드 단축키 — 모두 상담원이 호출할 수 있는 것과 동일한 작업을 호출합니다.
+- **또는 그냥 물어보세요.** "Sara가 보낸 이메일에 3시까지 도착하겠다고 답장"을 상담원에게 입력하세요. 올바른 스레드를 열고 답글 초안을 작성한 후 승인을 위해 표시합니다. 마치 직접 작업한 것처럼 말입니다.
+- **무엇이 보이는지 확인하세요.** 이메일을 열면 상담원이 어떤 이메일인지 알 수 있습니다. 차트를 선택하면 상담원이 어떤 차트인지 알 수 있습니다. 단락을 강조표시하고 Cmd+I를 누르면 상담원이 해당 단락에 대해서만 작업을 수행합니다.
+- **작동하는 모습을 지켜보세요.** 상담원이 보기 열기, 초안 편집, 보고서 실행 등의 작업을 수행할 때 UI가 실시간으로 업데이트됩니다. 언제든지 마우스로 중지하거나 방향을 바꾸거나 인계받을 수 있습니다.
+- **팀원처럼 조종하세요.** 피드백을 주고, 다른 작업을 대기열에 추가하고, 지침을 편집하고, 어제 수행한 작업을 감사하세요. 기억하고 시간이 지나면서 워크플로가 더 좋아집니다.
+
+이것이 바로 Agent-Native 경험을 위해 설계된 것입니다. 대부분의 제품이 거기에 도달하지 못하는 이유는 다음과 같습니다.
+
+## 대부분의 "AI 앱"이 부족한 이유(사다리 원리) {#the-ladder}
+
+대부분의 팀은 사다리처럼 올라가는 진행 과정이 있으며 대부분은 한 단계를 너무 일찍 멈춥니다.
+
+### Rung 1 — 단일 LLM 호출(안티패턴) {#rung-one}
+
+텍스트 상자가 프롬프트를 보내고 AI가 문자열을 반환하면 이를 표시합니다. 아마도 스피너를 사용했을 수도 있습니다. 사용자가 경로를 수정할 방법도 없고, AI가 조치를 취할 방법도 없으며, 무슨 일이 일어났는지, 왜 발생했는지 확인할 방법도 없습니다.
+
+SaaS 제품에 기본적으로 부착된 "요약" 버튼인 "AI 기능"은 어디에서나 볼 수 있습니다. 데모에서는 인상적으로 보이지만 현실이 지저분해지는 순간 깨집니다. 그것은 제품이 아닙니다. 그거 장난감이에요.
+
+### Rung 2 — 도구와의 채팅 {#rung-two}
+
+이제 AI는 _일을 할 수 있습니다_. 여기에는 "이메일 초안", "연락처 검색", "쿼리 실행" 등의 도구와 도구 호출 및 결과를 실시간으로 보여주는 채팅 인터페이스가 있습니다. Claude, ChatGPT 및 커서의 내부 모습은 다음과 같습니다.
+
+이것은 진정한 발전입니다. 하지만 그 자체로는 여전히 채팅 창입니다. 적절한 UI가 없습니다. 대시보드도, 목록도, 양식도, 키보드 단축키도, 팀 협업도 없습니다. AI가 혼란스러워하면 오른쪽 버튼을 클릭하는 것이 아니라 다시 입력해야 합니다. 개발자가 아닌 사람들은 이 형식으로 실제 작업을 완료하는 데 어려움을 겪습니다.
+
+### Rung 3 — 에이전트 + UI를 동등한 파트너로 {#rung-three}
+
+이것은 에이전트 기반입니다. 에이전트 주변에 모든 기능을 갖춘 실제 앱을 추가합니다. 그리고 결정적으로 에이전트가 수행할 수 있는 모든 작업은 UI의 버튼이기도 하며 사용자가 클릭하는 모든 버튼은 에이전트가 사용하는 것과 동일한 논리를 실행합니다. 하나의 구현, 두 가지 방법.
+
+3단계에 도달하면 세 가지가 변경됩니다:
+
+- **챗봇에 버튼 추가를 중단했습니다. 앱에 에이전트를 추가했습니다.** 이는 양쪽 모두에서 훨씬 더 높은 품질의 제품입니다.
+- **에이전트는 실제 상황을 가지고 있습니다.** 귀하가 보고 있는 것, 선택한 것, 방금 한 일을 봅니다. UI가 읽는 것과 동일한 데이터베이스에 쓰기 때문에 작업 내용이 즉시 표시됩니다.
+- **외부 에이전트도 사용할 수 있습니다.** 다른 에이전트 기반 앱은 [A2A protocol](/docs/a2a-protocol)를 통해 이 앱의 actions를 호출할 수 있습니다. Claude 코드, Codex, ChatGPT 맞춤형 MCP 앱, 커서 및 기타 MCP 호스트는 [MCP server](/docs/mcp-protocol)로 구동할 수 있습니다. 하나의 앱, 많은 진입점.
+
+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가 있는 애플리케이션 내부에 속합니다**." 에이전트가 제품을 *is*하는 앱이라도 인간이 제품을 감독, 구성 및 조종하려면 여전히 UI가 필요합니다. [Agent Surfaces — Headless](/docs/agent-surfaces#headless)를 참조하세요.
+
+## 에이전트 + UI 패리티 {#agent-ui-parity}
+
+이것이 정의 원칙입니다.
+
+> **UI에서** — 버튼을 클릭하고, 양식을 채우고, 보기를 탐색합니다. UI는 데이터베이스에 씁니다. 상담원은 결과를 봅니다.
+>
+> **에이전트에서** — 자연어, A2A, Slack, Telegram을 통한 기타 에이전트. 에이전트는 데이터베이스에 씁니다. 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 세계"는 없으며 하나의 시스템입니다. 이 작업을 수행하는 아키텍처는 [Key Concepts](/docs/key-concepts)를 참조하세요.
+
+## 일반적으로 전동 공구를 위한 맞춤화 {#workspace-customization}
+
+Claude 코드와 같은 도구가 강력하다고 느끼는 이유는 모델이 아니라 **사용자 정의 레이어**입니다: 프로젝트별 지침, skills, 메모리, 하위 에이전트, 연결된 서비스. 귀하의 코드베이스, 선호도, 팀에 맞게 에이전트를 구성할 수 있습니다.
+
+에이전트 네이티브는 앱을 종료하지 않고도 모든 사용자에게 동일한 사용자 정의 레이어를 제공합니다. 각 앱에는 사용자(또는 팀 구성원 누구나)가 다음을 수행할 수 있는 개인 **작업 공간**이 제공됩니다.
+
+- 모든 사람의 에이전트가 읽는 팀 전체 규칙 편집
+- 수정할 때 상담원이 자동으로 기본 설정을 기억하도록 합니다.
+- 재사용 가능한 방법 가이드를 `/slash` 명령으로 작성
+- 특정 작업을 위한 사용자 정의 하위 에이전트 유지(`@mentions`로 호출)
+- 크론에서 실행되도록 작업 예약(예: "매주 월요일 아침, 지난주 요약")
+- 사용자별 MCP 서버를 통해 외부 서비스(Gmail, Stripe, Slack, 내부 API) 연결
+
+트위스트: 파일 시스템이 아닌 데이터베이스에 모두 저장됩니다. 가동할 개발 환경도 없고 사용자당 컨테이너도 없습니다. 모든 사용자는 개인 메모리, 개인 연결, 개인 skills 등 자신만의 전체 작업 공간을 본질적으로 무료로 얻습니다. 왜냐하면 모든 것이 테이블의 행이기 때문입니다. 이것이 바로 실제 멀티 테넌트 SaaS 제품 내에서 Claude 코드 수준의 유연성을 실현할 수 있는 이유입니다.
+
+전체 개념은 [Workspace](/docs/workspace)를 참조하세요.
+
+## 다른 점 {#what-makes-it-different}
+
+| 접근                              | 설명                                                                                                                                                |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **AI가 탑재된 기존 앱**           | AI는 나중에 생각하는 것입니다. 앱에서 실제로 아무것도 할 수 없는 자동 완성, 요약 또는 채팅 사이드바로 제한됩니다.                                   |
+| **순수한 채팅/상담원 인터페이스** | 강력하지만 접근이 불가능합니다. 대시보드도 없고, 워크플로도 없고, 지속성도 없습니다. 개발자가 아닌 사람은 효과적으로 사용할 수 없습니다.            |
+| **SaaS용 Claude 코드 / Codex**    | 자신의 컴퓨터를 사용하는 개발자에게 적합합니다. 다중 테넌트 SaaS로 변환되지 않습니다. 개발 상자에서 사용자당 하나의 코드베이스는 확장되지 않습니다. |
+| **에이전트 기반 앱**              | 요원은 일류 시민입니다. 동일한 데이터베이스, 동일한 상태를 공유하며 UI가 할 수 있는 모든 작업을 수행할 수 있으며 그 반대의 경우도 마찬가지입니다.   |
+
+## 팀 전체 개발 {#whole-team-development}
+
+에이전트 네이티브는 개발자만을 위한 것이 아닙니다. 에이전트는 앱 자체 코드를 편집할 수 있으므로 앱 개발은 더 이상 개발자만의 활동이 아닙니다.
+
+- **디자이너**는 에이전트를 통해 실행 중인 앱에서 직접 디자인을 업데이트합니다.
+- **제품 관리자**는 설명을 통해 기능 및 업데이트 흐름을 추가합니다.
+- **QA**는 앱을 테스트하고 에이전트에게 손상된 부분을 수정하도록 요청합니다.
+- **팀원 누구나** 자연어를 통해 기여
+
+비전: 핸드오프 횟수를 줄이고 한 사람이 소규모 팀의 작업을 수행합니다.
+
+## 포크 및 맞춤설정 {#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`로 Plans 스킬을 설치하세요. [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 />;
+```
+
+하나의 작업, 다양한 표면: 에이전트는 이를 도구로 호출하고, UI는 이를 유형 안전 변형으로 호출하고, [native chat](/docs/native-chat-ui)는 명시적인 위젯 결과를 렌더링할 수 있고, 외부 에이전트는 [A2A](/docs/a2a-protocol)를 통해 도달하고, MCP 호스트는 선택적으로 MCP 앱 UI 리소스 및 표준 원격 MCP를 사용하여 앱의 [MCP server](/docs/mcp-protocol)를 통해 호출합니다. OAuth는 프레임워크에서 처리됩니다. 전체 참조는 [Actions](/docs/actions)를 참조하세요.
+
+## 다음 단계 {#whats-next}
+
+- [**Getting Started**](/docs/getting-started) — 하나의 작업으로 시작하거나, 템플릿을 선택하거나, 스킬을 설치하세요.
+- [**Agent Surfaces**](/docs/agent-surfaces) — 헤드리스, 풍부한 채팅, 내장형 사이드카 또는 전체 앱 선택
+- [**Key Concepts**](/docs/key-concepts) — 아키텍처: SQL, actions, 폴링 동기화, 상황 인식, 이식성
+- [**Templates**](/docs/cloneable-saas) — 귀하가 소유한 완전한 제품으로서의 템플릿
+- [**Workspace**](/docs/workspace) — 파일이 아닌 SQL가 지원하는 사용자별 사용자 정의 레이어(skills, 메모리, 지침, MCP)
+- [**Dispatch**](/docs/dispatch) — 작업 공간 제어 플레인: 비밀 저장소, Slack/이메일 받은 편지함, 앱 간 위임
+- [**Extensions**](/docs/extensions) — 코드 변경 없이 에이전트가 즉시 생성하는 샌드박스 미니 앱
+- [**Drop-in Agent**](/docs/drop-in-agent) — `<AgentPanel>`를 React 앱에 마운트