@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/hi-IN/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` के तहत माउंट किया गया है, एजेंट उसी actions को UI के रूप में कॉल कर सकता है, उपयोगकर्ता द्वारा बनाए गए एक्सटेंशन SQL में संग्रहीत हैं, `extensionData` टिकाऊ है और उपयोगकर्ता/ऑर्ग स्कोप्ड है, और ब्राउज़र-सत्र उपकरण बैकएंड एजेंट को वर्तमान में खुले का निरीक्षण या संचालन करने देते हैं टैब.
+
+होस्ट प्रमाणीकरण सर्वर-साइड है। सत्य के स्रोत के रूप में ब्राउज़र से पहचान को पारित न करें; होस्ट के अनुरोध/सत्र ऑब्जेक्ट या अल्पकालिक सर्वर-सत्यापित टोकन का उपयोग करें। यदि होस्ट ईमेल को उजागर नहीं करता है, तो एक स्थिर `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}
+
+उपरोक्त बैटरी-शामिल प्लगइन सुखद मार्ग है। इनमें से किसी एक तक पहुंचें
+केवल तभी जब यह आपकी स्थिति के लिए बेहतर अनुकूल हो:
+
+| मोड                             | इसका उपयोग तब करें जब                                                                                                        | पैकेज                                       |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| **एंबेडेडऐप पिकर**              | एक केंद्रित आईफ्रेम (एसेट पिकर, फॉर्म बिल्डर, अनुमोदन पैनल) के रूप में एक पूर्ण Agent-Native ऐप लॉन्च करना।                  | `@agent-native/embedding`                   |
+| **`<AgentNative>` होस्ट ब्रिज** | स्टैंडअलोन साइडकार ऐप्स या क्रॉस-ओरिजिन आईफ्रेम जो पेज संदर्भ और क्लाइंट actions को मैन्युअल रूप से वायर करते हैं।           | `@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` का उपयोग करें
+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` के लिए सुनना चाहिए।
+
+होस्टेड प्रथम-पक्ष ऐप्स के लिए, पहचान के रूप में डिस्पैच के साथ क्रॉस-ऐप SSO सक्षम करें
+हब ताकि `content.agent-native.com` और `assets.agent-native.com` उपयोगकर्ताओं को लिंक करें
+सत्यापित ईमेल. आईफ़्रेम लॉन्च को अभी भी अल्पकालिक, रूट-स्कोप
+एम्बेड सत्र जब उन्हें तृतीय-पक्ष-कुकी लचीलेपन की आवश्यकता होती है; सामान्य ऐप कुकीज़
+अपने आप में पूर्ण एंबेड ऑथ स्टोरी नहीं हैं।
+
+उसी पैकेज में प्रोटोकॉल खोज के लिए एजेंट एंडपॉइंट हेल्पर्स शामिल हैं और
+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>` होस्ट ब्रिज)
+
+> उपरोक्त बैटरी-शामिल प्लगइन को प्राथमिकता दी जाती है। इस निचले स्तर के पुल का उपयोग करें
+> केवल स्टैंडअलोन साइडकार ऐप्स या क्रॉस-ओरिजिन आईफ्रेम के लिए जहां आप पेज वायर करते हैं
+> संदर्भ और ग्राहक स्वयं actions।
+
+स्टैंडअलोन साइडकार ऐप्स या क्रॉस-ओरिजिन आईफ्रेम के लिए, निचले स्तर के `<AgentNative />` का उपयोग करें। यह आईफ्रेम साइडकार और वायर पेज संदर्भ, लाइव क्लाइंट 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}` का उपयोग करें। उन ऐप्स के लिए फ़ॉलबैक के रूप में `screen={{ includeDomHtml: true }}` का उपयोग करें जिन्होंने अभी तक अपने UI को सिमेंटिक आईडी और चयन स्थिति में मैप नहीं किया है। होस्ट ब्रिज डिफ़ॉल्ट रूप से केवल `agentUrl` के मूल से संदेशों को स्वीकार करता है। यदि iframe URL एक रूटेड/प्रॉक्सीड URL है जिसका विश्वसनीय मूल भिन्न है, तो `agentOrigin` पास करें।
+
+गैर-React होस्ट के लिए, सीधे `createAgentNativeHostBridge()` पर कॉल करें और समान `getContext`, `actions`, और `commands` विकल्प पास करें।
+
+### आईफ्रेम साइड
+
+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 अपने लाइव ब्राउज़र टैब को साइडकार बैकएंड के साथ भी पंजीकृत कर सकता है। फिर एजेंट को सामान्य बैकएंड टूल मिलते हैं जो एक अनुरोध को सूचीबद्ध करते हैं, आईफ्रेम उस पर दावा करता है, होस्ट पेज उसे निष्पादित करता है, और बैकएंड एजेंट को परिणाम लौटाता है।
+
+```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}"
+}
+```
+
+साइडकार ऐप में, आईफ्रेम माउंट होने पर एक बार ब्राउज़र-सत्र ब्रिज शुरू करें:
+
+```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/टेलीग्राम/ईमेल में, या 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 नामित स्लॉट में प्रस्तुत कर सकता है। इसका उपयोग तब करें जब ग्राहक एजेंट द्वारा उपयोग की जाने वाली उसी क्रिया/संदर्भ सतह पर अपने स्वयं के छोटे पैनल, कैलकुलेटर, डैशबोर्ड या वर्कफ़्लो सहायक बनाना चाहता है।
+
+```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` मौजूद होते हैं, तो iframe अनुरोध एक्शन ब्रिज या स्टोरेज एडाप्टर तक पहुंचने से पहले SDK उन्हें होस्ट में लागू करता है। जब `slots` मौजूद होता है, तो `AgentNativeExtensionSlot` केवल मिलान स्लॉट में एक्सटेंशन प्रस्तुत करता है। होस्ट अभी भी `allowedActions`, `allowedCommands`, और `allowedStorageScopes` के साथ प्रति स्लॉट नीति को ओवरराइड कर सकते हैं।
+
+एक एक्सटेंशन सादा HTML है। आईफ़्रेम रनटाइम मिनी-ऐप को समान सुरक्षित ब्रिज प्रिमिटिव प्रदान करता है:
+
+```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 एम्बेडिंग परिदृश्य में, `createAgentNativeEmbeddedPlugin()` प्लस `AgentNativeEmbedded` को प्राथमिकता दें, जब आप चाहते हैं कि Agent-Native बॉक्स से बाहर एक्सटेंशन परिभाषाओं, अनुमोदन, भंडारण और एजेंट-निर्मित एक्सटेंशन को प्रबंधित करे। `AgentNativeExtensionSlot` का उपयोग केवल तभी करें जब SaaS के पास पहले से ही एक्सटेंशन परिभाषाएँ, अनुमोदन, बाज़ार, भंडारण और बिलिंग हो।
+
+सुरक्षा मॉडल:
+
+- एक्सटेंशन आईफ्रेम को `allow-same-origin` के बिना सैंडबॉक्स किया गया है; मिनी-ऐप मूल DOM, कुकीज़, या ऐप रनटाइम को सीधे नहीं पढ़ सकता है।
+- एक्सटेंशन केवल actions और होस्ट और एक्सटेंशन मेनिफेस्ट द्वारा अनुमत कमांड को कॉल कर सकते हैं।
+- जोखिम भरे actions को `destructive` या `requiresApproval` सेट करना चाहिए ताकि होस्ट अनुमोदन प्रवाह दिखा सके।
+- उपयोगकर्ता द्वारा लिखित एक्सटेंशन HTML को अविश्वसनीय मानें। उपयोगकर्ता/संगठन द्वारा मार्केटप्लेस इंस्टॉल, लॉग एक्शन उपयोग और स्कोप बैकएंड स्टोरेज की समीक्षा करें।
+
+### सत्र और टैब
+
+होस्ट ब्रिज को एक आईफ्रेम/होस्ट-विंडो जोड़ी तक सीमित किया गया है। यदि एक ही उपयोगकर्ता एकाधिक टैब खोलता है, तो प्रत्येक टैब का अपना `session`, संदर्भ, चयन, क्लाइंट actions और लंबित कमांड प्रतिक्रियाएँ होती हैं। यह न मानें कि एक टैब में खोजी गई क्लाइंट कार्रवाई दूसरे टैब में चल सकती है, या यह नेविगेशन के बाद भी मौजूद रहेगी।
+
+मल्टी-टैब उत्पादों के लिए, SQL/बैकएंड actions में टिकाऊ स्थिति रखें और केवल टैब-स्थानीय भागों के लिए क्लाइंट actions का उपयोग करें: एक पंक्ति पर ध्यान केंद्रित करना, दृश्य संपादक स्थिति की प्रतिलिपि बनाना, एक कैनवास तत्व का चयन करना, या वर्तमान React क्वेरी कैश को ताज़ा करना। साइडकार के लिए पर्याप्त `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 चरण को संभालती है जो बैकएंड पर नहीं हो सकती।
+
+### रनटाइम एकीकरण
+
+जब आपका एजेंट रनटाइम सादे टूल डिस्क्रिप्टर स्वीकार करता है तो साइडकार आईफ्रेम के अंदर `createAgentNativeHostTools()` का उपयोग करें। यह चार फ्रेमवर्क-अज्ञेयवादी उपकरण लौटाता है:
+
+| उपकरण               | उद्देश्य                                                               |
+| ------------------- | ---------------------------------------------------------------------- |
+| `view-host-screen`  | सिमेंटिक होस्ट संदर्भ और स्क्रीन स्नैपशॉट पढ़ें।                       |
+| `list-host-actions` | वर्तमान टैब द्वारा प्रदर्शित लाइव ब्राउज़र-सत्र actions की सूची बनाएं। |
+| `run-host-action`   | नाम से एक लाइव क्लाइंट कार्रवाई चलाएँ।                                 |
+| `send-host-command` | रीफ्रेश, नेविगेट, रीमाउंट, या अनुमोदन जैसे होस्ट कमांड भेजें।          |
+
+सहायक जानबूझकर सादे `{ name, description, parameters, execute }` ऑब्जेक्ट लौटाता है ताकि साइडकार उन्हें इस SDK को एक रनटाइम में जोड़े बिना AI SDK, एंथ्रोपिक, OpenAI फ़ंक्शन कॉलिंग, या Agent-Native `ActionEntry` आकार में अनुकूलित कर सकें।
+
+## अनुशंसित उत्पाद आकार
+
+iframe-पहले प्रारंभ करें। यह Builder.io, ग्राहक SaaS ऐप्स और आंतरिक व्यवस्थापक टूल के लिए रिलीज चक्र या CSS/रनटाइम धारणाओं को जोड़े बिना काम करता है।
+
+साइडकार अभी भी एक Agent-Native ऐप/टेम्पलेट होना चाहिए: actions बैकएंड API सतह है, SQL-समर्थित ऐप स्टेट एजेंट की मेमोरी है, और Slack या टेलीग्राम जैसे एकीकरण उसी टिकाऊ चैट में रूट कर सकते हैं। एम्बेडिंग SDK उस साइडकार और वर्तमान होस्ट पेज के बीच लाइव झिल्ली की आपूर्ति करता है।