@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ko-KR/embedding-sdk.md

@@ -0,0 +1,597 @@
+---
+title: "SDK 삽입"
+description: "페이지 컨텍스트 및 호스트 명령을 사용하여 기존 SaaS 앱에 Agent-Native 사이드카를 삽입합니다."
+---
+
+# SDK 삽입
+
+기존 제품에 Agent-Native 내장: SaaS 앱을 유지하고 내구성을 추가
+에이전트 사이드카, 해당 에이전트가 사용자가 있는 페이지를 보고 작동하도록 합니다
+이미 사용 중입니다. 아직도 헤드리스 상담원과 리치 채팅 중 하나를 선택하고 계시다면
+내장형 사이드카 또는 전체 앱으로 시작
+[Agent Surfaces](/docs/agent-surfaces).
+
+```an-diagram title="The embedding membrane" summary="The host app supplies server-side auth and live page context; Agent-Native runs the durable sidecar and reaches the open tab through client actions and host commands."
+{
+  "html": "<div class=\"diagram-embed\"><div class=\"diagram-box\" data-rough><strong>Host SaaS app</strong><small class=\"diagram-muted\">your UI, your auth</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">getContext &rarr;</div><div class=\"diagram-pill\">&larr; client actions</div><div class=\"diagram-pill\">&larr; host commands</div></div><div class=\"diagram-panel center\" data-rough><strong>Agent-Native sidecar</strong><small class=\"diagram-muted\">durable chat · app state · extensions</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL<br><small class=\"diagram-muted\">framework tables</small></div></div>",
+  "css": ".diagram-embed{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-embed .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-embed .diagram-arrow{font-size:22px;line-height:1}.diagram-embed .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 여기서 시작하세요: 배터리 포함 플러그인 {#batteries-included}
+
+대부분의 SaaS 호스트의 경우 **전체 내장 런타임 사용** — 서버 플러그인
+`createAgentNativeEmbeddedPlugin` 및 `<AgentNativeEmbedded>` 클라이언트
+구성요소. 이는 권장 기본값입니다. 전체 프레임워크를 재사용합니다.
+(actions, SQL 지원 앱 상태, 확장 프로그램, 브라우저 세션 도구) 및 제공
+에이전트는 사용자가 이미 사용하고 있는 페이지를 보고 조작할 수 있는 능력입니다.
+
+호스트는 Agent-Native 서버 경로를 기존 앱에 마운트하고 해당 앱을 전달합니다.
+Agent-Native에 로그인한 사용자이며 UI 제품에서 React 사이드바를 렌더링합니다.
+Agent-Native는 호스트 배포, 호스트 세션 및 구성된
+자체 프레임워크 테이블을 관리하는 `DATABASE_URL`: 채팅 스레드, 설정,
+애플리케이션 상태, 확장 프로그램, 확장 데이터, 비밀, 브라우저 세션 및
+작업 경로.
+
+```bash
+pnpm add @agent-native/core
+```
+
+서버에서:
+
+```ts
+// server/plugins/agent-native.ts
+import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server";
+import { builderActions } from "../agent-native/actions";
+import { getBuilderSession } from "../auth";
+
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.DATABASE_URL,
+  auth: async (event) => {
+    const session = await getBuilderSession(event);
+    if (!session) return null;
+    return {
+      userId: session.user.id,
+      email: session.user.email,
+      name: session.user.name,
+      orgId: session.organization.id,
+      orgRole: session.organization.role,
+    };
+  },
+  actions: builderActions,
+  agentChat: {
+    appId: "builder",
+    systemPrompt:
+      "You are Builder's embedded agent. Use Builder actions for durable work.",
+  },
+});
+```
+
+클라이언트에서:
+
+```tsx
+import {
+  AgentNativeEmbedded,
+  defineClientAction,
+} from "@agent-native/core/client";
+
+export function BuilderAppShell({ children, content, editor }) {
+  return (
+    <AgentNativeEmbedded
+      defaultOpen
+      session={{
+        id: browserTabId(),
+        label: "Builder editor",
+      }}
+      getContext={() => ({
+        route: {
+          name: "builder-editor",
+          pathname: window.location.pathname,
+          params: { contentId: content.id },
+        },
+        resource: {
+          type: "content",
+          id: content.id,
+          name: content.name,
+        },
+        user: currentUser(),
+        organization: currentOrganization(),
+      })}
+      actions={[
+        defineClientAction({
+          name: "select-element",
+          description: "Select an element in the visual editor",
+          schema: {
+            type: "object",
+            properties: { elementId: { type: "string" } },
+            required: ["elementId"],
+          },
+          run: ({ elementId }) => editor.select(elementId),
+        }),
+      ]}
+      onRefresh={() => queryClient.invalidateQueries()}
+      onNavigate={(payload) =>
+        router.navigate((payload as { path: string }).path)
+      }
+      onRemount={() => setAppKey((key) => key + 1)}
+    >
+      {children}
+    </AgentNativeEmbedded>
+  );
+}
+```
+
+이 모드는 전체 프레임워크를 재사용하기 때문에 권장되는 기본값입니다. 백엔드 actions는 `/_agent-native/actions` 아래에 마운트되고, 에이전트는 UI와 동일한 actions를 호출할 수 있으며, 사용자가 만든 확장 프로그램은 SQL에 저장되고, `extensionData`는 내구성이 있고 사용자/조직 범위에 속하며, 브라우저 세션 도구를 사용하면 백엔드 에이전트가 현재 열려 있는 탭을 검사하거나 작동할 수 있습니다.
+
+호스트 인증은 서버 측입니다. 브라우저의 ID를 정보 소스로 전달하지 마세요. 호스트의 요청/세션 개체 또는 단기 서버 확인 토큰을 사용하세요. 호스트가 이메일을 노출하지 않는 경우 안정적인 `userId`를 반환하면 Agent-Native가 이를 소유자 키로 사용합니다.
+
+### 데이터베이스 격리
+
+임베디드 모드는 SQL의 Agent-Native 테이블을 관리합니다. 성숙한 SaaS 제품의 경우 가장 안전한 기본값은 **동일한 호스팅 및 인증, 전용 Agent-Native 데이터베이스/스키마**입니다:
+
+```ts
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL,
+  auth: getHostSession,
+  actions: hostActions,
+});
+```
+
+호스트 제품의 기본 `DATABASE_URL`를 사용하는 것은 지원되지만 이를 명시적으로 선택하십시오. Agent-Native는 `settings`, `application_state`, `tools`, `tool_data`와 같은 프레임워크 테이블, 브라우저 세션 테이블, 비밀, 채팅 스레드 및 관련 인덱스를 생성합니다. 전용 DB/스키마는 테이블 이름 충돌을 방지하고, 관리되는 테이블의 소유권을 명확하게 유지하며, 백업/보존 정책을 더 쉽게 추론할 수 있도록 해줍니다. 의도적으로 호스트 DB를 공유하는 경우 기존 테이블 이름을 먼저 검토하고 Agent-Native 테이블을 프레임워크 소유로 취급하세요.
+
+## 기타 모드 {#other-modes}
+
+위의 배터리 포함 플러그인이 가장 적합합니다. 다음 중 하나를 선택하세요
+귀하의 상황에 더 잘 맞는 경우에만:
+
+| 모드                              | 다음 경우에 사용                                                                                           | 패키지                                |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| **EmbeddedApp 선택기**            | 집중된 iframe(자산 선택기, 양식 작성기, 승인 패널)으로 전체 Agent-Native 앱을 실행합니다.                  | `@agent-native/embedding`             |
+| **`<AgentNative>` 호스트 브리지** | 페이지 컨텍스트와 클라이언트 actions를 수동으로 연결하는 독립형 사이드카 앱 또는 교차 출처 iframe.         | `@agent-native/core/client`           |
+| **이동식 확장 프로그램**          | SaaS가 이미 확장 저장소/승인을 소유한 경우 호스트 사용자가 샌드박스 미니 앱을 구축할 수 있도록 허용합니다. | `@agent-native/core/client` 확장 슬롯 |
+
+하위 수준 `@agent-native/embedding` 패키지는 다음을 공개합니다:
+
+| 가져오기 경로                      | 제공 내용                                                                             |
+| ---------------------------------- | ------------------------------------------------------------------------------------- |
+| `@agent-native/embedding`          | `EmbeddedApp` 선택기 구성 요소, `getA2AUrl`, `getMcpUrl`, `sendMessage`(A2A 스트리밍) |
+| `@agent-native/embedding/react`    | React 전용 후크 및 구성요소                                                           |
+| `@agent-native/embedding/bridge`   | `announceEmbeddedAppReady`, `sendEmbeddedAppMessage` — 임베디드 앱 내부에서 사용      |
+| `@agent-native/embedding/agent`    | 에이전트 엔드포인트 도우미                                                            |
+| `@agent-native/embedding/protocol` | 프로토콜 유형                                                                         |
+
+```bash
+pnpm add @agent-native/embedding
+```
+
+### 내장형 앱 및 선택기 모드
+
+호스트 제품이 완전한 제품을 출시하려는 경우 `@agent-native/embedding`를 사용하세요.
+집중된 iframe 표면으로서의 Agent-Native 앱: 자산 선택기, 자산 생성기,
+양식 작성기, 캘린더 슬롯 선택기, 승인 패널 또는 기타 작업별
+작업 흐름. 이는 아래의 사이드카 호스트 브리지보다 의도적으로 작습니다.
+iframe은 준비 상태를 알리고 호스트는 명명된 메시지를 보낼 수 있으며 삽입된 메시지는
+앱은 `chooseAsset` 또는 `close`와 같은 도메인 이벤트를 내보낼 수 있습니다.
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+export function AssetPickerDialog({ close }) {
+  return (
+    <EmbeddedApp
+      url="https://assets.agent-native.com/picker"
+      className="h-full w-full"
+      onLoad={(ref) => {
+        ref.postMessage("configure", {
+          prompt: "Editorial blog hero",
+          aspectRatio: "16:9",
+        });
+      }}
+      onMessage={(name, payload) => {
+        if (name === "chooseAsset") {
+          const asset = payload as { url: string; altText?: string };
+          insertAsset(asset.url, asset.altText);
+          close();
+        }
+        if (name === "close") close();
+      }}
+    />
+  );
+}
+```
+
+내장된 앱 내에서 브라우저 브리지를 사용하여 준비 상태를 알리고 전송
+이벤트가 호스트에게 다시 전달됩니다:
+
+```ts
+import {
+  announceEmbeddedAppReady,
+  sendEmbeddedAppMessage,
+} from "@agent-native/embedding/bridge";
+
+announceEmbeddedAppReady({ app: "assets", mode: "picker" });
+sendEmbeddedAppMessage("chooseAsset", {
+  url: asset.previewUrl,
+  assetId: asset.id,
+  altText: asset.altText,
+});
+```
+
+자산은 또한 이전 이미지 선택기의 호환성 별칭으로 `chooseImage`를 내보냅니다.
+호스트; 새로운 통합은 `chooseAsset`를 수신해야 합니다.
+
+호스팅된 자사 앱의 경우 Dispatch를 ID로 사용하여 Cross-App SSO를 활성화합니다.
+허브이므로 `content.agent-native.com` 및 `assets.agent-native.com`가 사용자를 연결합니다
+이메일이 확인되었습니다. Iframe 실행은 여전히 단기 경로 범위를 사용해야 합니다.
+타사 쿠키 복원력이 필요할 때 세션을 삽입하세요. 일반 앱 쿠키
+그 자체로는 완전한 삽입 인증 스토리가 아닙니다.
+
+동일한 패키지에는 프로토콜 검색을 위한 에이전트 엔드포인트 도우미가 포함되어 있으며
+A2A를 통한 텍스트 스트리밍:
+
+```ts
+import { getA2AUrl, getMcpUrl, sendMessage } from "@agent-native/embedding";
+
+getMcpUrl("https://assets.agent-native.com");
+getA2AUrl("https://assets.agent-native.com");
+
+for await (const chunk of sendMessage(
+  "https://assets.agent-native.com",
+  "Generate a blog hero",
+)) {
+  append(chunk);
+}
+```
+
+### 호스트 앱(`<AgentNative>` 호스트 브리지)
+
+> 위의 배터리 포함 플러그인이 선호됩니다. 이 하위 레벨 브리지를 사용하세요
+> 페이지를 연결하는 독립형 사이드카 앱 또는 교차 출처 iframe에만 해당
+> 컨텍스트 및 클라이언트 actions를 직접 사용하세요.
+
+독립형 사이드카 앱 또는 교차 출처 iframe의 경우 하위 수준 `<AgentNative />`를 사용하세요. iframe 사이드카 및 연결 페이지 컨텍스트, 라이브 클라이언트 actions, 호스트 새로 고침/탐색 명령을 한 곳에서 렌더링합니다.
+
+```tsx
+import { AgentNative, defineClientAction } from "@agent-native/core/client";
+
+export function AssistantDock({ customer, sessionToken }) {
+  return (
+    <AgentNative
+      agentUrl="https://agent.example.com/workspaces/acme/sidecar"
+      className="h-full w-full"
+      session={{ id: browserTabId(), label: "Customer detail" }}
+      auth={() => ({ token: sessionToken })}
+      screen={{ includeVisibleText: true }}
+      getContext={() => ({
+        route: {
+          name: "customer-detail",
+          pathname: window.location.pathname,
+          params: { customerId: customer.id },
+        },
+        resource: {
+          type: "customer",
+          id: customer.id,
+          name: customer.name,
+        },
+        selection: {
+          ids: getSelectedRowIds(),
+          text: window.getSelection()?.toString() || undefined,
+        },
+        user: currentUser(),
+        organization: currentOrganization(),
+      })}
+      actions={[
+        defineClientAction<{ contentId: string }, { published: true }>({
+          name: "publish-content",
+          description: "Publish a Builder content entry",
+          schema: {
+            type: "object",
+            properties: { contentId: { type: "string" } },
+            required: ["contentId"],
+          },
+          destructive: true,
+          approval: { title: "Publish this entry?", risk: "medium" },
+          run: async ({ contentId }, { refresh }) => {
+            await builderApi.publish(contentId);
+            await refresh({ queryKey: ["content", contentId] });
+            return { published: true };
+          },
+        }),
+        defineClientAction<{ elementId: string }, void>({
+          name: "select-element",
+          description: "Select an element in the live visual editor",
+          schema: {
+            type: "object",
+            properties: { elementId: { type: "string" } },
+            required: ["elementId"],
+          },
+          run: ({ elementId }) => editor.select(elementId),
+        }),
+      ]}
+      onNavigate={(payload) => {
+        const { path } = payload as { path: string };
+        router.navigate(path);
+      }}
+      onRefresh={(payload) => {
+        const { queryKey } = payload as { queryKey?: readonly unknown[] };
+        queryClient.invalidateQueries({ queryKey });
+      }}
+      onRemount={() => setAppKey((key) => key + 1)}
+      onOpenResource={(payload) => openResource(payload)}
+      onRequestApproval={(payload) => approvalDialog.confirm(payload)}
+    />
+  );
+}
+```
+
+명시적인 의미 컨텍스트만 원하는 경우 `screen={false}`를 사용하세요. 아직 UI를 의미 체계 ID 및 선택 상태에 매핑하지 않은 앱에 대한 대체 수단으로 `screen={{ includeDomHtml: true }}`를 사용하세요. 호스트 브리지는 기본적으로 `agentUrl` 원본의 메시지만 허용합니다. iframe URL가 신뢰할 수 있는 출처가 다른 라우팅/프록시 URL인 경우 `agentOrigin`를 전달하세요.
+
+React가 아닌 호스트의 경우 `createAgentNativeHostBridge()`를 직접 호출하고 동일한 `getContext`, `actions` 및 `commands` 옵션을 전달합니다.
+
+### iframe 측면
+
+Agent-Native 사이드카 내부에서 프레임 도우미를 사용하여 호스트 컨텍스트를 요청하고, 라이브 브라우저 세션 actions를 검색하고, 실행하거나, 호스트에 UI 작업을 수행하도록 요청합니다. 프로덕션에서는 항상 예상되는 `hostOrigin`를 전달하세요.
+
+```ts
+import {
+  announceAgentNativeFrameReady,
+  createAgentNativeHostTools,
+  requestAgentNativeHostActions,
+  requestAgentNativeHostContext,
+  runAgentNativeHostAction,
+  sendAgentNativeHostCommand,
+} from "@agent-native/core/client";
+
+announceAgentNativeFrameReady({ hostOrigin: "https://app.example.com" });
+
+const context = await requestAgentNativeHostContext({
+  hostOrigin: "https://app.example.com",
+});
+
+const liveActions = await requestAgentNativeHostActions({
+  hostOrigin: "https://app.example.com",
+});
+
+await runAgentNativeHostAction(
+  "select-element",
+  { elementId: context.selection?.ids?.[0] },
+  { hostOrigin: "https://app.example.com" },
+);
+
+await sendAgentNativeHostCommand(
+  "refreshData",
+  { queryKey: ["customer", context.resource?.id] },
+  { hostOrigin: "https://app.example.com" },
+);
+
+const hostTools = createAgentNativeHostTools({
+  hostOrigin: "https://app.example.com",
+});
+```
+
+### 서버 중재 도구 브리지
+
+CLAW 스타일 동료의 경우 iframe은 사이드카 백엔드에 라이브 브라우저 탭을 등록할 수도 있습니다. 그런 다음 에이전트는 요청을 대기열에 추가하는 일반 백엔드 도구를 가져오고, iframe이 이를 요청하고, 호스트 페이지가 이를 실행하며, 백엔드가 결과를 에이전트에 반환합니다.
+
+```an-diagram title="Server-mediated browser-session bridge" summary="A backend tool enqueues work; the registered tab claims it, runs it on the live page, and the result returns to the agent — so a backend/Slack/A2A agent can still touch the open tab."
+{
+  "html": "<div class=\"diagram-bridge\"><div class=\"diagram-node\" data-rough>Backend agent<br><small class=\"diagram-muted\">chat · Slack · A2A</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>enqueue request<br><small class=\"diagram-muted\">/_agent-native/browser-sessions</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Live tab claims it<br><small class=\"diagram-muted\">registered bridge</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">result &rarr; agent</div></div>",
+  "css": ".diagram-bridge{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bridge .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+사이드카 앱에서 iframe이 마운트되면 브라우저 세션 브리지를 한 번 시작합니다.
+
+```tsx
+import { useEffect } from "react";
+import { startAgentNativeBrowserSessionBridge } from "@agent-native/core/client";
+
+export function SidecarRuntime() {
+  useEffect(() => {
+    const bridge = startAgentNativeBrowserSessionBridge({
+      hostOrigin: "https://app.example.com",
+      label: "Builder editor",
+    });
+    return () => bridge.stop();
+  }, []);
+
+  return null;
+}
+```
+
+프레임워크는 `/_agent-native/browser-sessions`를 자동으로 마운트합니다. 브리지가 실행되면 사이드카 에이전트는 다음을 사용할 수 있습니다.
+
+| 도구                           | 목적                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| `list-browser-sessions`        | 현재 사용자의 연결된 호스트 탭을 확인하세요.                               |
+| `view-browser-session`         | 현재 페이지 컨텍스트 및 화면 스냅샷을 실시간 탭에 요청하세요.              |
+| `list-browser-session-actions` | 현재 클라이언트 측 작업 매니페스트에 대해 라이브 탭을 요청하세요.          |
+| `run-browser-session-action`   | 라이브 탭을 통해 현재 클라이언트 작업 하나를 실행하세요.                   |
+| `send-browser-session-command` | 호스트에게 새로 고침, 탐색, 다시 마운트, 다시 로드 또는 승인을 요청하세요. |
+
+이것은 에이전트가 Slack/Telegram/email에서 백엔드에서 실행 중이거나 A2A 수신자로서 실행 중이지만 사용자의 현재 브라우저 탭이 열려 있을 때 여전히 터치해야 하는 경우에 사용하는 브리지입니다. 브라우저가 닫힌 경우 백엔드 actions는 계속해서 내구성 있는 작업을 처리해야 하며 브라우저 세션 도구는 연결된 활성 탭이 없다고 보고합니다.
+
+### Actions
+
+두 가지 작업 클래스가 있습니다:
+
+| 작업 종류       | 실행 위치                                               | 브라우저를 닫아도 작동하나요? | 최적의 용도                                                                                       |
+| --------------- | ------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------- |
+| 백엔드 작업     | 사이드카 앱, 백엔드 API, MCP 또는 통합 어댑터           | 예                            | 만들기, 업데이트, 게시, 동기화, 보내기, 가져오기 등 지속적인 작업                                 |
+| 클라이언트 작업 | `<AgentNative actions={...} />`를 통한 현재 브라우저 탭 | 아니요                        | 임시 UI는 요소 선택, 편집기 상태 읽기, 행 스크롤, 현재 캔버스 상태 복사와 같은 작업을 수행합니다. |
+
+백엔드 actions는 새로 고침, 닫힌 브라우저, 재시도 또는 통합 트리거 실행 후에도 유지되어야 하는 모든 것에 대한 기본값이어야 합니다. 이는 사이드카 앱의 일반 Agent-Native 작업/도구 계층에 속하며, 에이전트는 채팅, 자동화, Slack/텔레그램/이메일 통합 및 백그라운드 작업에서 호출할 수 있습니다.
+
+클라이언트 actions는 하나의 브라우저 탭에 대한 라이브 브리지입니다. 호스트는 이를 `source: "client"` 및 `availability: "browser-session"`로 광고하고 사이드카는 해당 매니페스트를 임시로 처리해야 합니다. 경로 또는 선택 사항이 변경되면 actions를 다시 나열하고 탭이 사라지면 백엔드 actions로 대체됩니다.
+
+### 휴대용 확장 프로그램
+
+> Agent-Native를 관리하려는 경우 배터리 포함 플러그인을 선호하세요
+> 확장 정의, 승인, 저장 및 에이전트 생성 확장. 사용
+> 아래 휴대용 슬롯은 SaaS가 이미 해당 문제를 소유하고 있는 경우에만 해당됩니다.
+
+SDK는 또한 사용자 정의 확장, 즉 호스트 SaaS가 명명된 슬롯에서 렌더링할 수 있는 샌드박스 Alpine.js 미니 앱을 지원합니다. 고객이 상담원이 사용하는 것과 동일한 작업/컨텍스트 표면에 대해 자신만의 작은 패널, 계산기, 대시보드 또는 워크플로 도우미를 구축하기를 원할 때 이 기능을 사용하세요.
+
+```tsx
+import {
+  AgentNativeExtensionSlot,
+  createHttpAgentNativeExtensionStorage,
+  defineClientAction,
+} from "@agent-native/core/client";
+
+const storage = createHttpAgentNativeExtensionStorage({
+  endpoint: "/api/agent-native/extensions/storage",
+  headers: () => ({ Authorization: `Bearer ${sessionToken()}` }),
+});
+
+const actions = [
+  defineClientAction({
+    name: "list-at-risk-customers",
+    description: "List customers currently at risk",
+    schema: { type: "object", properties: {} },
+    run: () => crmApi.customers.list({ status: "at-risk" }),
+  }),
+];
+
+const customerHealthExtension = {
+  id: "customer-health",
+  name: "Customer health",
+  description: "Shows at-risk customers and quick notes.",
+  manifest: {
+    slots: ["crm.customer.sidebar"],
+    requestedActions: ["list-at-risk-customers"],
+    requestedCommands: ["openResource", "refreshData"],
+    storageScopes: ["user", "org"],
+  },
+  content: `
+    <div x-data="{
+      customers: [],
+      note: '',
+      async init() {
+        this.customers = await appAction('list-at-risk-customers', {})
+        const row = await extensionData.get('notes', slotContext.customerId, { scope: 'user' })
+        this.note = row?.data?.text || ''
+      },
+      async save() {
+        await extensionData.set('notes', slotContext.customerId, { text: this.note }, { scope: 'user' })
+        await agentNative.refresh({ customerId: slotContext.customerId })
+      }
+    }" x-init="init()" class="space-y-3">
+      <textarea class="w-full rounded-md border bg-background p-2" x-model="note"></textarea>
+      <button class="rounded-md bg-primary px-3 py-2 text-primary-foreground" @click="save()">Save</button>
+    </div>
+  `,
+};
+
+export function CustomerSidebar({ customer, userExtensions }) {
+  return (
+    <AgentNativeExtensionSlot
+      id="crm.customer.sidebar"
+      extensions={[customerHealthExtension, ...userExtensions]}
+      context={{ customerId: customer.id, plan: customer.plan }}
+      actions={actions}
+      storage={storage}
+      storageContext={{
+        userId: currentUser().id,
+        organizationId: currentOrganization().id,
+      }}
+      getContext={() => ({
+        resource: { type: "customer", id: customer.id, name: customer.name },
+      })}
+      commands={{
+        refreshData: async () => queryClient.invalidateQueries(),
+      }}
+    />
+  );
+}
+```
+
+매니페스트는 설치 계약입니다. `requestedActions`, `requestedCommands` 또는 `storageScopes`가 있는 경우 SDK는 iframe 요청이 작업 브리지 또는 스토리지 어댑터에 도달하기 전에 호스트에서 이를 시행합니다. `slots`가 있는 경우 `AgentNativeExtensionSlot`는 일치하는 슬롯의 확장만 렌더링합니다. 호스트는 `allowedActions`, `allowedCommands` 및 `allowedStorageScopes`를 사용하여 슬롯당 정책을 계속 재정의할 수 있습니다.
+
+확장자는 일반 HTML입니다. iframe 런타임은 미니앱에 동일한 안전한 브리지 기본 요소를 제공합니다.
+
+```html
+<div
+  x-data="{ customers: [], async init() { this.customers = await appAction('list-at-risk-customers', {}) } }"
+  x-init="init()"
+>
+  <template x-for="customer in customers" :key="customer.id">
+    <button
+      class="block w-full rounded-md px-3 py-2 text-left hover:bg-muted"
+      x-text="customer.name"
+      @click="agentNative.command('openResource', { type: 'customer', id: customer.id })"
+    ></button>
+  </template>
+</div>
+```
+
+iframe 내에서 사용 가능한 전역 변수:
+
+| 도우미                         | 목적                                                            |
+| ------------------------------ | --------------------------------------------------------------- |
+| `appAction(name, args)`        | 호스트가 선언한 작업을 실행합니다.                              |
+| `agentNative.context()`        | 현재 호스트 페이지, 리소스, 슬롯 및 사용자 데이터를 읽습니다.   |
+| `agentNative.command(name, p)` | 호스트에게 탐색, 새로 고침, 다시 마운트 또는 열기를 요청하세요. |
+| `agentNative.refresh(payload)` | `refreshData`의 단축키.                                         |
+| `extensionData.*`              | 호스트 어댑터를 통해 확장 로컬 데이터를 유지합니다.             |
+
+기본적으로 `extensionData`는 프로토타입 및 로컬 위젯에 유용한 브라우저 `localStorage`를 사용합니다. 프로덕션 SaaS 호스트는 백엔드 지원 `storage` 어댑터를 전달해야 사용자 및 조직 범위의 확장 데이터가 지속적이고 감사 가능하며 앱 권한에 따라 관리됩니다. 일반 HTTP 어댑터는 `{ operation, extensionId, slotId, collection, id, data, options, context }`와 같은 POST 본문을 전송하고 `{ result }` 또는 결과 JSON를 직접 기대합니다.
+
+이 이식 가능한 SDK 레이어는 프레임워크에 내장된 SQL 지원 확장 저장소와 별개입니다. Agent-Native 앱에서는 기존 `ExtensionSlot`/`EmbeddedExtension` 구성 요소와 `create-extension` 작업을 사용합니다. 호스팅된 SaaS 임베딩 시나리오에서 Agent-Native가 확장 정의, 승인, 저장 및 에이전트 생성 확장을 즉시 관리하도록 하려면 `createAgentNativeEmbeddedPlugin()`와 `AgentNativeEmbedded`를 선호합니다. SaaS가 이미 확장 정의, 승인, 마켓플레이스, 스토리지 및 청구를 소유한 경우에만 `AgentNativeExtensionSlot`를 사용하십시오.
+
+보안 모델:
+
+- 확장 iframe은 `allow-same-origin` 없이 샌드박스 처리됩니다. 미니앱은 상위 DOM, 쿠키 또는 앱 런타임을 직접 읽을 수 없습니다.
+- 확장 프로그램은 호스트 및 확장 프로그램 매니페스트에서 허용하는 actions 및 명령만 호출할 수 있습니다.
+- 위험한 actions는 호스트가 승인 흐름을 표시할 수 있도록 `destructive` 또는 `requiresApproval`를 설정해야 합니다.
+- 사용자가 작성한 확장 HTML를 신뢰할 수 없는 것으로 처리합니다. 사용자/조직별로 마켓플레이스 설치, 로그 작업 사용 및 범위 백엔드 저장소를 검토하세요.
+
+### 세션 및 탭
+
+호스트 브리지의 범위는 하나의 iframe/호스트-창 쌍으로 지정됩니다. 동일한 사용자가 여러 탭을 열면 각 탭에는 자체 `session`, 컨텍스트, 선택, 클라이언트 actions 및 보류 중인 명령 응답이 있습니다. 한 탭에서 발견된 클라이언트 작업이 다른 탭에서 실행될 수 있거나 탐색 후에도 여전히 존재할 것이라고 가정하지 마십시오.
+
+다중 탭 제품의 경우 SQL/백엔드 actions에서 내구성 상태를 유지하고 탭 로컬 부분(행에 초점 맞추기, 표시되는 편집기 상태 복사, 캔버스 요소 선택 또는 현재 React 쿼리 캐시 새로 고침)에만 클라이언트 actions를 사용합니다. 사이드카가 현재 탭이 브라우저 세션 작업을 실행하기에 적합한 위치인지 결정할 수 있도록 충분한 `route`, `resource` 및 `selection` 컨텍스트를 포함하세요.
+
+### 명령 모델
+
+내장된 명령 이름은 의도적으로 데이터베이스 형태가 아닌 앱 형태입니다:
+
+| 명령                                   | 목적                                                                         |
+| -------------------------------------- | ---------------------------------------------------------------------------- |
+| `navigate`                             | 호스트 UI를 경로/보기/리소스로 이동합니다.                                   |
+| `refreshData` / `refresh-data`         | 호스트에 클라이언트 측 데이터를 무효화하도록 요청하세요.                     |
+| `remountView` / `remount-view`         | 호스트에게 하위 트리를 다시 마운트하도록 요청합니다. `<App key={key} />`.    |
+| `hardReload` / `hard-reload`           | 전체 브라우저를 다시 로드합니다.                                             |
+| `openResource` / `open-resource`       | 호스트 UI에서 특정 도메인 개체를 엽니다.                                     |
+| `requestApproval` / `request-approval` | 호스트에게 확인 흐름을 보여달라고 요청하세요. 이에 대한 핸들러를 등록하세요. |
+
+핸들러가 제공되지 않으면 안전한 기본값은 `agentNative:refresh-data` 및 `agentNative:remount-view`와 같은 브라우저 이벤트를 전달합니다. `requestApproval`에는 기본 핸들러가 없습니다. 사용하기 전에 등록해 보세요.
+
+### 승인 지침
+
+위험한 클라이언트 actions를 매니페스트에 `destructive: true`로 표시하고 현재 보기 외부의 사용자에게 삭제, 게시, 전송, 청구, 초대, 공유 또는 기타 영향을 미치는 작업을 실행하기 전에 호스트 승인을 요구합니다. 백엔드 actions는 자체 인증 및 승인 확인도 시행해야 합니다. 호스트 승인은 보안 경계가 아닌 유용한 UX입니다.
+
+이 모양을 선호하세요:
+
+- 지속성 변형은 유효성 검사, 인증, 감사 로깅 및 재시도를 통해 백엔드 작업에서 실행됩니다.
+- 호스트 명령은 승인 UI를 열거나 영향을 받는 리소스에 집중합니다.
+- 클라이언트 작업은 백엔드에서 발생할 수 없는 라이브 UI 단계만 처리합니다.
+
+### 런타임 통합
+
+에이전트 런타임이 일반 도구 설명자를 허용하는 경우 사이드카 iframe 내에서 `createAgentNativeHostTools()`를 사용하세요. 프레임워크에 구애받지 않는 네 가지 도구를 반환합니다:
+
+| 도구                | 목적                                                                  |
+| ------------------- | --------------------------------------------------------------------- |
+| `view-host-screen`  | 의미론적 호스트 컨텍스트 및 화면 스냅샷을 읽습니다.                   |
+| `list-host-actions` | 현재 탭에 노출된 라이브 브라우저 세션 actions를 나열합니다.           |
+| `run-host-action`   | 이름으로 하나의 라이브 클라이언트 작업을 실행합니다.                  |
+| `send-host-command` | 새로 고침, 탐색, 다시 마운트 또는 승인과 같은 호스트 명령을 보냅니다. |
+
+도우미는 의도적으로 일반 `{ name, description, parameters, execute }` 개체를 반환하므로 사이드카는 이 SDK를 하나의 런타임에 결합하지 않고도 AI SDK, Anthropic, OpenAI 함수 호출 또는 Agent-Native `ActionEntry` 모양에 적용할 수 있습니다.
+
+## 권장 제품 형태
+
+iframe 우선을 시작합니다. 이는 릴리스 주기 또는 CSS/런타임 가정을 결합하지 않고도 Builder.io, 고객 SaaS 앱 및 내부 관리 도구에서 작동합니다.
+
+사이드카 자체는 여전히 Agent-Native 앱/템플릿이어야 합니다. actions는 백엔드 API 표면이고, SQL 지원 앱 상태는 에이전트의 메모리이며, Slack 또는 Telegram과 같은 통합은 동일한 내구성 있는 채팅으로 라우팅될 수 있습니다. 임베딩 SDK는 해당 사이드카와 현재 호스트 페이지 사이에 라이브 멤브레인을 제공합니다.