Skip to content

BuilderIO/agent-native / packages/core/docs

agent-native-docs

Unverified

How to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.

FileKindSize
AGENTS.mdmarkdown6.0 KB
SKILL.mdskill md2.2 KB
content/a2a-protocol.mdxmarkdown37.6 KB
content/actions-access-control.mdxmarkdown28.9 KB
content/actions-advanced.mdxmarkdown13.1 KB
content/actions-agent-tools.mdxmarkdown5.6 KB
content/actions-defining.mdxmarkdown31.2 KB
content/actions-other-surfaces.mdxmarkdown10.3 KB
content/actions-overview.mdxmarkdown8.3 KB
content/actions-run-context.mdxmarkdown9.1 KB
content/add-ui-to-your-agent.mdxmarkdown5.0 KB
content/administered-deployments.mdxmarkdown7.7 KB
content/agent-mentions.mdxmarkdown10.2 KB
content/agent-native-config.mdxmarkdown34.9 KB
content/agent-native-toolkit.mdxmarkdown17.3 KB
content/agent-resources.mdxmarkdown27.0 KB
content/agent-surfaces.mdxmarkdown33.8 KB
content/agent-teams.mdxmarkdown13.4 KB
content/agent-web-surfaces.mdxmarkdown10.7 KB
content/agentkit.mdxmarkdown14.0 KB
content/audit-log.mdxmarkdown14.3 KB
content/authentication.mdxmarkdown30.7 KB
content/automation-connectors.mdxmarkdown7.8 KB
content/automations.mdxmarkdown26.7 KB
content/aws-amplify.mdxmarkdown10.7 KB
content/aws-lambda.mdxmarkdown13.9 KB
content/aws-rds.mdxmarkdown1.7 KB
content/azure-postgresql.mdxmarkdown1.8 KB
content/azure-static-web-apps.mdxmarkdown9.1 KB
content/blueprint-installer.mdxmarkdown6.3 KB
content/cli-adapters.mdxmarkdown5.7 KB
content/client-advanced.mdxmarkdown13.1 KB
content/client-agent-chat.mdxmarkdown17.7 KB
content/client-data.mdxmarkdown19.3 KB
content/client-entry-points.mdxmarkdown1.2 KB
content/client-overview.mdxmarkdown10.6 KB
content/client-routing.mdxmarkdown5.7 KB
content/client-sync-internals.mdxmarkdown5.2 KB
content/cloneable-saas.mdxmarkdown16.6 KB
content/cloud-sql.mdxmarkdown2.3 KB
content/cloudflare.mdxmarkdown8.3 KB
content/code-agents-ui.mdxmarkdown26.6 KB
content/components.mdxmarkdown42.9 KB
content/context-awareness.mdxmarkdown24.9 KB
content/create-with-an-agent.mdxmarkdown8.8 KB
content/creating-templates.mdxmarkdown21.6 KB
content/cross-app-connect-design.mdxmarkdown8.4 KB
content/cross-app-sso.mdxmarkdown8.7 KB
content/custom-design-system.mdxmarkdown17.3 KB
content/data-programs.mdxmarkdown25.0 KB
content/decisions.mdxmarkdown7.9 KB
content/deno-deploy.mdxmarkdown7.2 KB
content/deploy-an-app.mdxmarkdown5.0 KB
content/deployment-environment-variables.mdxmarkdown16.3 KB
content/deployment.mdxmarkdown11.3 KB
content/dispatch.mdxmarkdown18.6 KB
content/docker.mdxmarkdown8.1 KB
content/docs-components.mdxmarkdown28.9 KB
content/doctor.mdxmarkdown21.3 KB
content/drafts/clips-experimental-features.mdmarkdown5.4 KB
content/drop-in-agent.mdxmarkdown16.0 KB
content/durable-background-runs.mdxmarkdown13.8 KB
content/durable-resume.mdxmarkdown10.0 KB
content/embedding-sdk.mdxmarkdown31.3 KB
content/environment-variables.mdxmarkdown29.9 KB
content/evals.mdxmarkdown12.4 KB
content/extensions.mdxmarkdown34.8 KB
content/external-agents-catalog.mdxmarkdown40.5 KB
content/external-agents.mdxmarkdown29.3 KB
content/file-uploads.mdxmarkdown10.7 KB
content/generative-ui.mdxmarkdown10.8 KB
content/getting-started-actions.mdxmarkdown2.7 KB
content/getting-started-pages.mdxmarkdown2.6 KB
content/getting-started.mdxmarkdown7.2 KB
content/harness-agents.mdxmarkdown16.9 KB
content/http-api.mdxmarkdown20.9 KB
content/integrations.mdxmarkdown33.8 KB
content/internationalization.mdxmarkdown6.2 KB
content/key-concepts.mdxmarkdown30.6 KB
content/koyeb.mdxmarkdown7.3 KB
content/locales/ar-SA/a2a-protocol.mdxmarkdown48.5 KB
content/locales/ar-SA/actions-access-control.mdxmarkdown40.8 KB
content/locales/ar-SA/actions-advanced.mdxmarkdown16.3 KB
content/locales/ar-SA/actions-agent-tools.mdxmarkdown8.1 KB
content/locales/ar-SA/actions-defining.mdxmarkdown42.2 KB
content/locales/ar-SA/actions-other-surfaces.mdxmarkdown14.5 KB
content/locales/ar-SA/actions-overview.mdxmarkdown11.3 KB
content/locales/ar-SA/actions-run-context.mdxmarkdown11.1 KB
content/locales/ar-SA/add-ui-to-your-agent.mdxmarkdown3.7 KB
content/locales/ar-SA/administered-deployments.mdxmarkdown6.4 KB
content/locales/ar-SA/agent-mentions.mdxmarkdown11.8 KB
content/locales/ar-SA/agent-native-toolkit.mdxmarkdown17.3 KB
content/locales/ar-SA/agent-resources.mdxmarkdown36.8 KB
content/locales/ar-SA/agent-surfaces.mdxmarkdown48.4 KB
content/locales/ar-SA/agent-teams.mdxmarkdown18.5 KB
content/locales/ar-SA/agent-web-surfaces.mdxmarkdown14.3 KB
content/locales/ar-SA/audit-log.mdxmarkdown15.9 KB
content/locales/ar-SA/authentication.mdxmarkdown39.8 KB
content/locales/ar-SA/automations.mdxmarkdown31.3 KB
content/locales/ar-SA/aws-amplify.mdxmarkdown14.9 KB
content/locales/ar-SA/aws-lambda.mdxmarkdown18.9 KB
content/locales/ar-SA/aws-rds.mdxmarkdown319 B
content/locales/ar-SA/azure-postgresql.mdxmarkdown344 B
content/locales/ar-SA/azure-static-web-apps.mdxmarkdown12.4 KB
content/locales/ar-SA/blueprint-installer.mdxmarkdown8.4 KB
content/locales/ar-SA/cli-adapters.mdxmarkdown6.7 KB
content/locales/ar-SA/client-advanced.mdxmarkdown17.8 KB
content/locales/ar-SA/client-agent-chat.mdxmarkdown23.0 KB
content/locales/ar-SA/client-data.mdxmarkdown23.8 KB
content/locales/ar-SA/client-entry-points.mdxmarkdown1.6 KB
content/locales/ar-SA/client-overview.mdxmarkdown13.9 KB
content/locales/ar-SA/client-routing.mdxmarkdown7.2 KB
content/locales/ar-SA/client-sync-internals.mdxmarkdown7.3 KB
content/locales/ar-SA/cloneable-saas.mdxmarkdown23.2 KB
content/locales/ar-SA/cloud-sql.mdxmarkdown317 B
content/locales/ar-SA/cloudflare.mdxmarkdown11.9 KB
content/locales/ar-SA/code-agents-ui.mdxmarkdown34.2 KB
content/locales/ar-SA/components.mdxmarkdown51.5 KB
content/locales/ar-SA/context-awareness.mdxmarkdown33.1 KB
content/locales/ar-SA/create-with-an-agent.mdxmarkdown12.2 KB
content/locales/ar-SA/creating-templates.mdxmarkdown26.8 KB
content/locales/ar-SA/cross-app-connect-design.mdxmarkdown1.5 KB
content/locales/ar-SA/cross-app-sso.mdxmarkdown9.7 KB
content/locales/ar-SA/custom-design-system.mdxmarkdown21.6 KB
content/locales/ar-SA/data-programs.mdxmarkdown33.3 KB
content/locales/ar-SA/decisions.mdxmarkdown9.1 KB
content/locales/ar-SA/deno-deploy.mdxmarkdown10.1 KB
content/locales/ar-SA/deploy-an-app.mdxmarkdown7.1 KB
content/locales/ar-SA/deployment-environment-variables.mdxmarkdown21.3 KB
content/locales/ar-SA/deployment.mdxmarkdown13.9 KB
content/locales/ar-SA/dispatch.mdxmarkdown27.3 KB
content/locales/ar-SA/docker.mdxmarkdown11.3 KB
content/locales/ar-SA/doctor.mdxmarkdown3.4 KB
content/locales/ar-SA/drop-in-agent.mdxmarkdown20.8 KB
content/locales/ar-SA/durable-resume.mdxmarkdown15.4 KB
content/locales/ar-SA/embedding-sdk.mdxmarkdown41.3 KB
content/locales/ar-SA/evals.mdxmarkdown13.3 KB
content/locales/ar-SA/extensions.mdxmarkdown34.0 KB
content/locales/ar-SA/external-agents.mdxmarkdown89.3 KB
content/locales/ar-SA/file-uploads.mdxmarkdown13.4 KB
content/locales/ar-SA/getting-started-actions.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started-pages.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started.mdxmarkdown9.7 KB
content/locales/ar-SA/harness-agents.mdxmarkdown22.3 KB
content/locales/ar-SA/internationalization.mdxmarkdown8.2 KB
content/locales/ar-SA/key-concepts.mdxmarkdown42.0 KB
content/locales/ar-SA/koyeb.mdxmarkdown10.2 KB
content/locales/ar-SA/mcp-apps.mdxmarkdown33.7 KB
content/locales/ar-SA/mcp-clients.mdxmarkdown35.0 KB
content/locales/ar-SA/mcp-protocol.mdxmarkdown27.6 KB
content/locales/ar-SA/messaging.mdxmarkdown59.2 KB
content/locales/ar-SA/multi-app-workspace.mdxmarkdown36.2 KB
content/locales/ar-SA/multi-tenancy.mdxmarkdown7.5 KB
content/locales/ar-SA/native-chat-ui.mdxmarkdown21.3 KB
content/locales/ar-SA/neon.mdxmarkdown244 B
content/locales/ar-SA/netlify.mdxmarkdown15.2 KB
content/locales/ar-SA/node-docker.mdxmarkdown878 B
content/locales/ar-SA/node-js.mdxmarkdown8.4 KB
content/locales/ar-SA/notifications.mdxmarkdown16.2 KB
content/locales/ar-SA/observability.mdxmarkdown45.2 KB
content/locales/ar-SA/observational-memory.mdxmarkdown10.9 KB
content/locales/ar-SA/onboarding.mdxmarkdown16.9 KB
content/locales/ar-SA/organizations-teams-permissions.mdxmarkdown5.9 KB
content/locales/ar-SA/package-lifecycle.mdxmarkdown3.0 KB
content/locales/ar-SA/plan-plugin.mdxmarkdown23.0 KB
content/locales/ar-SA/portal.mdxmarkdown636 B
content/locales/ar-SA/postgres.mdxmarkdown487 B
content/locales/ar-SA/pr-visual-recap.mdxmarkdown53.9 KB
content/locales/ar-SA/privacy-and-data-rights.mdxmarkdown6.2 KB
content/locales/ar-SA/processors.mdxmarkdown8.7 KB
content/locales/ar-SA/progress.mdxmarkdown10.7 KB
content/locales/ar-SA/pure-agent-apps.mdxmarkdown5.0 KB
content/locales/ar-SA/real-time-collaboration.mdxmarkdown55.6 KB
content/locales/ar-SA/recorder.mdxmarkdown16.7 KB
content/locales/ar-SA/recurring-jobs.mdxmarkdown23.8 KB
content/locales/ar-SA/render.mdxmarkdown11.2 KB
content/locales/ar-SA/sandbox-adapters.mdxmarkdown18.0 KB
content/locales/ar-SA/security.mdxmarkdown31.5 KB
content/locales/ar-SA/server-database.mdxmarkdown27.6 KB
content/locales/ar-SA/server-middleware.mdxmarkdown7.9 KB
content/locales/ar-SA/server-overview.mdxmarkdown12.2 KB
content/locales/ar-SA/server-plugins.mdxmarkdown9.1 KB
content/locales/ar-SA/server-routes.mdxmarkdown14.3 KB
content/locales/ar-SA/sharing.mdxmarkdown28.6 KB
content/locales/ar-SA/skills-guide.mdxmarkdown27.0 KB
content/locales/ar-SA/ssr-caching.mdxmarkdown7.4 KB
content/locales/ar-SA/supabase.mdxmarkdown264 B
content/locales/ar-SA/syncing-template-changes.mdxmarkdown11.7 KB
content/locales/ar-SA/telemetry.mdxmarkdown21.9 KB
content/locales/ar-SA/template-analytics.mdxmarkdown26.4 KB
content/locales/ar-SA/template-assets.mdxmarkdown31.9 KB
content/locales/ar-SA/template-brain.mdxmarkdown29.7 KB
content/locales/ar-SA/template-calendar-agent.mdxmarkdown10.2 KB
content/locales/ar-SA/template-calendar-developers.mdxmarkdown33.4 KB
content/locales/ar-SA/template-calendar-features.mdxmarkdown14.4 KB
content/locales/ar-SA/template-calendar-integrations.mdxmarkdown6.2 KB
content/locales/ar-SA/template-calendar.mdxmarkdown4.4 KB
content/locales/ar-SA/template-chat-agent.mdxmarkdown4.7 KB
content/locales/ar-SA/template-chat-developers.mdxmarkdown31.3 KB
content/locales/ar-SA/template-chat-features.mdxmarkdown9.9 KB

content/locales/ar-SA/drop-in-agent.mdx

View on GitHub
---
title: "وكيل الدخول"
description: "قم بتثبيت دردشة الوكيل + موارد الوكيل في أي تطبيق React باستخدام <AgentPanel>، و<AgentSidebar>، وsendToAgentChat()."
---

# وكيل الدخول

> **صفحة المطور.** هذه الصفحة مخصصة للمطورين الذين يقومون بدمج الوكيل في تطبيق React. للتعرف على تجربة المستخدم النهائي في العمل مع الوكيل، راجع [Using Your Agent](/docs/using-your-agent).

لست بحاجة إلى إنشاء وكيل أصلي من البداية. يتم شحن دردشة الوكيل وعلامة تبويب موارد الوكيل ومحطة CLI والإدخال الصوتي وجميع البنية التحتية ذات الصلة كمجموعة من مكونات React التي تضعها في أي تطبيق.

> **المتطلبات الأساسية:** يجب أن يقوم الخادم بتشغيل `agent-chat-plugin` (يتم تركيبه تلقائيًا في كل قالب). إذا كنت تبدأ من الصفر، فراجع [Server](/docs/server-overview).
>
> هل تحتاج إلى خريطة API العامة بدلاً من البرنامج التعليمي؟ انظر [Component API](/docs/components).

## نظرة سريعة على المكونات {#components}

| المكون                | ما هو                                                                            | استخدمه عندما                                            |
| --------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `<AgentSidebar>`      | يغلف تخطيط التطبيق الجذر ويضيف لوحة جانبية قابلة للتبديل تحتوي على الوكيل الكامل | تريد أن يكون الوكيل متاحًا بجانب تطبيقك على كل شاشة      |
| `<AgentToggleButton>` | فتح/إغلاق `<AgentSidebar>` (ضعه في رأسك)                                         | إقران مع `<AgentSidebar>`                                |
| `<AgentPanel>`        | اللوحة الأولية نفسها — الدردشة + CLI + علامات تبويب موارد الوكيل                 | تريد التحكم الكامل في التخطيط، أو صفحة وكيل مخصصة        |
| `<AgentChatSurface>`  | سطح دردشة/صفحة مزود بأسلاك مسبقة                                                 | تريد الدردشة بدون غلاف الشريط الجانبي                    |
| `<AssistantChat>`     | عارض الدردشة ذو المستوى الأدنى مع ربطات الملحن/السجل                             | تحتاج إلى كروم مخصص للمحادثة القياسية UI                 |
| `sendToAgentChat()`   | إرسال رسالة إلى الدردشة برمجيًا                                                  | زر يقوم بتسليم العمل إلى الوكيل بدلاً من التشغيل المضمّن |
| `useActionMutation()` | مجمّع الواجهة الأمامية الآمنة حول الإجراء                                        | يحتاج UI إلى تشغيل نفس العملية التي ستجريها أداة الوكيل  |

يتم تصدير كل هذه العناصر من `@agent-native/core/client`.

<Diagram id="doc-block-aqmizx" title={"نموذج جبل"} summary={"<AgentSidebar> يغلف تخطيطك الحالي. يتم عرض مساراتك في المنطقة الرئيسية؛ يتم تركيب لوحة الوكيل بجانبهم. <AgentPanel> هي نفس اللوحة بدون الغلاف."}>

```html
<div class="diagram-mount">
  <div class="diagram-box sidebar" data-rough>
    <span class="diagram-pill accent">&lt;AgentSidebar&gt;</span>
    <div class="inner">
      <div class="diagram-node main">
        تطبيقك<br /><small class="diagram-muted"
          >children: header + &lt;Outlet/&gt;</small
        >
      </div>
      <div class="diagram-node panel">
        لوحة الوكيل<br /><small class="diagram-muted"
          >chat &middot; CLI &middot; resources</small
        >
      </div>
    </div>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
  <div class="diagram-card alt">
    <span class="diagram-pill">&lt;AgentPanel&gt;</span
    ><small class="diagram-muted"
      >same panel, no wrapper &mdash; you own the layout</small
    >
  </div>
</div>
```

```css
.diagram-mount {
  display: flex;
  align-items: center;
  gap: 14px;
  flex-wrap: wrap;
}
.diagram-mount .sidebar {
  display: flex;
  flex-direction: column;
  gap: 8px;
  padding: 14px;
}
.diagram-mount .inner {
  display: flex;
  gap: 10px;
}
.diagram-mount .main {
  flex: 2;
}
.diagram-mount .panel {
  flex: 1;
}
.diagram-mount .alt {
  display: flex;
  flex-direction: column;
  gap: 6px;
  padding: 14px;
}
.diagram-mount .diagram-arrow {
  font-size: 22px;
  line-height: 1;
}
```

</Diagram>

## حالة 80%: `<AgentSidebar>` {#sidebar}

الإعداد الأكثر شيوعًا هو الشريط الجانبي الذي يفتح من اليمين على أي شاشة.
قم بلف تخطيط الجذر الموجود لديك باستخدام `<AgentSidebar>`؛ مهما تم تمريره كـ
يبقى الأطفال في منطقة التطبيق الرئيسية. دردشة الوكيل هي اللوحة الجانبية.

<AnnotatedCode
  id="doc-block-1nt1prb"
  title={"تغليف تخطيط الجذر بـ <AgentSidebar>"}
  filename="app/root.tsx"
  language="tsx"
  code={
    'import { Outlet } from "react-router";\nimport { AgentSidebar, AgentToggleButton } from "@agent-native/core/client/agent-chat";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText="كيف يمكنني المساعدة؟"\n      suggestions={[\n        "Summarize my inbox",\n        "Draft a reply to the latest email",\n        "Show me yesterday\'s signup numbers",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position="right"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}'
  }
  annotations={[
    {
      lines: "6",
      label: "المجمع",
      note: "`<AgentSidebar>` wraps your whole layout. It adds the toggleable side panel; everything you pass as children stays in the main app area.",
    },
    {
      lines: "8-12",
      label: "يبدأ تشغيل المطالبات",
      note: "يتم عرض `suggestions` كشرائح قابلة للنقر في الدردشة الفارغة.",
    },
    {
      lines: "13",
      label: "شرائح تدرك السياق",
      note: '`dynamicSuggestions` merges screen-aware prompts (e.g. "Summarize this selection") with your static ones. On by default.',
    },
    {
      lines: "18-20",
      label: "زر التبديل",
      note: "Put `<AgentToggleButton />` anywhere in your header to open and close the panel.",
    },
    {
      lines: "22-24",
      label: "تطبيقك",
      note: "`<Outlet/>` (your routes) renders in the main area, untouched.",
    },
  ]}
/>

هذا كل شيء. أصبح لدى المستخدم الآن وكيل قابل للتبديل في كل صفحة - مع سجل الدردشة، وعلامة تبويب موارد الوكيل، ومحطة CLI، والإدخال الصوتي، ولوحة أوسع. تستمر الحالة عبر عمليات إعادة التحميل عبر `localStorage`.

### الدعائم

- **`children`** — التخطيط والمسارات العادية لتطبيقك. المقدمة في المنطقة الرئيسية. يتم تثبيت لوحة الوكيل بجانبها على سطح المكتب وفوقها على الهاتف المحمول.
- **`emptyStateText`** — تظهر الترحيب عندما لا تحتوي الدردشة على رسائل. الافتراضي: `"How can I help you?"`.
- **`suggestions`** — يتم عرض مطالبات البدء كشرائح قابلة للنقر عندما تكون فارغة.
- **`dynamicSuggestions`** — تم دمج شرائح المطالبة المدركة للسياق مع `suggestions`. ممكّن افتراضيًا؛ قم بتمرير `false` لعرض الاقتراحات الثابتة فقط، أو `{ max, includeStatic, getSuggestions }` للتخصيص.
- **`defaultSidebarWidth`** — عرض البكسل الأولي (للتثبيت فقط؛ تغيير حجم المستخدم وتجاوز القيمة المحفوظة). الافتراضي: `380`.
- **`position`** — `"left"` أو `"right"`. الافتراضي: `"right"`.
- **`defaultOpen`** — ما إذا كان الشريط الجانبي يبدأ مفتوحًا (سطح المكتب فقط). الافتراضي: `false`.

## الـ 20% الأخرى: `<AgentPanel>` {#panel}

عندما تحتاج إلى التحكم الكامل في التخطيط - مسار `/chat` مخصص، أو لوحة مضمنة في عمود جانبي تديره، أو نافذة منبثقة - قم بعرض `<AgentPanel>` مباشرةً:

```tsx
// app/routes/agent.tsx
import { AgentPanel } from "@agent-native/core/client/agent-chat";
export default function AgentRoute() {
  return (
    <div className="h-screen">
      <AgentPanel defaultMode="chat" className="h-full" />
    </div>
  );
}
```

يمنحك `<AgentPanel>` علامات التبويب الأولية (الدردشة / CLI / موارد الوكيل) بدون غلاف الشريط الجانبي، أو زر الطي، أو أي ثبات للحالة. ضعها أينما تريد؛ يمكنك التعامل مع التخطيط.

### الدعائم المحددة

- **`defaultMode`** — `"chat"` أو `"cli"`. الافتراضي: `"chat"`.
- **`className`** — فئة CSS للحاوية الخارجية.
- **`onCollapse`** — إذا تم توفيره، فسيظهر زر طي في الرأس.
- **`isFullscreen`** — اضبط هذا الخيار إذا كنت تريد عمودًا مركزيًا بنمط Claude لسطح صفحة أو لوحة مخصصة. يستخدم الشريط الجانبي اللوحة الأوسع بدلًا من ذلك.
- **`storageKey`** — مساحة الاسم لمفاتيح `localStorage`. يكون ذلك مفيدًا عند عرض لوحات متعددة (مثيلات تطبيق أو مساحات عمل مختلفة) في نفس الصفحة.

الدعائم الكاملة: `AgentPanelProps` في `@agent-native/core/client`.

## الرسائل البرمجية: `sendToAgentChat()` {#send}

زر يسلّم العمل إلى الوكيل بدلاً من إنشاء مسار AI منفصل عبر استدعاء `llm()` مضمن. راجع [لماذا نبني التطبيقات بهذه الطريقة](/docs/what-is-agent-native#why-build-apps-this-way) لمعرفة أهمية هذا الفرق:

```tsx
import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
<Button
  onClick={() =>
    sendToAgentChat({
      message: "Generate a chart showing signups by source",
      context: `Dashboard ID: ${dashboardId}, date range: last 30 days`,
      submit: true,
      openSidebar: true,
    })
  }
>
  Generate chart
</Button>;
```

### الخيارات

- **`message`** — المطالبة المرئية التي تظهر في الدردشة.
- **`context`** — سياق مخفي مُلحق بالموجه (النص المحدد، موضع المؤشر، معرف الكيان الحالي — أي شيء يجب أن يعرفه الوكيل ولكن لا ينبغي للمستخدم رؤيته مرتين).
- **`submit`** — `true` للتشغيل التلقائي، و`false` للتعبئة المسبقة ولكن انتظر. تجاهل استخدام المشروع الافتراضي.
- **`newTab`** — أنشئ سلسلة محادثات منفصلة لهذه المطالبة.
- **`background`** — مع `newTab`، قم بالتشغيل دون تركيز الخيط الجديد. يتم تتبع المسار المخفي في `RunsTray`.
- **`openSidebar`** — تم ضبطه على `false` للإرسال في الخلفية/الصامت. يفتح الإعداد الافتراضي الشريط الجانبي حتى يرى المستخدم الاستجابة.
- **للعمل المرئي الذي يبدأه المستخدم ويستخدم الذكاء الاصطناعي**، استخدم `openSidebar: true`. استخدم `false` فقط للعمل الصامت المحدد في الخلفية أو الذي يبدأه النظام، وأبقِ المتابعات في سلسلة AgentSidebar نفسها.
- **`type`** — يحتفظ `"content"` (افتراضي) بالعمل في وكيل التطبيق المضمن الذي يعمل من خلال أدوات التطبيق. يوجه `"code"` إلى مضيف منفصل قادر على التعامل مع الكود لإجراء تغييرات مصدر المستودع؛ ولا تتوفر الكتابة إلا عندما يمنح المضيف عمدًا أدوات repository/workspace. راجع [رمز Agent-Native UI](/docs/code-agents-ui).

يُرجع `sendToAgentChat` `tabId` مستقرًا يمكنك استخدامه لتتبع تشغيل الدردشة.

للعمل الصامت، قم بإقران `newTab` و`background` و`openSidebar: false`:

```ts
sendToAgentChat({
  message: "Summarize the selected thread and save the summary",
  context: `Thread id: ${threadId}`,
  submit: true,
  newTab: true,
  background: true,
  openSidebar: false,
});
```

لا يزال هذا وكيلًا كاملاً يتم تشغيله باستخدام الأدوات، وactions، وحالة مؤشر الترابط، والتشغيل
التتبع. إنه ببساطة لا يسرق التركيز من حالة الشريط الجانبي الحالية للمستخدم.
أبقِ مطالبات المتابعة والمراجعة في سلسلة الشريط الجانبي الحالية. لا تضف حقل إدخال حرًا ثانيًا بجانب النتيجة؛ استخدم نموذجًا محليًا فقط للقيم المنظمة التي يجب على الواجهة التحقق منها.

عندما يتم تضمين نفس المسار كتطبيق MCP، يتم إرساله
تتم إعادة توجيه مكالمات `sendToAgentChat()` إلى الدردشة المضيفة حيثما تكون مدعومة؛ انظر
[محادثة الوكيل](/docs/client-agent-chat#sendtoagentchat) لسلوك جسر تطبيق MCP.

إذا كنت تريد حالة تحميل، فاستخدم الخطاف `useSendToAgentChat()` - فهو يُرجع كلاً من `send` و`isGenerating`:

```ts
import { useSendToAgentChat } from "@agent-native/core/client/agent-chat";
const { send, isGenerating } = useSendToAgentChat();
```

## عندما لا يكون الشريط الجانبي للأسهم مناسبًا {#custom-chat-ui}

يغطي `<AgentSidebar>` و`<AgentPanel>` معظم التطبيقات. عندما تحتاج إلى امتلاك
التخطيط حول الوكيل، أو إذا كنت ترغب في تعزيز المحادثة مع الوكيل
الذي أنشأته في مكان آخر، قم بإسقاط طبقة - ولكن استمر في السماح لإطار العمل بامتلاك
وقت التشغيل، وactions، والحالة المدعومة SQL:

- **امتلك Chrome خلال وقت التشغيل القياسي.** استخدم `<AgentChatSurface>` لـ
  مسار دردشة مخصص، أو `<AssistantChat>` عندما تريد رؤوسًا مخصصة،
  والحالات الفارغة حول المحادثة القياسية. خريطة الطبقة الكاملة —
  يعيش كل مكون وخطاف وملحن ومحول مع مسارات الاستيراد في
  [Component API](/docs/components#agent-chat-ui).
- **إحضار وقت تشغيل الوكيل الخاص بك.** إذا كان ينبغي على الوكيل الذي أنشأته في مكان آخر
  دعم المحادثة بينما يحتفظ Agent-Native بالملحن والنص والأداة
  البطاقات والموافقات والأدوات الأصلية، قم بتمرير `AgentChatRuntime` إلى
  `<AssistantChat runtime={...} />`. الموصلات
  (`createHttpAgentChatRuntime()` وOpenAI / Claude / Vercel AI / AG-UI
  المساعدون) وعقد الحدث موثق في
  [Native واجهة الدردشة — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).

أيًا كانت الطبقة التي تختارها، احتفظ بحالة التطبيق المدعومة بـ actions وSQL كعقد،
وتجنب النشر مباشرة إلى `/_agent-native/agent-chat` من المنتج UI. إذا كان
المساعد المسمى مفقود لسطح مخصص حقيقي، قم بإضافة هذا المساعد أولاً لذلك
لا يتعلم كود العميل عملية نقل ثانية مخصصة.

## اختيار دردشة الوكيل مقابل الإجراء {#agent-or-action}

استخدم `useActionQuery` أو `useActionMutation` مباشرة للعمليات المحلية الحتمية مثل CRUD والتحقق وقراءة موفر البيانات والحفظ. إذا اختبر المستخدم سير العمل على أنه بحث أو تحليل أو إنشاء أو توصية أو تركيب أو استدلال متعدد الخطوات، فابدأه باستخدام `sendToAgentChat({ openSidebar: true })` ودع الوكيل ينسق الإجراءات المركزة. لا يكفي كون التنفيذ حتميًا لإخفاء سير عمل يشبه الذكاء الاصطناعي داخل إجراء واحد مبهم.

## Typesafe actions من UI: `useActionMutation()` {#use-action-mutation}

عندما تحتاج UI إلى تشغيل العملية نفسها التي قد تشغّلها أداة وكيل، استخدم [`useActionMutation`](/docs/client-data#use-action-mutation):

```tsx
import { useActionMutation } from "@agent-native/core/client/hooks";
const { mutate, isPending } = useActionMutation("reply-to-email");

<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
  Send Reply
</Button>;
```

تأتي وسائط النوع الآمن من مخطط zod في `defineAction()`. راجع [Actions](/docs/actions-overview) للتعرف على نظام العمل الكامل.

<Callout id="doc-block-1757zi5" tone="decision">

**`useActionMutation` vs `sendToAgentChat`.** Run the operation directly with `useActionMutation` when the user clicked a deterministic button ("Send reply"). Hand it to `sendToAgentChat` when the work needs the agent's reasoning, tools, or multi-step planning. Never call an inline `llm()` from UI; that creates a separate AI path instead of using the shared agent loop.

</Callout>

## التحديد + التعرف على المؤشر {#selection}

يمكن للوكيل رؤية ما حدده المستخدم - النص والخلايا والشرائح وجهات الاتصال - عبر مفتاحي `navigation` و`selection` في حالة التطبيق. تستخدم الدردشة الفارغة أيضًا هذه المفاتيح لتقديم اقتراحات ديناميكية مثل "تلخيص هذا التحديد" أو "تحسين هذه الشريحة" عندما تجعلها الشاشة الحالية ذات صلة. إذا كنت تريد من Cmd-I (أو ما شابه) إرسال نطاق محدد إلى الدردشة كسياق، راجع [Context Awareness](/docs/context-awareness).

## تجميع كل ذلك معًا {#putting-it-together}

الإعداد المنسدلة النموذجي:

```tsx
// app/root.tsx
import {
  AgentSidebar,
  AgentToggleButton,
  sendToAgentChat,
} from "@agent-native/core/client/agent-chat";
export default function Root() {
  return (
    <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>
      <Header>
        <AgentToggleButton />
      </Header>

      <Main>
        <YourRoutes />
      </Main>
    </AgentSidebar>
  );
}
```

```tsx
// Anywhere else in the app
<Button
  onClick={() =>
    sendToAgentChat({
      message: "Summarize this thread",
      context: `Thread id: ${threadId}`,
      submit: true,
      openSidebar: true,
    })
  }
>
  Summarize
</Button>
```

يرى المستخدم زر الدردشة في الرأس، ويمكنه فتحه، ويمكنه التحدث إلى الوكيل. تعمل أزرارك اليدوية مع نفس الوكيل بدلاً من إجراء مكالمات LLM لمرة واحدة.

## ما هي الخطوة التالية

- [**Actions**](/docs/actions-overview) — `defineAction()` و`useActionMutation()`
- [**Context Awareness**](/docs/context-awareness) — الاختيار، التنقل، شاشة العرض
- [**موارد الوكيل**](/docs/agent-resources) — ما تحتويه علامة تبويب موارد الوكيل (skills، الذاكرة، خوادم MCP، المهام المجدولة)
- [**Voice Input**](/docs/voice-input) — الميكروفون الموجود في مؤلف الدردشة
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall