tool schemas — فروق بحسب الـvendor

الدرس اللي فات أثبت إن التلات vendors بيدعموا function calling ووصف الشكل العام. الدرس ده هو تفصيل التطبيق: لما تكتب الـtools array الفعلية، الـJSON بيختلف عبر الـvendors بطرق صغيرة بس نتايجها كبيرة. لو إنت عارف الفروق دي قبل ما تشتغل، هتوفّر debug session في كل عملية نقل.

نفس الـschema المفهومي، 3 serializations مختلفة

تخيّل إنك عايز تكشف function get_order_status(order_id: string) -> string للنموذج. كل vendor بياخد النية دي ويـserialize-ها بشكل مختلف.

Anthropic (Claude)

{
  "tools": [
    {
      "name": "get_order_status",
      "description": "Look up the current shipping status of an order",
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "Order ID like 4821"
          }
        },
        "required": ["order_id"]
      }
    }
  ]
}

OpenAI (GPT)

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Look up the current shipping status of an order",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "Order ID like 4821"
            }
          },
          "required": ["order_id"]
        }
      }
    }
  ]
}

Google (Gemini)

{
  "tools": [
    {
      "function_declarations": [
        {
          "name": "get_order_status",
          "description": "Look up the current shipping status of an order",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "string",
                "description": "Order ID like 4821"
              }
            },
            "required": ["order_id"]
          }
        }
      ]
    }
  ]
}

فين الفروق بتفرق فعلاً

3 نقط لازم تنبه ليها أثناء النقل:

1. شكل الـwrapper. Anthropic بتستخدم input_schema على الـtool مباشرة. OpenAI بتعشّش تحت function.parameters. Google بتعشّش تحت function_declarations[].parameters. الـJSON Schema جوّه واحد في التلاتة؛ الـwrapping مختلف.

2. دعم الـtype system. التلاتة بيقبلوا الـsubset القياسي من JSON Schema (string, number, boolean, array, object, enum). الـedge cases بتختلف. Anthropic بيقبل format: "uri" و pattern: "^regex$" للـstrings. الـstrict mode بتاع OpenAI (strict: true) هو الوحيد اللي بيضمن إن مخرج النموذج يطابق الـschema بالظبط — بس الـstrict mode بيمنع additionalProperties وبعض مزايا JSON Schema التانية. الصرامة بتاعت Google هي الأقل فيهم التلاتة.

3. سلوك الـstreaming. arguments الـfunction-call بترجع streamed في chunks على التلاتة. Anthropic بتـstream الـJSON كـcontent_block_delta events. OpenAI بتـstream عبر delta.tool_calls[].function.arguments. Google بتـstream كجزء من parts. لو الكود بتاعك بيـparse الـarguments وهي جاية، الـparser ده vendor-specific.

طبقة abstraction portable

في الـproduction، أغلب الفرق بتكتب interface داخلي بياخد وصف schema واحد ويطلّع الـJSON الـvendor-specific الصح. الـlayer ده عادةً بيعيش في 100-200 سطر من TypeScript أو Python وهو المكان الصح لتمركز الفروق دي. الـlayer كمان بيـnormalize شكل الـresponse — كود الـbusiness بتاعك بيشوف { tool_name, arguments } بغضّ النظر عن الـvendor.

لو بتبدأ النهارده، ما تكتبش بتاعك إنت. Vercel AI SDK و LangChain الاتنين بيشحنوا abstractions function-calling portable عبر الـvendors. اختار واحد منهم. الشغل المهم هو تصميم الـschema وتطبيقات الـtools، مش لفّ الـJSON.

التالي: failure modes بحسب الـvendor لما function calling يبوظ. :::