Phase 13: Tools & Protocols

الوظيفة التي تدعو للغوص العميق OpenAI، الأنثروبيك، جيمين

تجمع مزودي الحدود الثلاثة على نفس حلقة الاتصال بالأدوات في عام 2024 ثم اختلفوا على كل شيء آخر.toolsوtool_calls. الاستخدامات الإنسانيةtool_useوtool_resultالكتل التي يستخدمها التوأمfunctionDeclarationsهذه الدروس تفرق الثلاثة جانبا إلى جانبه بحيث لا يتم كسر الرمز الذي يتم شحنه على مزود واحد عندما تقوم بتنفيذه.

Type: Build

Languages: Python (stdlib, schema translators)

Prerequisites: Phase 13 · 01 (the tool interface)

Time: ~75 minutes

أهداف التعلم

  • أوضح الفرق الثلاثة في الشكل بين OpenAI و Anthropic و Gemini (إعلان ، دعوة ، نتيجة).
  • ترجمة إعلان واحد للأداة عبر جميع تنسيقات المزودين الثلاثة وتنبؤ بمكان تختلف قيود الوضع الصارم.
  • استخدامtool_choiceفي كل مزود لإجبار، أو منع، أو اختيار أداة الاتصال تلقائيًا.
  • تعرف الحدود القاسية لكل مزود (عدد الأدوات ، عمق النظام ، طول الحجج) وتوقيعات الخطأ التي تنبعثها كل واحد عندما يتم انتهاك الحدود.

المشكلة

تشكل طلب استدعاء الوظيفة يختلف حسب المقدم. ثلاثة أمثلة ملموسة من مجموعات الإنتاج 2026:

OpenAI Chat Completions / Responses API.أنت تمرtools: [{type: "function", function: {name, description, parameters, strict}}]. ردة النموذج تحتوي على choices[0].message.tool_calls: [{id, type: "function", function: {name, arguments}}]أينargumentsهو سلسلة JSON يجب أن تحلل. وضع صارم (strict: true) يفرض الامتثال للخطط عبر فك القيود المحدود.

Anthropic Messages API.أنت تمرtools: [{name, description, input_schema}]ردنا على هذا هوcontent: [{type: "text"}, {type: "tool_use", id, name, input}]. .inputتم تحليلها بالفعل (شيء وليس سلسلة)userرسالة تحتوي على{type: "tool_result", tool_use_id, content}-بلوك

Google Gemini API.أنت تمرtools: [{functionDeclarations: [{name, description, parameters}]}](مُعَشَّرَة تحت functionDeclarations) والرد يأتي كcandidates[0].content.parts: [{functionCall: {name, args, id}}]أينidهو فريد في جيميني 3 و فوق لتنسيق المكالمة المتوازية.{functionResponse: {name, id, response}}. . .

نفس الحلقة، أسماء الميدان المختلفة، وترتيبات مختلفة، وآليات مختلفة للشريط مقابل الكائن، وآليات مختلفة للاتصال. فريق يكتب وكيل الطقس على OpenAI يدفع لميناء يومين إلى "أنثروبيك" و يوم آخر إلى "جيميني" فقط من أجل التبني.

هذه الدروس تبني مترجم يوحد الصيغ الثلاثة في إعلان واحد أداة القنوني والطرق في الحافة. مرحلة 13 · 17 تعميم نفس النمط في بوابة LLM.

المفهوم

الهيكل المشترك

كل مزود يحتاج إلى خمسة أشياء:

  1. Tool list.اسم كل أداة وصف ونظام إدخال.
  2. Tool choice.أجبري على أداة محددة أو حظر الأدوات أو دع النموذج يقرر
  3. Call emission.الناتج المهيكلي الذي يسمي الأداة والحجج.
  4. Call id.ربط الاستجابة بالدعوة الصحيحة (المسائل للموازية).
  5. Result injection.رسالة أو حظر يربط النتيجة بالاتصال

اختلافات الشكل، حقلًا بحقل

AspectOpenAIAnthropicGemini
Declaration envelope{type: "function", function: {...}}{name, description, input_schema}{functionDeclarations: [{...}]}
Schema fieldparametersinput_schemaparameters
Response containertool_calls[] on assistant messagecontent[] of type tool_useparts[] of type functionCall
Arguments typestringified JSONparsed objectparsed object
Id formatcall_... (OpenAI generates)toolu_... (Anthropic)UUID (Gemini 3+)
Result blockrole tool, tool_call_iduser with tool_result, tool_use_idfunctionResponse with matching id
Force-a-tooltool_choice: {type: "function", function: {name}}tool_choice: {type: "tool", name}tool_config: {function_calling_config: {mode: "ANY"}}
Forbid toolstool_choice: "none"tool_choice: {type: "none"}mode: "NONE"
Strict schemastrict: trueschema-is-schema (always enforced)responseSchema at request level

الحدود التي ستضربها فعلاً

  • OpenAI.128 أداة لكل طلب. عمق الخطة 5. سلسلة الحجج <= 8192 بايت. وضع القييد لا يتطلب $refلا , لاoneOf-أجلanyOf-أجلallOfمع التداخل، كل ممتلكات المدرجة في required. . .
  • Anthropic.64 أداة لكل طلب. عمق الخطة لا حدود لها ولكن حد عملي 10. لا يوجد علامة على الوضع الصارم. الخطة عقد وتعتبر النموذج متوافقة.
  • Gemini.64 وظيفة لكل طلب. أنواع الخطة هي OpenAPI 3.0 فرعية (اختلاف طفيف من JSON Schema 2020-12). الدعوات المتوازية هو واحد-هوية منذ جيمين 3.

tool_choiceالسلوك

ثلاثة أنظمة تدعمها الجميع، تسميت مختلفة.

  • Auto.النموذج يختار الأداة أو النص الافتراضي
  • Required / Any.يجب أن يتصل النموذج بأداة واحدة على الأقل
  • None.لا يجب أن تدعو النموذج إلى أدوات

بالإضافة إلى وضع واحد فريد لكل مزود:

  • OpenAI.اجبر أداة محددة باسمها
  • Anthropic.إجبار أداة محددة باسمهاdisable_parallel_tool_useالعلم يفصل بين واحد مقابل متعدد
  • Gemini. mode: "VALIDATED"يتوجه كل رد عبر مؤكدة النظام بغض النظر عن نية النموذج.

المكالمات المتوازية

"أوبن آي"parallel_tool_calls: true(الديفالتي) ينشر مكالمات متعددة في رسالة مساعدة واحدة. تقوم بتشغيلها كلها وترد برسالة أداة-دور المجموعة التي تحتوي على إدخال واحد لكلtool_call_id. إنثروبي تاريخياً كان يطلب مكالمة واحدةdisable_parallel_tool_use: false(الديفالتي اعتبارا من كلود 3.5) تمكن متعددة. سمح جيميني 2 بالاتصال المتوازي ولكن لم يعطي هواتف مستقرة. جيميني 3 يضيف UUIDs حتى تتواصل استجابات خارج النظام بشكل نظيف.

التدفق

جميع الدعوات الثلاثة تدعم أداة التدفق. تنسيق الأسلاك يختلف:

  • OpenAI.قطعات ديلتا منtool_calls[i].function.argumentsتصل بشكل تدريجي، تتراكم حتىfinish_reason: "tool_calls". . .
  • Anthropic.أحداث البدء المحدد / البلوك-دلتا / وقف المحدد. input_json_deltaالكتائب تحمل حجج جزئية.
  • Gemini. streamFunctionCallArguments(جديد في جيميني 3) يُصدّر قطع مع functionCallIdحتى تتمكن مكالمات متوازية متعددة من التقاط.

مرحلة 13 · 03 تدخل عميقًا في إعادة تجميع الموازات + التدفق. يركز هذا الدروس على أشكال الإعلانات والدعوة الواحدة.

الأخطاء وإصلاحها

أخطاء الحجج غير صالحة تبدو مختلفة أيضا.

  • OpenAI (non-strict).النموذج يعود arguments: "{bad json}"إذا فشلت تحليل JSON، تقوم بإدخال رسالة خطأ وإعادة الاتصال.
  • OpenAI (strict).يتم التحقق من التحقق من الصحة أثناء فك التشفير . غير صالحة JSON مستحيل ولكن refusalيمكن أن تظهر.
  • Anthropic. inputقد تحتوي على حقل غير متوقعة، النموذج هو نصيحة. تأكيد جانب الخادم.
  • Gemini.المميزة في OpenAPI 3.0: enumعلى حقل الأشياء التي تم تجاهلها بصمت، تأكدي نفسك.

نمط الترجمة

إعلان أداة طائفية في رمزك يبدو هكذا (انت تختار الشكل):

pythonTool(
    name="get_weather",
    description="Use when ...",
    input_schema={"type": "object", "properties": {...}, "required": [...]},
    strict=True,
)

ثلاث وظائف صغيرة تحويلها إلى ثلاثة أشكال مزود.code/main.pyيقوم بذلك بالضبط، ثم يقوم بتجول مكالمة أداة مزيفة عبر شكل استجابة كل مزود. لا توجد شبكة مطلوبة هذا الدرس يعلم الشكول، وليس HTTP.

فرق الإنتاج تغلف هذا المترجم فيAbstractToolset(الذكاء الاصطناعي البيانتي)UniversalToolNode(لنجراف) ، أوBaseTool(LlamaIndex). مرحلة 13 · 17 تشكل بوابة تعرض API على شكل OpenAI أمام أي من الثلاثة.

استخدمها

code/main.pyيحدد واحد القنوني Toolفهي تقوم بعد ذلك بتحليل استجابة مزود مصنوعة يدويا لكل شكل إلى نفس جسم الدعوة القنوني ، مما يظهر أن التفاصيل نفسها تحت الجلد. قم بتشغيلها وتفاصيل الإعلانات الثلاث جنبا إلى جنب.

ما الذي يجب أن ننظر إليه:

  • لا تختلف كتلة الإعلان الثلاثة إلا في أسم الملفات والحقول.
  • تختلف كتلة الاستجابة الثلاثة في مكان وجود المكالمة (على مستوى أعلى tool_calls،content[]الحجرparts[]الدخول)
  • واحدcanonical_call()مقتطفات الوظيفة {id, name, args}من جميع أشكال الاستجابة الثلاثة.

أرسله

هذا الدرس يُنتجoutputs/skill-provider-portability-audit.md. نظراً لتكاملات الدعوة الوظيفية مع مزود واحد، فإن المهارة تنتج مراجعة للنقل: أي مزود يحد من الحدود التي يعتمد عليها، والحقول التي تحتاج إلى إعادة تسمية، وما الذي ينتهي عندما يتم نقلها إلى مزود آخر.

التمارين

  1. أركضcode/main.pyوتحقق من أن جميع JSONs الإعلانات المقدمة ثلاثة تسلسل نفس الأساسية Toolتعديل الأداة القنونية لإضافة مبرمير enum وتأكيد فقط مترجم جيميني يحتاج للتعامل مع عادة OpenAPI.
  1. إضافةListToolsResponseالمصفح لكل مزود يستخرج قائمة الأدوات يعيد النموذج بعد list_toolsأو دعوة اكتشاف. لا يوجد لدى OpenAI واحدة بشكل أصلي؛ لاحظ هذه التناظر.
  1. تنفيذtool_choiceتحويل: خريطة القنوني ToolChoice(mode="force", tool_name="x")في جميع أشكال المزودين الثلاثة. ثم خريطةmode="any"وmode="none"تفقد جدول الاختلافات في الدروس
  1. اختر واحد من المقدمين الثلاثة وقرأ دليل استدعاء الوظائف من نهايتها إلى نهايتها. ابحث عن حقل واحد في مواصفات مخططها التي لا تدعمها الاثنان الآخران. المتقدمين: OpenAI strict، الأنثروبيك disable_parallel_tool_use، التوأمfunction_calling_config.allowed_function_names. . .
  1. كتابة متجه اختبار: دعوة أداة تنتهك حججها النظام المعلن. قم بتشغيلها من خلال مؤكدة كل مزود (ستعمل stdlib في الدروس 01 كوكب) وتسجيل أي أخطاء تنطلق. وثيقة من المزود الذي ستستخدم في الإنتاج لتحقيق الصرامة.

الشروط الرئيسية

TermWhat people sayWhat it actually means
Function calling"Tool use"Provider-level API for structured tool-call emission
Tool declaration"Tool spec"Name + description + JSON Schema input payload
tool_choice"Force / forbid"Auto / required / none / specific-name modes
Strict mode"Schema enforcement"OpenAI flag that constrains decoding to match schema
tool_use block"Anthropic's call shape"Inline content block with id, name, input
functionCall part"Gemini's call shape"A parts[] entry containing name, args, and id
Arguments-as-string"Stringified JSON"OpenAI returns args as a JSON string, not an object
Parallel tool calls"Fan-out in one turn"Multiple tool calls in one assistant message
Refusal"Model declines"Strict-mode-only refusal block instead of a call
OpenAPI 3.0 subset"Gemini schema quirk"Gemini uses a JSON-Schema-like dialect with minor differences

المزيد من القراءة

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.