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/harness-agents.mdx

View on GitHub
---
title: "وكلاء تسخير"
description: "قم بتشغيل Claude Code، وCodex، وPi، وغيرها من أدوات الترميز الكاملة كوكلاء مضمنين داخل Agent-Native، مع الحلقة الخاصة بهم، ووضع الحماية، والأدوات الأصلية، وجلسات SQL المدعومة القابلة للاستئناف."
search: "وكلاء تسخير AgentHarness ai-sdk رمز HarnessAgent Claude Codex Pi Cursor Mastra وكيل الترميز المضمن ResolveAgentHarness startAgentHarnessRun أدوات مضيف وضع الحماية للجلسة القابلة للاستئناف"
---

# وكلاء تسخير

> **من هو هذا:** المؤلفون المضيفون يقومون بتوصيل وقت تشغيل كامل للترميز (رمز Claude،
> Codex, Pi) إلى Agent-Native كوكيل. بناء التطبيق؟ ابدأ بـ
> [Creating Templates](/docs/creating-templates).

وكيل التسخير هو وقت تشغيل كامل للوكيل — رمز Claude، وCodex، وPi، وما شابه ذلك —
يمتلك حلقة خاصة به، ومساحة عمل، وأدوات ملفات أصلية، وحالة الجلسة، والضغط،
نموذج الموافقة وسلوك وضع الحماية. يقوم Agent-Native بتشغيل هذه من خلال
**`AgentHarness`** الركيزة في `@agent-native/core/agent/harness`، تتدفق
تدرج الأحداث في النص العادي، وتستمر في جلستها الأصلية بحيث تكون سلسلة رسائل
يمكن إيقافه مؤقتًا واستئنافه.

يختلف هذا عن وكيل الدردشة المدمج وعن إحضار الدردشة الخاصة بك
وقت التشغيل. الوكيل المدمج و`AgentEngine` مخصصان لنموذج واحد ذهابًا وإيابًا
أسفل `runAgentLoop`. الحزام ليس مزود `AgentEngine` - فهو يقوم بتشغيل
حلقة خاصة بها من البداية إلى النهاية، لذا فإن Agent-Native يقودها كجلسة، وليس كجلسة واحدة
استدعاء النموذج.

<Diagram id="doc-block-1q7je8a" title={"يمتلك الحزام حلقته. Agent-Native يقود الجلسة"} summary={"تقوم الركيزة AgentHarness creates/resumes بالجلسة الأصلية، بتدفق أحداثها إلى النص العادي، وتستمر في حالة الاستئناف في SQL بين المنعطفات."}>

```html
<div class="diagram-harness">
  <div class="diagram-box" data-rough>
    <strong>AgentHarness substrate</strong
    ><small class="diagram-muted">@agent-native/core/agent/harness</small>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-panel center" data-rough>
    <strong>Native harness loop</strong
    ><small class="diagram-muted"
      >Claude Code · Codex · Pi — own tools, sandbox, compaction</small
    >
  </div>
  <div class="diagram-col">
    <div class="diagram-pill accent">events &rarr; transcript</div>
    <div class="diagram-pill ok">resumeState &rarr; SQL session</div>
  </div>
</div>
```

```css
.diagram-harness {
  display: flex;
  align-items: center;
  gap: 14px;
  flex-wrap: wrap;
}
.diagram-harness .diagram-col {
  display: flex;
  flex-direction: column;
  gap: 8px;
}
.diagram-harness .diagram-arrow {
  font-size: 22px;
  line-height: 1;
}
.diagram-harness .center {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 4px;
}
```

</Diagram>

## ما هو مستند البرمجة الذي أريده؟ {#which-doc}

| تريد...                                                                        | استخدام                                      |
| ------------------------------------------------------------------------------ | -------------------------------------------- |
| تشغيل Claude Code / Codex / Pi **كوكيل**، باستخدام الحلقة + الأدوات الخاصة بهم | **وكلاء الاستفادة** (هذه الصفحة)             |
| عرض نمط Claude/Codex **مساحة عمل الترميز UI**                                  | [Agent-Native Code UI](/docs/code-agents-ui) |
| قم بتبديل الواجهة الخلفية التي تقوم بتشغيل **أداة `run-code`**                 | [Adapters](/docs/sandbox-adapters)           |
| قم بلف أداة CLI (`gh`، `ffmpeg`) ليتصل بها الوكيل                              | [Adapters](/docs/sandbox-adapters)           |

الأسطح المجاورة: ضع الوكيل الذي أنشأته في مكان آخر خلف دردشة Agent-Native
UI مع [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes)؛ دع
مكالمة مضيف MCP خارجية إلى تطبيقك عبر [External Agents](/docs/external-agents)؛
يتم تشغيل الخلفية/الوكيل الفرعي باستخدام [Custom Agents & Teams](/docs/agent-teams).

## أدوات مساعدة مدمجة {#built-in}

يسجل `registerBuiltinAgentHarnesses()` ثلاثة محولات مدعومة بـ AI SDK
`HarnessAgent`:

| الاسم                        | وقت التشغيل | وضع الحماية | الموافقات |
| ---------------------------- | ----------- | ----------- | --------- |
| `ai-sdk-harness:claude-code` | رمز Claude  | نعم         | نعم       |
| `ai-sdk-harness:codex`       | Codex       | نعم         | لا        |
| `ai-sdk-harness:pi`          | باي         | لا          | نعم       |

حزم وقت التشغيل الخاصة بها هي **تبعيات نظير اختيارية** ويتم تحميلها ببطء، لذا
التطبيق الذي لا يستخدم أداة التثبيت مطلقًا لا يدفع ثمنه. يحمل كل محول
تلميح `installPackage` (على سبيل المثال `@ai-sdk/harness@latest
@ai-sdk/harness-codex@latest`); `resolveAgentHarness` يُجري تثبيتًا واضحًا
خطأ إذا كانت الحزم مفقودة، و`isAgentHarnessPackageInstalled(entry)`
يتيح لك التحقق أولاً.

يسجل `registerBuiltinAgentHarnesses()` أيضًا أحزمة [ACP](#acp)
(`acp`, `acp:gemini`, `acp:claude-code`).

## وكلاء ACP {#acp}

يمكن أن يعمل Agent-Native كعميل [ACP](https://agentclientprotocol.com) (العميل
البروتوكول) **العميل** وقيادة وكيل الترميز المحلي — Gemini CLI، Claude Code،
أو أي وكيل متوافق مع ACP — من خلال نفس الركيزة. يعمل الوكيل باعتباره
عملية فرعية محلية تتحدث JSON-RPC مفصولة بسطر جديد عبر stdio؛ محرر ACP
↔ نموذج الوكيل هو هذا الشكل بالضبط.

تم تحديد نطاق هذا المحول لـ **الترميز المحلي**. ترث العملية الفرعية
البيئة الأصلية، لذلك يقوم الوكيل بإعادة استخدام أي معلومات تسجيل دخول CLI محلية لديه بالفعل
(على سبيل المثال، مصادقة `gemini` أو `claude` في الدليل الرئيسي للمستخدم). إنها ليست
نقل مستضاف أو في وضع الحماية، وهو ليس وسيلة نقل للدردشة/A2A - بالنسبة لهؤلاء،
راجع [Agent Surfaces](/docs/agent-surfaces).

| الاسم             | الأمر الافتراضي                                | قابل للاستئناف\* |
| ----------------- | ---------------------------------------------- | ---------------- |
| `acp`             | _(توريد `command`/`args` عبر التكوين)_         | نعم              |
| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp` | نعم              |
| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`       | نعم              |

\*تعمل السيرة الذاتية عندما يعلن الوكيل عن قدرة `loadSession` و
سيتدهور إلى جلسة جديدة.

```ts
import {
  registerBuiltinAgentHarnesses,
  resolveAgentHarness,
} from "@agent-native/core/agent/harness";

registerBuiltinAgentHarnesses();

// A built-in preset (command/args are overridable through the resolve config):
const adapter = resolveAgentHarness("acp:gemini");

// Or any ACP agent by command:
const custom = resolveAgentHarness("acp", {
  command: "gemini",
  args: ["--experimental-acp"],
});
```

يعد نقل البروتوكول (`@zed-industries/agent-client-protocol`) اختياريًا
يتم تحميل التبعيات ببطء من خلال تلميح `installPackage`، تمامًا مثل AI SDK
يسخر. الوكيل الثنائي نفسه (`@google/gemini-cli`،
`@zed-industries/claude-code-acp`,...) هو CLI خارجي منفصل؛ الإعدادات المسبقة
قم بتشغيله من خلال `npx` وسيظل الأمر/الوسائط قابلة للتجاوز لأن الوكيل ACP
لا تزال إشارات الإدخال تتطور.

يتم تعيين `permissionMode` إلى ACP `session/request_permission` باستخدام استدعاء الأداة
اكتب تقارير الوكيل: يتم تشغيل القراءات دائمًا، ويتم تشغيل التعديلات ضمن `allow-edits`، و
كل شيء محفوف بالمخاطر يطالب إلا `allow-all`. تظهر الموافقات كالمعتاد
أحداث `approval-request`. يخدم المحول `fs/read_text_file` و
`fs/write_text_file` مقابل مساحة عمل الجلسة (رفض المسارات التي تهرب
it) ويكتب أحداث `file-change`؛ لا يتم الإعلان عن الطرق الطرفية،
لذلك يستخدم الوكيل غلافه الخاص.

## مصادقة Codex: الكود UI مقابل محولات أدوات الحماية {#codex-auth}

هناك سطحان لـ Codex:

- **Agent-Native Code / Desktop** يقوم بتشغيل `codex exec` على جهاز المستخدم
  ويعيد استخدام تسجيل دخول Codex CLI المحلي الذي يبلّغ عنه `codex login status`.
- **`ai-sdk-harness:codex`** يستخدم تدفق اشتراك AI SDK Harness الأصلي حيثما كان
  مدعومًا. لا يلزم إعداد إضافي: تبقى بيانات الاعتماد على المضيف، وتأتي بيانات
  اعتماد مفتاح API الصريحة أولاً، ويتم تمرير المصادقة الناتجة إلى صندوق الحماية
  دون نسخ ملف المصادقة المحلي. عيّن `harnessOptions.auth` إلى `"ai-gateway"`
  لاستخدام AI Gateway فقط؛ هذا الوضع لا يقرأ اشتراكًا أصليًا.

يدعم محول `ai-sdk-harness:codex` المضمّن فقط
`permissionMode: "allow-all"`، لأن هذا هو الوضع الوحيد المقبول في إصدار Codex
المستقر. اترك `permissionMode` دون تحديد لاستخدام هذا الإعداد الافتراضي؛ يتم
رفض `allow-reads` و`allow-edits` لهذا المحول.

## التسجيل والحل {#register-resolve}

```ts
import {
  registerBuiltinAgentHarnesses,
  resolveAgentHarness,
} from "@agent-native/core/agent/harness";

registerBuiltinAgentHarnesses();
const adapter = resolveAgentHarness("ai-sdk-harness:codex");
```

ترجع `resolveAgentHarness(name, config?)` `AgentHarnessAdapter`. ال
تتم إعادة توجيه `config` الاختياري إلى مصنع المحولات — لمحولات AI SDK
الذي يتم تعيينه إلى `AiSdkHarnessAdapterOptions` (`label`، `description`،
`permissionMode`، و`harnessOptions`، و`agentOptions`). استخدم
`listAgentHarnesses()` لتعداد ما تم تسجيله من أجله منتقي.

بالنسبة إلى أحزمة Agent-Native المضمنة التي تستخدم صندوق حماية، مرر موفر صندوق
الحماية عبر `agentOptions.sandbox` عند تسجيلها. يجب أن يطبق الموفر
`resumeSession` لإعادة تهيئة الجلسة بعد إعادة تشغيل العملية؛ جلسة `sandbox` التي
يملكها المستدعي تغطي الإنشاء الأولي فقط.

## أجري دورة {#run-a-turn}

`startAgentHarnessRun` بتوصيل جلسة تسخير إلى مدير التشغيل المشترك
دورة الحياة. فهو ينشئ (أو يعيد استخدام) الجلسة الأصلية، ويستمر فيها، ويبث
يحول كل حدث تسخير ويترجمه إلى أحداث نصية ويفصل
حالة قابلة للاستئناف عند اكتمال الدور.

```ts
import { startAgentHarnessRun } from "@agent-native/core/agent/harness";

const run = startAgentHarnessRun({
  runId,
  threadId,
  adapter,
  input: { prompt },
  createSession: {
    sessionId,
    resumeState, // opaque value from a previous turn, if resuming
    instructions,
    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
    permissionMode: "allow-all",
    tools, // a narrow, intentional set of host tools (see below)
  },
  ownerEmail,
  orgId,
});
```

يرجع `startAgentHarnessRun` `ActiveRun` من مدير التشغيل، وبالتالي فإن الدور
يظهر من خلال مسارات التشغيل الحالية والنص والإلغاء تمامًا مثل
تشغيل أي وكيل آخر. قم بتمرير `session` الذي تم إنشاؤه بالفعل بدلاً من `createSession`
لمتابعة الجلسة التي تحتفظ بها في الذاكرة.

## الجلسات والاستئناف {#sessions}

يمتلك الحزام حالة جلسة أصلية طويلة الأمد. يستمر Agent-Native في SQL
حتى يتمكن الخيط من البقاء عبر المنعطفات والعمليات والنشر. `resumeState`
**غير شفاف** — يقوم Agent-Native بتخزينه وإعادته، ولكن لا يتم فحصه أو فحصه مطلقًا
يفسرها.

<Diagram id="doc-block-23lsu4" title={"الاستئناف عبر المنعطفات والعمليات والنشر"} summary={"يقوم كل دور بفصل حالة السيرة الذاتية المبهمة إلى SQL؛ المنعطف التالي يعيده مرة أخرى إلى createSession بدلاً من إعادة تشغيل سجل الدردشة."}>

```html
<div class="diagram-resume">
  <div class="diagram-node" data-rough>
    الدور N<br /><small class="diagram-muted">streamTurn</small>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-box" data-rough>
    detach &rarr; resumeState<br /><small class="diagram-muted"
      >معتم · جلسة حاضنة SQL</small
    >
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-node" data-rough>
    الدور N+1<br /><small class="diagram-muted"
      >createSession.resumeState</small
    >
  </div>
</div>
```

```css
.diagram-resume {
  display: flex;
  align-items: center;
  gap: 12px;
  flex-wrap: wrap;
}
.diagram-resume .diagram-arrow {
  font-size: 22px;
  line-height: 1;
}
```

</Diagram>

```ts
import {
  getLatestAgentHarnessSessionForThread,
  listAgentHarnessSessions,
} from "@agent-native/core/agent/harness";

const last = await getLatestAgentHarnessSessionForThread(threadId);
// Feed last?.resumeState into createSession.resumeState on the next turn.
```

يكشف المتجر أيضًا عن `saveAgentHarnessSession`، `updateAgentHarnessSession`،
`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
`markAgentHarnessSessionStopped`، و`ensureAgentHarnessSessionTables`.
`startAgentHarnessRun` يستدعي مسارات الحفظ/التحديث/الإيقاف نيابةً عنك؛ الوصول إليهم
مباشرة فقط في مضيف مخصص.

## أدوات وأذونات المضيف {#host-tools}

يجلب الحزام أدواته الأصلية (القراءة، والتحرير، والكتابة، والصدفة، وما إلى ذلك)، وهكذا
لا يمكنك **إعادة عرض تحرير الملفات كأدوات مضيفة. قم بتمرير **ضيق فقط،
المجموعة المقصودة\*\* من Agent-Native actions حتى `createSession.tools` عندما
تريد أن يصل الحزام إلى عمليات تطبيق معينة - واحتفظ بـ `defineAction`
المصادقة وسياق الطلب والمهلات والاقتطاع وبيانات التعريف للقراءة فقط سليمة عندما
أنت تفعل ذلك.

يحدد `permissionMode` ما قد يفعله الحزام دون موافقة:

| الوضع         | المعنى                                                               |
| ------------- | -------------------------------------------------------------------- |
| `allow-reads` | افتراضي. تشغيل القراءات؛ التعديلات ومطالبة actions المحفوفة بالمخاطر |
| `allow-edits` | تشغيل عمليات القراءة والتحرير؛ موجه actions الخطير الآخر             |
| `allow-all`   | لا توجد بوابة موافقة                                                 |

عندما يتوقف الحزام مؤقتًا للموافقة عليه، فإنه يصدر حدث `approval-request` و
تم وضع علامة `idle` على الجلسة مع تسجيل الموافقة المعلقة، لذا يمكن لـ UI
أبرزها واستأنفها بناءً على قرار المستخدم. انظر
[Human Approval](/docs/actions-access-control#needs-approval) لسطح الموافقة.

## الأحداث {#events}

تقوم جلسة تسخير ببث قيم `AgentHarnessEvent`، والتي Agent-Native
يترجم إلى دفق `AgentChatEvent` القياسي باستخدام
`agentHarnessEventToAgentChatEvents`. The event union covers `text-delta`,
`thinking-delta`، `activity`، `tool-start`، `tool-done` (والتي يمكنها حمل
حمولة `mcpApp` للأدوات الأصلية)، `approval-request`، `file-change`،
`compaction`، و`usage`، و`error`، و`done`. لأن نتائج الأداة تتدفق عبر
نفس الترجمة، ولا تزال الأدوات الأصلية التي تم الإعلان عنها عن إجراء تعرض - راجع
[Native واجهة الدردشة](/docs/native-chat-ui).

## يعمل في الخلفية وUI {#background-runs}

يقوم Harness بتشغيل المشروع في شكل `BackgroundAgentRun` المشترك مع
`createAgentHarnessBackgroundAgentController()` ومتاح من خلال
مسارات التشغيل الموجودة كـ `goalId=agent-harness`. وهذا يعني Claude طويل الأمد
تظهر جلسة التعليمات البرمجية أو Codex في نفس أسطح التشغيل في الخلفية والنص
مثل فرق الوكلاء والمحولات الأخرى، باستخدام `listAgentHarnessBackgroundRuns`،
`listAgentHarnessBackgroundTranscriptEvents`، `getAgentHarnessBackgroundRun`، و
`stopAgentHarnessBackgroundRun` متاح للمضيفين المخصصين.

## المحولات المخصصة {#custom-adapters}

لتغليف وقت تشغيل ليس أحد العناصر المضمنة، قم بتنفيذ
`AgentHarnessAdapter` وقم بتسجيله. يعلن المحول عن إمكانياته و
ينشئ جلسات؛ تعرض الجلسة `streamTurn` و`continueTurn` الاختيارية،
`approve`، و`detach`، و`stop`، و`destroy`.

```ts
import {
  registerAgentHarness,
  type AgentHarnessAdapter,
} from "@agent-native/core/agent/harness";

const myHarness: AgentHarnessAdapter = {
  name: "acme:my-coder",
  label: "Acme Coder",
  description: "Runs the Acme coding agent.",
  installPackage: "@acme/coder",
  capabilities: {
    sandbox: true,
    resumable: true,
    approvals: true,
    hostTools: true,
    fileEvents: true,
  },
  async createSession(opts) {
    // Build your native session and adapt it to AgentHarnessSession.
    return createAcmeSession(opts);
  },
};

registerAgentHarness({
  name: myHarness.name,
  label: myHarness.label,
  description: myHarness.description,
  installPackage: myHarness.installPackage,
  capabilities: myHarness.capabilities,
  create: () => myHarness,
});
```

احتفظ بحزمة وقت التشغيل اختيارية من خلال الاستيراد الديناميكي في `createSession` و
تلميح `installPackage`. بالنسبة إلى أدوات الترميز المدعومة بالجسر، يلزم وجود
موفر وضع الحماية/مساحة العمل بدلاً من تشغيل وكيل ترميز عشوائي في
عملية المضيف — راجع [Sandbox Adapters](/docs/sandbox-adapters). محول AI SDK
(`createAiSdkHarnessAdapter`، مدعوم بـ `HarnessAgent` من `@ai-sdk/harness`) هو
تنفيذ واحد لهذا العقد، وليس التجريد العام.

## لا تفعل ذلك {#donts}

- لا تقم بإضافة رمز Claude أو Codex أو Cursor أو Mastra أو Pi كـ `AgentEngine`. هم
  تملك الحلقة الخاصة بهم؛ يؤدي تشغيل واحدة تحت `AgentEngine.stream()` إلى تشغيل الحلقة بشكل مزدوج
  ويفقد دلالات دورة حياة الجلسة.
- لا تقم بإعادة تشغيل سجل الدردشة Agent-Native الكامل في كل دورة. استئناف
  جلسة الحزام باستخدام `resumeState` بدلاً من ذلك.
- لا تقم بتخزين `resumeState` في `application_state`. إنه ينتمي إلى الحزام
  جدول SQL للجلسة.
- لا تعرض كل إجراء من إجراءات التطبيق لكل جلسة استخدام بشكل افتراضي. سلمها
  مجموعة أدوات صغيرة ومتعمدة.

## المستندات ذات الصلة {#related-docs}

- [Native واجهة الدردشة](/docs/native-chat-ui) — ضع وكيلك الخاص خلف الدردشة UI مع `AgentChatRuntime`.
- [Agent Surfaces](/docs/agent-surfaces) - اختر التطبيق بلا رأس، أو الدردشة، أو السيارة الجانبية، أو التطبيق الكامل.
- [Agent-Native Code UI](/docs/code-agents-ui) — سطح مساحة عمل البرمجة القابلة لإعادة الاستخدام.
- [Custom Agents & Teams](/docs/agent-teams) — عمليات التشغيل في الخلفية وتفويض الوكيل الفرعي.
- [Sandbox Adapters](/docs/sandbox-adapters) — واجهات خلفية قابلة للتنفيذ لأدوات البرمجة.
- [Human Approval](/docs/actions-access-control#needs-approval) — يتم استخدام مجموعة أحزمة السطح المعتمدة.
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: 472kUpdated 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