# شرح حقول Request Body

شرح الحقول العليا لجسم طلب `/v1/messages` في Claude API.

## قائمة الحقول

| الحقل | النوع | الشرح |
|------|------|------|
| **model** | string | اسم النموذج المستخدم، مثل `claude-opus-4-6`، `claude-sonnet-4-6` |
| **messages** | array | سجل رسائل المحادثة. تحتوي كل رسالة على `role` (user/assistant) و`content` (مصفوفة من الكتل مثل النصوص والصور وtool_use وtool_result) |
| **system** | array | System prompt. يتضمن التعليمات الأساسية لـ Claude Code وتعليمات استخدام الأدوات ومعلومات البيئة ومحتوى CLAUDE.md وغيرها. الكتل التي تحمل `cache_control` يتم تخزينها مؤقتًا عبر prompt caching |
| **tools** | array | قائمة تعريفات الأدوات المتاحة. تحتوي كل أداة على `name` و`description` و`input_schema` (JSON Schema). عادةً يمتلك MainAgent أكثر من 20 أداة، بينما يمتلك SubAgent عددًا قليلًا فقط |
| **metadata** | object | البيانات الوصفية للطلب، تتضمن عادةً `user_id` لتحديد هوية المستخدم |
| **max_tokens** | number | الحد الأقصى لعدد الرموز (tokens) في رد النموذج الواحد، مثل `16000`، `64000` |
| **thinking** | object | تكوين التفكير الموسع. `type: "enabled"` يُفعّل وضع التفكير، و`budget_tokens` يتحكم في الحد الأقصى لرموز التفكير |
| **context_management** | object | تكوين إدارة السياق. `truncation: "auto"` يسمح لـ Claude Code باقتطاع سجل الرسائل الطويل تلقائيًا |
| **output_config** | object | تكوين المخرجات، مثل إعداد `format` |
| **stream** | boolean | ما إذا كان يتم تفعيل الاستجابة المتدفقة. يستخدم Claude Code دائمًا `true` |

## بنية messages

حقل `content` لكل رسالة هو مصفوفة من الكتل، والأنواع الشائعة هي:

- **text**: محتوى نصي عادي
- **tool_use**: استدعاء النموذج لأداة (يحتوي على `name`، `input`)
- **tool_result**: نتيجة تنفيذ الأداة (يحتوي على `tool_use_id`، `content`)
- **image**: محتوى صورة (base64 أو URL)
- **thinking**: عملية تفكير النموذج (وضع التفكير الموسع)

## بنية system

تتضمن مصفوفة system prompt عادةً:

1. **تعليمات الوكيل الأساسية** ("You are Claude Code...")
2. **مواصفات استخدام الأدوات**
3. **محتوى CLAUDE.md** (تعليمات على مستوى المشروع)
4. **تذكيرات المهارات** (skills reminder)
5. **معلومات البيئة** (نظام التشغيل، الصدفة، حالة git، إلخ) — في الواقع يعتمد Claude Code بشكل كبير على git. إذا كان المشروع يحتوي على مستودع git، يمكن لـ Claude Code إظهار فهم أفضل للمشروع، بما في ذلك القدرة على جلب التغييرات البعيدة وسجلات الالتزام للمساعدة في التحليل

الكتل المعلّمة بـ `cache_control: { type: "ephemeral" }` يتم تخزينها مؤقتًا بواسطة Anthropic API لمدة 5 دقائق. عند إصابة الذاكرة المؤقتة يتم المحاسبة كـ `cache_read_input_tokens` (أقل بكثير من `input_tokens`).

> **ملاحظة**: بالنسبة للعملاء الخاصين مثل Claude Code، لا يعتمد خادم Anthropic فعليًا بشكل كامل على خاصية `cache_control` في الطلب لتحديد سلوك التخزين المؤقت. يقوم الخادم بتنفيذ سياسة التخزين المؤقت تلقائيًا لحقول معينة (مثل system prompt وتعريفات الأدوات)، حتى لو لم يحمل الطلب علامة `cache_control` بشكل صريح. لذلك، عندما لا ترى هذه الخاصية في جسم الطلب، لا تحتاج إلى الاستغراب — فالخادم قد أنجز عملية التخزين المؤقت في الكواليس، لكنه لم يكشف هذه المعلومات للعميل. هذا تفاهم ضمني بين Claude Code وAnthropic API.
