openApiTools()
يحوّل المستند إلى tool واحد typed لكل عملية في الـ API، فيقدر الـ agent
يستدعي الـ API بدون defineTool() مكتوبة يدويًا لكل endpoint وبدون
الـ http tool الخام. والعمليات التي تغيّر
البيانات تطلب approval (موافقة) افتراضيًا.
openApiTools مُصدَّرة من lousho ومن
lousho/tools. لا تحتاج إلى أي حزمة إضافية. بادئة الموديل
vendor/ هي التي تحدد الـ provider؛ ومع OpenRouter استخدم
openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini).
بداية سريعة
openApiTools() دائمًا async، لأن المستند قد يكون URL. تُرجع array من
tools تمرّرها إلى createAgent({ tools }) مثل أي tools أخرى.
document يمكن أن يكون object مُفسَّرًا لـ OpenAPI 3.0 أو 3.1، أو string بصيغة
JSON أو YAML، أو https URL (string أو URL). openApiTools() تحلّل
المستند مرة واحدة؛ أما execute في الـ tool فلا تفعل إلا بناء الطلب
وإرساله.
شكل كل tool
معاملات الـ header
Accept وContent-Type وAuthorization تُتجاهل كما
تنص مواصفة OpenAPI؛ استخدم bearerToken أو headers لبيانات الاعتماد.
الخيارات
و
op هو { name, operationId?, method, path, summary?, tags }.
افتراضيات الـ approval
معapproval: 'mutating'، تعمل GET وHEAD وOPTIONS مباشرة، وكل method أخرى
تطلب approval. وكل tool يحمل أيضًا annotations بأسلوب MCP:
readOnlyHint: true, destructiveHint: false على GET وHEAD وOPTIONS؛
وreadOnlyHint: false على الباقي، مع destructiveHint: true لـ DELETE.
وأي شيء يقرأ الـ annotations يعامل هذه الـ tools كما يعامل tools الـ MCP.
القيم التي يزوّدها تطبيقك
providedArguments تملأ الـ parameters التي لا يجب أن يختارها الـ model،
مثل tenant id. المفتاح المزوَّد يُحذف من الـ input schema الخاصة بالـ tool
(فالـ model لا يراه أبدًا) ويُضاف إلى الطلب. ويمكن أن تكون القيمة دالة،
تُستدعى لكل طلب مع العملية ومعرّف الـ tool call.
<in>_<name>
(مثل query_id) عندما يتشارك اثنان من الـ parameters في العملية الواحدة
الاسم نفسه؛ ومفتاح جسم الطلب هو body (أو requestBody عندما يكون
parameter قد أخذ body من قبل). والمفتاح الذي لا تمتلكه أي عملية مُختارة
يرمي خطأً، فلا يؤدي خطأ مطبعي إلى كشف الـ parameter للـ model بصمت.
قواعد الأمان
- الـ base URL لك أنت، لا للـ model. الـ model يختار قيم الـ parameters
والـ body؛ ولا يختار الـ host أبدًا. يجب أن يكون الـ base URL https. ولا
يُقبل http العادي إلا لـ
localhostو127.0.0.1و[::1]، وأي URL فيه اسم مستخدم أو كلمة مرور يُرفض. ونفس القاعدة تنطبق على URL المستند. - بيانات الاعتماد لا تصل إلى ما يراه الـ model وسجلاتك. الـ headers
والـ tokens لا تدخل أبدًا في الـ input schema الخاصة بالـ tool، ولا في
حدثي
tool.startوtool.done، ولا في الـ transcript؛ فقط input الـ model نفسه والاستجابة. والـ header الذي يزوّده الـ model لـ header parameter مُصرَّح به لا يحل محلheadersأوbearerTokenأبدًا. - الـ redirects تبقى على origin الـ base URL. الطلبات تستخدم redirects يدوية: يُتبَع 3 على الأكثر، وفقط إلى نفس الـ origin الخاص بالـ base URL. والـ redirect إلى origin آخر هو خطأ tool، فالـ token لا يغادر الـ origin المُعَدّ أبدًا.
- قيم الـ path تبقى داخل المقطع الخاص فيها. معاملات الـ path تُرمَّز
percent-encoded (فلا يستطيع
../adminالخروج من مقطعه)، والقيمة التي تساوي.أو..تمامًا تُرفض. - العناوين الخاصة: لا فحص افتراضيًا، و
privateAddresses: 'refuse'يفعّله. افتراضيًا الـ tools تنادي الـ base URL الذي أعددته أنت، أينما حُلّ: عناوين الـ base لك وغالبًا داخلية. وعندما لا يكون الـ base URL أو URL المستند تحت سيطرتك الكاملة (اسم يجيب عليه DNS شخص آخر، أو مستند تجلبه من مكان آخر)، مرّرprivateAddresses: 'refuse'. عندها يُرفض كل طلب operation وجلب المستند، بما فيها كل hop في الـ redirect، إذا كان الـ host عنوانًا أو يُحل إلى عنوان loopback أو link-local أو خاص أو shared أو multicast أو محجوز (نفس القائمة التي يستخدمهاhttp_request، بما فيها NAT64 و6to4). أسماء الـ hosts تُفحص بنفس الـ DNS lookup المثبَّت الذي يستخدمهhttp_requestوweb_fetch: الـ host يُحل مرة واحدة لكل اتصال، وكل عنوان يُفحص، والـ socket يتصل بالعنوان الذي فُحص، فاسم DNS-rebinding (عام للفحص، و127.0.0.1للاتصال) لا يصل إلى عنوان خاص أبدًا. والـ IP literals بأي صيغة يقبلهاURL(2130706433،0x7f000001،0177.0.0.1،[::ffff:127.0.0.1]) وأسماءlocalhost/*.localhostتُرفض عند إنشاء الـ tools، كـConfigurationError. الـ model لا يستطيع نقل طلب إلى host آخر: قيم الـ path تُرمَّز percent-encoded داخل مقطعها، ومتغيرات server URL تأخذ فقط القيم الافتراضية للمستند، والـ redirects تبقى على origin الأساس. ضع الـ hosts الداخلية الخاصة بك فيallowPrivate(allowPrivate: ['localhost']لواجهة محلية). والطلب المرفوض هو خطأ tool يذكر الـ host، ولا يذكر أبدًا العناوين التي حُلّ إليها.'refuse'لا يمكن دمجه معfetch: الـfetchالمخصصة تحل الأسماء بنفسها، فلا يستطيع الفحص تثبيت العنوان الذي تتصل به، وإنشاء الـ tools يرمي خطأً بدل أن يفحص نصف الطريق فقط. ومعfetchالخاصة بك (أو proxy)، افحص الوجهات هناك.'refuse'يحتاج Node.js (undiciوnode:dns)؛ وعلى runtime بدونهما، إنشاء الـ tools يرميConfigurationErrorبدل إرسال طلبات غير مفحوصة. وفي Cloudflare Workers لا تتوفّرopenApiTools.
الـ APIs الكبيرة
واجهة فيها مئات العمليات تعني مئات الـ tools. أعطِ الـ agent ما يحتاجه بـinclude أو exclude، أو بـ predicate على op.tags:
الحدود
- OpenAPI 3.0 و3.1 فقط. ومستند Swagger 2.0 يرمي
ConfigurationErrorيطلب منك تحويله أولًا. - يجب أن تكون أجسام الطلبات JSON (
application/jsonأو+json). والعملية التي ليس لها إلا جسم multipart أو form أو XML تُستبعد؛ وتسميتها فيincludeترمي خطأً. - يُستخدم فقط أول مدخل في
servers، والمتغيرات بقيمها الافتراضية. وتُتجاهلserversعلى مستوى الـ path وعلى مستوى العملية. - يجب أن يكون كل
$refمحليًا (#/components/...)؛ والإشارة إلى ملف آخر أو URL ترمي خطأً. اعمل bundle للمستند أولًا. - لا يوجد OAuth flows. و
bearerTokenوheadersيغطّيان بيانات الاعتماد الثابتة والمتغيرة لكل طلب. - أجسام الاستجابات تُقرأ نصًا، وما في streaming لها.