--- title: 'ترحيل AG-UI 1.0: ما الذي يتعطل، وما الذي تم اختباره (2026)' description: 'تحديث AG-UI إلى الإصدار 1.0، وتم اختباره: يوضح هذا التحديث كيفية تعامل عميل الإصدار 1.0.1 مع تدفقات الإصدار 0.x، بالإضافة إلى نتيجة أداة الوسائط المتعددة التي تسببت في تعطل عميل الإصدار 0.x، وإصلاح لـ protocolVersion.' url: https://nerdleveltech.com/ar/ag-ui-1-0-migration-tested language: ar date: '2026-10-01' category: ai-ml tags: - ag-ui - ag-ui 1.0 migration - agent protocols - ai agents - copilotkit - typescript - python markdown_url: https://nerdleveltech.com/ar/ag-ui-1-0-migration-tested.md attribution: 'Source: NerdLevelTech — https://nerdleveltech.com/ar/ag-ui-1-0-migration-tested' terms: https://nerdleveltech.com/llms.txt --- # ترحيل AG-UI 1.0: ما الذي يتعطل، وما الذي تم اختباره (2026) **ملخص:** عملية الترحيل إلى AG-UI 1.0 آمنة إلى حد كبير، ولكن ليس في جميع الاتجاهات. في اختباراتي التي أجريتها في الأول من أكتوبر 2026، قبل عميل 1.0.1 كل تدفق بنمط 0.x أرسلته إليه، مع ترجمة الأشكال القديمة وتسجيل تحذير لكل منها.[^7] الاتجاه الآخر فشل مرة واحدة. عندما أرجع تدفق بنمط 1.0 نتيجة أداة تحتوي على جزء صورة، ألقى عميل 0.0.59 خطأ `ZodError` ولم ينتج عن التشغيل أي رسائل. يمكن إصلاح ذلك عن طريق إجراء فحص سريع لـ `protocolVersion` على الوكيل. هناك تغييران هادئان يحتاجان إلى نظرة قبل الترقية. الحقول المخصصة التي تضعها مباشرة على الأحداث تتم إزالتها الآن، وتضيف التدفقات القديمة `THINKING_*` الآن رسالة `reasoning` إلى سجل الدردشة الخاص بك. ## ترحيل AG-UI 1.0: ملخص AG-UI هو "بروتوكول مفتوح وخفيف الوزن وقائم على الأحداث يحدد كيفية اتصال وكلاء الذكاء الاصطناعي بالتطبيقات التي يواجهها المستخدم." إنه الطبقة بين الوكيل والمستخدم، بجانب MCP للأدوات و A2A للعمل بين الوكلاء.[^5] أعلنت CopilotKit عن AG-UI 1.0 في 30 سبتمبر 2026، قائلة: "AG-UI 1.0 متوافق مع الإصدارات السابقة، لذلك ستستمر الوكلاء والتطبيقات الحالية في العمل."[^1] تقول الدليل الرسمي للترحيل: "يستمر عمل وكيل 0.x مع عميل 1.0" و "يستمر عمل وكيل 1.0 مع عميل 0.x."[^2] لقد اختبرت هذا الادعاء باستخدام حزم npm الفعلية بدلاً من تكراره. الجدول أدناه هو النتيجة. ![مخرجات الطرفية لمصفوفة توافق AG-UI: ستة تدفقات مكتوبة تم تشغيلها في @ag-ui/client 0.0.59 و 1.0.1، مع نجاح جميع عمليات تشغيل 1.0.1 وتم وضع علامة FAIL على عملية تشغيل 0.0.59 الخاصة بـ multimodal-tool-result](https://nerdleveltech.com/images/ag-ui-1-0-compat-matrix.png) *المخرجات الفعلية لأداة الاختبار، التي تم تشغيلها في الأول من أكتوبر 2026 باستخدام Node 22.22.2. كل صف هو تدفق واحد يتم تشغيله في إصدار عميل واحد.*[^7] ## ما ستتعلمه - ما الذي تغير في AG-UI 1.0 ومتى تم إصدار الحزم - كيف اختبرت التوافق الرجعي لـ AG-UI باستخدام أداة إعادة التشغيل - ماذا يفعل عميل 1.0 مع أحداث THINKING إلى REASONING، والقيم الفارغة والحقول غير المعروفة - لماذا يمكن أن تتسبب نتائج أدوات AG-UI متعددة الوسائط في تعطل عميل 0.x، وإصلاح protocolVersion - التغييرات التي تسبب مشاكل في TypeScript و Python، بما في ذلك `@ag-ui/core/schemas` - قائمة تحقق للترقية وقيود هذه الاختبارات ## ما الذي تغير في AG-UI 1.0؟ AG-UI 1.0 هو الإصدار الأول الذي يحتوي على مواصفات مكتوبة، والآن يتم إنشاء أنواع البروتوكول لكل SDK من مخططها.[^2] يعلن Anmol Baranwal و Eli Berman عن خمس ميزات رئيسية: دعم الوكيل الفرعي، والبيانات الوصفية، ونتائج الأدوات متعددة الوسائط، والمقاطعات البشرية، واستخدام الرموز المميزة.[^1] تقول CopilotKit إن البروتوكول "معتمد من قبل Google و Microsoft و Amazon و Oracle، ويتم دعمه من قبل معظم أطر عمل الوكلاء، بما في ذلك LangChain و Mastra و Anthropic's Claude Managed Agents." هذا هو ادعاء البائع نفسه؛ لم أختبر أيًا من هذه التكاملات.[^1] تم إصدار الحزم قبل الإعلان. `@ag-ui/core`، `@ag-ui/client` و `@ag-ui/encoder` 1.0.0 تم نشرها على npm في 17 سبتمبر 2026، و 1.0.1 في 29 سبتمبر. كما تم نشر حزمة Python `ag-ui-protocol` 1.0.0 في 17 سبتمبر.[^6] تُدرج قائمة التغييرات في المواصفات القواعد الأكثر أهمية للتحديث:[^4] - "تتم إزالة الحقول الاختيارية، ولا يتم استخدام `null` أبدًا" - يتم تجاهل الأحداث غير المعروفة وإزالة الأعضاء غير المعروفة، "مع إظهار تحذير أثناء ذلك؛ والقيمة المعروفة غير الصحيحة هي خطأ قاتل" - "تم إيقاف أحداث `THINKING_*` 0.x لصالح عائلة التفكير" - يمكن للأداة "إرجاع مستند أو صورة أو نتيجة بحث دون ترميزها إلى سلسلة" يتم ترجمة الأشكال القديمة في الوقت الحالي، وليس إلى الأبد. تقول وثيقة الترحيل أن كل إصلاح توافق سينتهي صلاحيته، بشكل مؤقت بعد اثني عشر شهرًا من كتابته، "وبعد ذلك ستتوقف الأشكال التي تم إيقافها عن العمل تمامًا".[^2] ## كيف اختبرت توافق AG-UI مع الإصدارات السابقة قمت بتثبيت عميلين جنبًا إلى جنب: `@ag-ui/client` 0.0.59، وهو أحدث إصدار 0.x (تم نشره في 27 أغسطس 2026)، و 1.0.1.[^6] ثم كتبت وكيلًا وهميًا يعيد تشغيل دفق أحداث يتم إرساله من الخادم إلى `HttpAgent` الفعلي. ```bash mkdir v0 v1 harness (cd v0 && npm init -y && npm i @ag-ui/client@0.0.59 @ag-ui/core@0.0.59 @ag-ui/encoder@0.0.59) (cd v1 && npm init -y && npm i @ag-ui/client@1.0.1 @ag-ui/core@1.0.1 @ag-ui/encoder@1.0.1 zod) ``` يعيش كل دفق في `harness/streams.json`. إليك اثنان من ستة: وكيل قديم لا يزال يصدر أحداث `THINKING_*`، وواحد يضع حقولًا مخصصة مباشرة على أحداثه. ```json { "legacy-thinking": [ {"type":"RUN_STARTED","threadId":"t1","runId":"r1"}, {"type":"THINKING_START"}, {"type":"THINKING_TEXT_MESSAGE_START"}, {"type":"THINKING_TEXT_MESSAGE_CONTENT","delta":"Checking the weather tool..."}, {"type":"THINKING_TEXT_MESSAGE_END"}, {"type":"THINKING_END"}, {"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant"}, {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"Sunny."}, {"type":"TEXT_MESSAGE_END","messageId":"m1"}, {"type":"RUN_FINISHED","threadId":"t1","runId":"r1"} ], "unknown-prop": [ {"type":"RUN_STARTED","threadId":"t1","runId":"r1"}, {"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant","traceId":"abc-123"}, {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"hi","costUsd":0.0004}, {"type":"TEXT_MESSAGE_END","messageId":"m1"}, {"type":"RUN_FINISHED","threadId":"t1","runId":"r1"} ] } ``` تتضمن الأربعة تدفقات الأخرى `legacy-nulls` (`rawEvent`، `parentMessageId` و `result` تم تعيينها على `null`)، `metadata` (تم نقل نفس الحقول المخصصة إلى `metadata`)، `modern-reasoning` (أحداث `REASONING_*`) و `multimodal-tool-result` (نتيجة `TOOL_CALL_RESULT` التي يحتوي محتواها على جزء نصي بالإضافة إلى جزء صورة). يبدأ الوحدة الوهمية الوكيل الوهمي، ويشغل العميل ضده، ويطبع ما انتهى به الأمر في العميل: ```js // compat.mjs: replay a scripted SSE stream into an @ag-ui/client install. // Usage: node compat.mjs import http from "node:http"; import fs from "node:fs"; import { createRequire } from "node:module"; const [folder, name] = process.argv.slice(2); const streams = JSON.parse(fs.readFileSync(new URL("./streams.json", import.meta.url))); const require = createRequire(new URL(`../${folder}/package.json`, import.meta.url)); const { HttpAgent } = require("@ag-ui/client"); // 1. A fake agent that replays one stream and remembers what the client sent. let lastInput = null; const server = http.createServer(async (req, res) => { let body = ""; for await (const chunk of req) body += chunk; lastInput = JSON.parse(body); res.writeHead(200, { "content-type": "text/event-stream" }); for (const event of streams[name]) res.write(`data: ${JSON.stringify(event)}\n\n`); res.end(); }); await new Promise((resolve) => server.listen(0, resolve)); // 2. Run the real client against it, counting warnings instead of printing them. const warnings = []; console.warn = (...args) => warnings.push(args.join(" ")); const agent = new HttpAgent({ url: `http://localhost:${server.address().port}`, threadId: "t1" }); let status = "ok"; try { await agent.runAgent({ runId: "r1" }); } catch (err) { const issue = err.issues?.[0]; status = issue ? `FAIL: ${err.name} at ${issue.path.join(".")}: ${issue.message}` : `FAIL: ${err.message}`; } server.close(); console.log({ client: require("@ag-ui/client/package.json").version, stream: name, status, sentProtocolVersion: lastInput.protocolVersion ?? "(absent)", warnings: warnings.length, messages: agent.messages.map((m) => `${m.role}: ${JSON.stringify(m.content)}`), }); ``` قم بتشغيله كـ `node harness/compat.mjs v1 legacy-thinking`، وهكذا لكل دفق ومجلد عميل. ## ماذا يفعل العميل 1.0 مع وكيل 0.x قديم؟ يستمر في العمل. اكتملت جميع التدفقات الستة باستخدام عميل 1.0.1، وتم ترجمة كل شكل تم إيقافه مع تحذير في وحدة التحكم بدلاً من خطأ.[^7] | الدفق من الوكيل | عميل 0.0.59 | عميل 1.0.1 | | ------------------------------------ | ---------------------------------- | ------------------------------------------- | | أحداث `THINKING_*` | تم، لا يتم الاحتفاظ برسالة التفكير | تم، 5 تحذيرات، تم تحويلها إلى `REASONING_*` | | الحقول الاختيارية المعينة إلى `null` | تم، تم تمرير القيم الفارغة | تم، 3 تحذيرات، تمت إزالة القيم الفارغة | | الحقول المخصصة في الأحداث | تم، تم الاحتفاظ بالحقول | تم، 2 تحذيرات، **تمت إزالة الحقول** | | الحقول المخصصة ضمن `metadata` | تم | تم، تم الاحتفاظ بها | | أحداث `REASONING_*` | تم | تم | | جزء الصورة في نتيجة الأداة | **ZodError، فشل التشغيل** | تم | تفصيل واحد في الإخراج: أرسل 1.0.1 أيضًا `protocolVersion: "1.0"` في إدخال التشغيل، في حين أن 0.0.59 لم يرسل أي إصدار على الإطلاق. هذا الحقل الواحد هو الذي يدفع الإصلاح في وقت لاحق في هذا المنشور. ### أحداث التفكير إلى التفكير: يتغير تاريخك قام العميل 1.0.1 بتحويل كل واحد من أحداث `THINKING_*` الخمسة إلى ما يعادله `REASONING_*`. كان أول تحذير: "\[ag-ui]\[compat] يتم تحويل THINKING\_START القديم إلى REASONING\_START." التأثير الجانبي يظهر في `agent.messages`. مع 0.0.59، لم يتم الاحتفاظ بالنص الخاص بالتفكير، لذلك احتوت السجل فقط على `assistant: "Sunny."`. مع 1.0.1، احتوت السجل أيضًا على `reasoning: "Checking the weather tool..."`. [ثم يتم إرسال رسالة التفكير هذه مرة أخرى إلى الوكيل. في التكرار الثاني، أرسل العميل 0.0.59 أدوار الرسائل `assistant, user`، بينما أرسل العميل 1.0.1 `reasoning, assistant, user`.](#thinking-to-reasoning-events-your-history-changes)[^7] قبل نموذج Python في `ag-ui-protocol` 0.1.22 هذا الإدخال. ومع ذلك، إذا كانت وكيلك تقوم بتعيين السجل إلى تنسيق رسالة مزود النموذج، فتحقق من أنه يتعامل مع دور `reasoning` قبل الترقية إلى الواجهة الأمامية. ### يتم الآن إزالة الخصائص غير المعروفة في AG-UI هذا هو التغيير الذي سأتحقق منه أولاً، لأنه يفشل بصمت. أرسل تدفق البيانات الخاص بي `traceId` و `costUsd` مباشرةً في أحداث رسائل النص. قام العميل 0.0.59 بتمريرها إلى المشتركين؛ قام 1.0.1 بإزالتها. كان التحذير: "\[ag-ui]\[enforce] تمت إزالة المادة غير المعروفة في '/traceId' على TEXT\_MESSAGE\_START." نجح التشغيل، لذلك ستحصل واجهة المستخدم التي تقرأ `event.traceId` ببساطة على `undefined`. تقول الإرشادات الخاصة بالترحيل "القناة المعتمدة للبيانات الإضافية هي `metadata`"، والتي "لا تتم إزالتها أبدًا". ينطبق نفس القاعدة على المفاتيح غير المعروفة التي ترسلها في إدخال التشغيل؛ تشير الإرشادات إلى `forwardedProps` لذلك.[^2] عندما قمت بنقل نفس الحقلين إلى `metadata`، احتفظ كلا العميلين بهما، دون أي تحذيرات. ### تصبح القيم الفارغة حقولًا مفقودة قام العميل 1.0.1 بتحويل `rawEvent: null` و `parentMessageId: null` و `result: null` إلى حقول مفقودة، مع تحذير واحد لكل منها.[^7] يقوم مُشفّر 1.0.1 أيضًا بإزالة القيم الفارغة في طريقه للخارج: أدى ترميز `RUN_FINISHED` مع `result: null` إلى عدم وجود مفتاح `result`، بينما كتب مُشفّر 0.0.59 `"result":null`. إذا كانت الواجهة الأمامية الخاصة بك تتحقق من `event.result === null`، فقم بتغييرها إلى `event.result == null` أو `!("result" in event)`. ## لماذا يمكن أن تتسبب نتائج أدوات AG-UI متعددة الوسائط في تعطل عميل 0.x؟ لأن العميل 0.0.59 لا يزال يتوقع أن يكون محتوى نتيجة الأداة عبارة عن سلسلة. عندما أرجع تدفق البيانات الخاص بي جزءًا نصيًا وجزء صورة، فشل العميل 0.0.59 مع `ZodError at content: Expected string, received array`، ولم يتم الاحتفاظ بأي رسائل.[^7] كان هذا هو التدفق الوحيد في اختباراتي حيث أدى وكيل ذو شكل 1.0 إلى تعطيل عميل أقدم. تعتبر نتائج الأدوات متعددة الوسائط واحدة من الميزات الرئيسية لـ 1.0، لذلك فهي حالة سهلة الحدوث.[^1] تذكر قائمة الإرشادات الخاصة بالترحيل بالإضافات 1.0 التي يمكن لعميل 0.x تجاهلها `RUN_FINISHED.outcome`، وأحداث الوكيل الفرعي، و `protocolVersion`، وأحداث النشاط. لا تذكر محتوى نتيجة الأداة.[^2] تغطي مواصفات الإصدار هذا. كلا حقلي الإصدار اختياريان "لأن الغياب يعني شيئًا: يشير إلى أن نظيرًا من فترة سابقة للبروتوكول كان لديه إصدار"، و"يجب أن يرسل تطبيق هذا الإصدار إعلانه".[^3] ويقول أيضًا: "يجوز للطرف الذي يعرف أن نظيره أقدم ترجمة الدفق إلى شكل يفهمه النظير"، و"يجب أن يصدر التخفيض التدريجي الذي يؤدي إلى فقدان البيانات تحذيرًا يوضح ما تم فقده ولماذا".[^3] ## تصحيح protocolVersion لأدوات AG-UI متعددة الوسائط تحقق من `protocolVersion` في مدخل التشغيل الوارد. إذا كان مفقودًا، قم بتسطيح نتيجة الأداة باستخدام `contentToText` من `@ag-ui/core` قبل إرسالها، وسجل ما قمت بإزالته. احفظ هذا كـ `v1/agent.mjs` بحيث يستخدم حزم 1.0.1. ```js // agent.mjs: a minimal AG-UI 1.0 agent that stays safe for pre-1.0 clients. import http from "node:http"; import { EventEncoder } from "@ag-ui/encoder"; import { EventType, PROTOCOL_VERSION, contentToText, contentHasMedia } from "@ag-ui/core"; const chartResult = [ { type: "text", text: "Chart attached" }, { type: "image", source: { type: "url", value: "https://example.com/c.png", mimeType: "image/png" } }, ]; export function startAgent(port = 0) { const server = http.createServer(async (req, res) => { let body = ""; for await (const chunk of req) body += chunk; const input = JSON.parse(body); // A 1.0 client declares protocolVersion on every RunAgentInput. Absent = pre-1.0 peer. const peerSpeaks1 = typeof input.protocolVersion === "string"; const enc = new EventEncoder({ accept: req.headers.accept }); res.writeHead(200, { "content-type": enc.getContentType() }); const send = (e) => res.write(enc.encode(e)); send({ type: EventType.RUN_STARTED, threadId: input.threadId, runId: input.runId, protocolVersion: PROTOCOL_VERSION }); send({ type: EventType.TOOL_CALL_START, toolCallId: "c1", toolCallName: "render_chart" }); send({ type: EventType.TOOL_CALL_END, toolCallId: "c1" }); let content = chartResult; if (!peerSpeaks1 && contentHasMedia(content)) { // Spec: a lossy downgrade MUST warn, naming what was lost and why. const dropped = content.filter((part) => part.type !== "text").map((part) => part.type); console.warn(`[agent] client sent no protocolVersion (pre-1.0): dropped ${dropped.join(", ")} part(s) from tool result c1`); content = contentToText(content); } send({ type: EventType.TOOL_CALL_RESULT, messageId: "tm1", toolCallId: "c1", role: "tool", content }); send({ type: EventType.RUN_FINISHED, threadId: input.threadId, runId: input.runId }); res.end(); }); return new Promise((resolve) => server.listen(port, () => resolve(server))); } ``` `@ag-ui/encoder` 1.0.1 لن يقوم بذلك نيابة عنك: لم تقم التعليمات البرمجية المنشورة بها مطلقًا باستدعاء `contentToText`، لذلك يجب أن يكون لديك وكيل مكتوب يدويًا.[^7] يقوم الوكيل أيضًا بتعيين `protocolVersion` على `RUN_STARTED`. تقول ملاحظات Python SDK أنه "لا يقوم بتعيينها نيابة عنك"، لذا قم بتمرير `PROTOCOL_VERSION` بنفسك في أي من اللغتين.[^8] لاختبار ذلك، قمت بتوجيه كل عميل إلى هذا الوكيل: ```js // run-fixed.mjs, in the harness folder. Usage: node run-fixed.mjs import { createRequire } from "node:module"; import { startAgent } from "../v1/agent.mjs"; const ver = process.argv[2]; const require = createRequire(new URL(`../${ver}/package.json`, import.meta.url)); const { HttpAgent } = require("@ag-ui/client"); const server = await startAgent(); const agent = new HttpAgent({ url: `http://localhost:${server.address().port}/`, threadId: "t1" }); try { await agent.runAgent({ runId: "r1" }); const tool = agent.messages.find((m) => m.role === "tool"); console.log(`${ver} client -> tool message content:`, JSON.stringify(tool.content)); } catch (e) { console.log(`${ver} client -> FAILED:`, e.message.split("\n")[0]); } server.close(); ``` العميل 0.0.59 الآن حصل على سلسلة نصية بسيطة `"Chart attached"`، وسجل الوكيل أنه قام بإزالة جزء الصورة. لا يزال العميل 1.0.1 يحصل على المصفوفة الكاملة التي تحتوي على النص والصورة.[^7] ![مخرجات الطرفية لـ run-fixed.mjs: يحذر الوكيل أنه قام بإزالة جزء الصورة لعميل لا يحتوي على protocolVersion، ويتلقى العميل 0.0.59 السلسلة Chart attached، ويتلقى العميل 1.0.1 الأجزاء النصية والصورة](https://nerdleveltech.com/images/ag-ui-1-0-downgrade-fix.png) *المخرجات الفعلية للوكيل الثابت مع كلا إصداري العميل، 1 أكتوبر 2026.*[^7] ## التغييرات الجذرية في TypeScript: @ag-ui/core/schemas والوحدات ذات الصلة الجانب الخاص بالعميل من الواجهة متسامح. واجهات برمجة التطبيقات للحزم ليست كذلك، لذا توقع حدوث أخطاء في التجميع والاستيراد في التعليمات البرمجية التي استخدمت أدوات التحقق أو أسماء الأنواع القديمة. ### تم نقل أدوات التحقق إلى @ag-ui/core/schemas يصدر جذر `@ag-ui/core` 1.0.1 12 اسمًا، مقارنة بـ 102 في 0.0.59. تم نقل مخططات Zod إلى مسار فرعي.[^2][^7] في وحدة ES، يفشل الاستيراد القديم قبل تشغيل أي تعليمات برمجية: ```text SyntaxError: The requested module '@ag-ui/core' does not provide an export named 'EventSchemas' ``` الحل هو سطر واحد: ```js import { EventSchemas } from "@ag-ui/core/schemas"; const ok = EventSchemas.safeParse({ type: "TEXT_MESSAGE_CONTENT", messageId: "m1", delta: "hi" }); const old = EventSchemas.safeParse({ type: "THINKING_START" }); console.log("valid event:", ok.success, "| THINKING_START:", old.success); // valid event: true | THINKING_START: false ``` تم أيضًا نقل Zod. في `@ag-ui/core` 0.0.59 كان تبعية عادية (`^3.22.4`); في 1.0.1 هو تبعية نظيرة (`^3.25.18 || ^4.0.0`).[^7] تقول الإرشادات أن استيراد أدوات التحقق "يتطلب zod"، لذا أضف `zod` بنفسك إذا كنت تستخدم `@ag-ui/core/schemas`. لا تزال `@ag-ui/client` تعتمد على zod مباشرةً.[^2] ### الأسماء التي تم تغيير اسمها وإيقافها تحول مُحَدَّد `EventType` من 36 عنصرًا إلى 31: اختفت القيم الخمسة `THINKING_*`.[^7] يسرد الدليل التغييرات، بما في ذلك:[^2] - `SubAgentInfo` → `SubagentInfo`، و`multiAgent.subAgents` → `subagents` - `InputContent` → `ContentPart`، `TextInputContent` → `TextPart`، `ImageInputContent` → `ImagePart` - `AbstractAgent.maxVersion` → `maxProtocolVersion` (الاسم القديم مُعَلَّق) - تم إيقاف `BinaryInputContent` لصالح أجزاء الصورة والصوت والفيديو والمستندات ## تغيير مُكسِّر في Python: عمليات JSON Patch مُعطَّاة بنوع في `ag-ui-protocol` 1.0.0، تكون الإدخالات في `StateDeltaEvent.delta` نماذج عمليات مُعطَّاة بنوع، وليست قوائم.[^2] قمت بإنشاء نفس الحدث باستخدام الإصدارين 0.1.22 و1.0.0: ```python from ag_ui.core import StateDeltaEvent, EventType event = StateDeltaEvent(type=EventType.STATE_DELTA, delta=[{"op": "replace", "path": "/temp", "value": 21}]) op = event.delta[0] print(type(op).__name__) for label, read in [("op.path", lambda: op.path), ('op["path"]', lambda: op["path"])]: try: print(label, "->", read()) except Exception as err: print(label, "->", type(err).__name__, err) ``` في الإصدار 0.1.22، كان `op` من نوع `dict` و`op.path` أثار `AttributeError`. أما في الإصدار 1.0.0، فقد كان `op` من نوع `ReplaceOperation`، و`op["path"]` أثار `TypeError: 'ReplaceOperation' object is not subscriptable`.[^7] ابحث في عاملك عن `delta[` و`patch[` قبل الترقية. إذا احتاجت مكتبة إلى قوائم عادية، يوضح الدليل تحويل كل إدخال باستخدام `model_dump(by_alias=True)`.[^2] لم يُكسَّر شيئان. قَبِلَ `RunAgentInput` في الإصدار 0.1.22 الحقل الجديد `protocolVersion` (وأزاله)، وكان مُشفِّره يُهمِل بالفعل الحقول الاختيارية غير المُحدَّدة. يذكر الدليل أن معالجة الحقول المفقودة صدرت في Python 0.1.20.[^2][^7] ## قائمة مراجعة الترقية إلى AG-UI 1.0 1. **قم بترقية عميل الواجهة الأمامية أولًا.** في اختباراتي، تمكن عميل 1.0.1 من التعامل مع كل تدفقات 0.x، مع تحذيرات. 2. **انقل حقول الأحداث المخصصة تحت `metadata`.** يُزيل العميل 1.0 الحقول غير المعروفة. 3. **تحقق من معالجة السجل الخاص بك لرسائل `reasoning`** إذا كان عاملك لا يزال يُصدر أحداث `THINKING_*`. 4. **استبدل فحوصات `=== null`** على الحقول الاختيارية بفحوصات الغياب. 5. **غيّر استيرادات المُحقِّقين إلى `@ag-ui/core/schemas`** وأضف `zod` كاعتماد خاص بك إذا كنت تستخدمها. 6. **في Python، استبدل `patch["path"]` بـ `patch.path`.** 7. **قبل أن يُرجع العامل أجزاء صورة أو صوت أو فيديو أو مستند، تحقق من `protocolVersion`** وقم بتبسيطها للعملاء الذين لا يرسلونها. 8. **أرسل `protocolVersion` بنفسك عند `RUN_STARTED`.** إذا كان عاملك يعمل خلف خطوة موافقة بشرية، فربما يستحق أيضًا التحقق من نتيجة المقاطعة الجديدة. يغطي دليلي [عن التكامل البشري في الحلقة لـ Claude Agent SDK](https://nerdleveltech.com/human-in-the-loop-claude-agent-sdk-typescript-tutorial) نمط الموافقة من جانب العامل. ## حدود هذه الاختبارات هذه اختبارات على مستوى البروتوكول باستخدام عامل مُزيف مُبرمَج، وليس نموذجًا حقيقيًا. لقد اختبرت عميلًا واحدًا من 0.x (0.0.59، آخر إصدار من 0.x) وعميلًا واحدًا من 1.0 (1.0.1). قد يتصرف عملاء 0.x الأقدم بشكل مختلف. لم أختبر SDK الخاص بـ .NET أو تكاملات الإطار أو أحداث أو تدخلات الوكلاء الفرعية عبر الإصدارات. المطالبات المتعلقة بالاعتماد في هذه المقالة تخص CopilotKit، وليست لي. ## الأسئلة الشائعة ### هل AG-UI 1.0 متوافق مع الإصدارات السابقة؟ بشكل كبير. في اختباراتي، قبل عميل الإصدار 1.0.1 كل تدفق من نمط 0.x مع تحذيرات. فشل عميل الإصدار 0.0.59 في معالجة نتيجة أداة متعددة الوسائط من الإصدار 1.0، لذا يجب على وكلاء الإصدار 1.0 التحقق من `protocolVersion` قبل إرسال أجزاء الوسائط.[^7] ### ماذا يتعطل عند الترقية إلى AG-UI 1.0؟ على مستوى النقل، يتم إزالة الحقول المخصصة المضافة مباشرةً على الأحداث، وتصبح القيم الفارغة حقولًا غير موجودة. في الكود، تنتقل المدققات إلى `@ag-ui/core/schemas`، ويتم إزالة أنواع الأحداث `THINKING_*`، وأُعيد تسمية عدة أنواع، وأصبحت إدخالات Python JSON Patch كائنات مُعرَّفة النوع.[^2][^7] ### ماذا حدث لأحداث THINKING في AG-UI 1.0؟ تم إيقافها لصالح عائلة `REASONING_*`.[^4] لا يزال عميل الإصدار 1.0.1 يحول أحداث `THINKING_*` الواردة، مع تحذير واحد لكل حدث، ويحتفظ بالنص كرسالة `reasoning`.[^7] ### كيف يعرف وكيل AG-UI إصدار العميل؟ يرسل عميل الإصدار 1.0 `protocolVersion` في كل مدخل تشغيل؛ وأرسل الإصدار 1.0.1 `"1.0"`. يعني غياب القيمة أن الطرف الآخر يسبق نظام الإصدارات.[^3][^7] ### أين يجب وضع البيانات المخصصة على أحداث AG-UI؟ في حقل `metadata`. يوصي دليل التحويل بذلك، وفي اختباري حافظ كلا العميلين على الحقول المضافة هناك.[^2][^7] ### كيف ترتبط AG-UI بـ MCP وA2A؟ تضبط وثائق AG-UI AG-UI بين الوكيل والمستخدم، وMCP بين الوكيل وأدواته وبياناته، وA2A بين الوكلاء.[^5] لمعرفة المزيد عن الطبقتين الأخريين، راجع [برنامج تعليمي حول إضافة MCP Tasks](https://nerdleveltech.com/mcp-tasks-extension-tutorial) و[برنامج تعليمي بروتوكول A2A باستخدام Python](https://nerdleveltech.com/a2a-protocol-python-tutorial). يغطي منشور [معايير بروتوكول وكيل IETF](https://nerdleveltech.com/ietf-ai-agent-protocol-standard-agentproto) الاتجاهات المستقبلية لهذه البروتوكولات. ## الخلاصة إن عملية التحويل إلى AG-UI 1.0 أسهل إذا بدأت بالواجهة الأمامية. لقد قام عميل الإصدار 1.0.1 بتحويل كل تدفق قديم أرسلته له، والتحذيرات توضح لك بالضبط ما يجب تنظيفه. يظل هناك خطران. الحقول المخصصة التي ليست تحت `metadata`\_\_PRESERSEVERE\_\_ تختفي بدون ظهور خطأ، كما أن العميل من إصدار 1.0 الذي يرسل أجزاء وسائط يمكن أن يتسبب في تعطل عميل من إصدار 0.x. قم بنقل الحقول، وأضف فحص `protocolVersion` قبل شحن نتائج الأدوات متعددة الوسائط (multimodal tool results). [^7]: Author's measurement, October 1, 2026: Node 22.22.2 and Python 3.11.15; `@ag-ui/client`, `@ag-ui/core` and `@ag-ui/encoder` 0.0.59 and 1.0.1 installed from npm; `ag-ui-protocol` 0.1.22 and 1.0.0 installed from PyPI into separate virtual environments. Export counts, the `EventType` member count and the Zod dependency entries were read from the installed packages. All code in this post was run as shown, after extracting it from the finished post into a fresh folder. The second-turn history check and the null-encoding check used two small extra scripts in the same setup. [^5]: [AG-UI Overview — Agent User Interaction Protocol docs](https://docs.ag-ui.com/introduction), fetched 2026-10-01. [^1]: [Introducing AG-UI 1.0: a stable spec for connecting any agent to any application — CopilotKit](https://www.copilotkit.ai/blog/ag-ui-1.0), by Anmol Baranwal and Eli Berman, published September 30, 2026, fetched 2026-10-01. [^2]: [Migrating to 1.0 — Agent User Interaction Protocol docs](https://docs.ag-ui.com/migrating-to-1-0), fetched 2026-10-01; quotations checked against the page source, `docs/migrating-to-1-0.mdx` on the ag-ui-protocol/ag-ui GitHub main branch, read the same day. [^6]: Publish dates from the npm registry (`npm view @ag-ui/core time`, and the same for `@ag-ui/client` and `@ag-ui/encoder`) and from [PyPI's JSON API for ag-ui-protocol](https://pypi.org/pypi/ag-ui-protocol/json), checked 2026-10-01. [^4]: [Key Changes — AG-UI 1.0 spec](https://docs.ag-ui.com/spec/1.0/changelog), fetched 2026-10-01; quotations checked against `docs/spec/1.0/changelog.mdx` on GitHub main. [^3]: [Versioning and Compatibility — AG-UI 1.0 spec](https://docs.ag-ui.com/spec/1.0/basic/versioning), fetched 2026-10-01; quotations checked against `docs/spec/1.0/basic/versioning.mdx` on GitHub main. [^8]: `ag_ui/core/version.py` in `ag-ui-protocol` 1.0.0, read after installing from PyPI on 2026-10-01.