> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# المخرجات المنظمة واستدعاء الأدوات

> استخدم وضع JSON، وأدوات الوظائف، ومسارات الأدوات الأصلية دون افتراض أن كل نموذج يدعم نفس العقد.

المخرجات المنظمة واستدعاءات الأدوات هي عقود محددة حسب المسار. يقوم TokenLab بإرسال عدة تنسيقات API عامة، لذا فإن نمط الإنتاج الأكثر أمانًا هو الاحتفاظ بشكل كل أداة أصلية على المسار الذي يمتلكها والتحقق من مخرجات النموذج في تطبيقك الخاص.

## اختر المسار

| الحاجة                                    | المسار                                  | استخدم هذا الشكل                                   |
| ----------------------------------------- | --------------------------------------- | -------------------------------------------------- |
| استجابات كائن JSON المحمولة               | `/v1/chat/completions`                  | `response_format: {"type": "json_object"}`         |
| استدعاء الوظائف المتوافق مع OpenAI        | `/v1/chat/completions`                  | `tools: [{ "type": "function", "function": ... }]` |
| أدوات استجابات OpenAI                     | `/v1/responses`                         | حقول الاستجابات `tools` و `tool_choice` و `text`   |
| استخدام أدوات Claude الأصلية أو التفكير   | `/v1/messages`                          | مخطط أدوات رسائل Anthropic                         |
| إعلانات الوظائف Gemini أو الأدوات المدمجة | `/v1beta/models/:model:generateContent` | أدوات Gemini الأصلية وأجزاء المحتوى                |

لا ترسل الأدوات المدمجة الأصلية عبر مسار مختلف وتتوقع من TokenLab أن يترجمها بصمت.

## وضع JSON

للحصول على استجابات منظمة قابلة للنقل، ابدأ بوضع JSON لاستكمالات الدردشة:

```json theme={null}
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}
```

تقبل عملية التحقق المشتركة المستقرة لاستكمالات الدردشة `text` و `json_object`. قد توجد `json_schema` و `strict` وفرض مخطط محدد من قبل المزود لبعض المسارات أو مسارات التحويل، لكنها ليست وعدًا شاملًا عبر كل مسار ونموذج في TokenLab. تحقق منها مقابل النموذج المحدد قبل الاعتماد عليها.

قم دائمًا بتحليل والتحقق من JSON المعاد على خادمك. يحسن وضع JSON الشكل، لكنه لا يحل محل التحقق من المخطط على مستوى التطبيق.

## حلقة استدعاء الأدوات

لا يقوم TokenLab بتنفيذ وظائفك. يمتلك تطبيقك الحلقة:

1. أرسل الرسائل بالإضافة إلى تعريفات الأدوات.
2. اقرأ استجابة النموذج لـ `tool_calls` و `function_call` و `tool_use` من Anthropic أو أجزاء استدعاء الوظائف Gemini.
3. نفذ الأداة في الخلفية الخاصة بك.
4. أضف نتيجة الأداة بالشكل المطلوب من نفس المسار.
5. استمر في المحادثة حتى يعود النموذج بإجابة نهائية.

احتفظ بنفس المسار طوال حلقة الأداة. عادةً ما يؤدي خلط استكمالات الدردشة، والاستجابات، والرسائل، وأشكال Gemini في محادثة واحدة إلى إنشاء أخطاء دقيقة في الحالة والمخطط.

## مثال على استكمالات الدردشة

```bash theme={null}
curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'
```

## تصميم المخطط

* احتفظ بالمخططات صغيرة وصريحة. تضيف المخططات الكبيرة المتداخلة رموزًا وتقلل من الاعتمادية.
* فضل الحقول المطلوبة للقيم التي لا يمكن لمنتجك الاستمرار بدونها.
* استخدم enums لمجموعات مغلقة تعتمد عليها واجهة المستخدم أو الخلفية الخاصة بك.
* قم بتضمين أمثلة في الطلب عندما يواجه النموذج صعوبة في شكل معين.
* اعتبر أخطاء الحقول غير المدعومة كتعليقات على العقد. قم بإزالة الحقل أو استخدم المسار الأصلي الذي يوثقه.

## قائمة التحقق للإنتاج

* سجل المسار، والنموذج، وأسماء الأدوات، وشكل المخطط المنظف في السجلات.
* تحقق من معلمات الأداة قبل تنفيذ أي تأثير جانبي.
* طبق فحوصات الأذونات الخاصة بك قبل تنفيذ الأداة.
* اجعل تنفيذ الأداة غير متغير عندما يمكن أن يؤدي إعادة محاولة العميل إلى تكرار نفس استدعاء الأداة.
* لا تسجل الأسرار التي تعيدها الأدوات في الرسائل المرئية للنموذج.

## مرجع API

| الموضوع             | المرجع                                                          |
| ------------------- | --------------------------------------------------------------- |
| API متعدد التنسيقات | [API متعدد التنسيقات](/ar/guides/api-formats)                   |
| إنشاء استكمال دردشة | [إنشاء استكمال دردشة](/ar/api-reference/chat/create-completion) |
| إنشاء استجابة       | [إنشاء استجابة](/ar/api-reference/responses/create-response)    |
| إنشاء رسالة         | [إنشاء رسالة](/ar/api-reference/messages/create-message)        |
| توليد محتوى Gemini  | [توليد محتوى Gemini](/ar/api-reference/gemini/generate-content) |