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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# قوالب الموجّهات

> احتفظ بالموجّهات في إعداد مسبق وأرسل فقط القيم التي تتغير مع كل طلب.

احفظ رسائلك مع `{{variables}}` في [إعداد مسبق](https://phaseo.app/docs/ar/v1/guides/presets.md)، فلا يرسل تطبيقك سوى مرجع الإعداد المسبق وقيم المتغيرات. يتحقق Phaseo من القيم، ويملأ الرسائل، ويرسل الطلب إلى نموذج الإعداد المسبق. لا يحتاج تغيير الموجّه في لوحة التحكم إلى نشر جديد، ويحصل كل مستدعٍ على الصياغة والأدوات وصيغة الاستجابة نفسها.

تعمل القوالب على `POST /v1/chat/completions` و`POST /v1/responses` و`POST /v1/messages`.

## أنشئ قالبًا واستدعِه

**1. اكتب القالب**

افتح **الإعدادات ← الإعدادات المسبقة**، وأنشئ إعدادًا مسبقًا أو افتح واحدًا، واختر نموذجه، وافتح علامة التبويب **قالب الموجّه**. أضف الرسائل واكتب المتغيرات بين قوسين معقوفين مزدوجين:

```text theme={null}
System: You triage support tickets for {{company}}. Reply in a {{tone}} tone.
User:   Ticket: {{ticket}}
```

يسرد المحرر كل متغير يعثر عليه. اضبط نوعه، وما إذا كان مطلوبًا، وقيمته الافتراضية، ووصفه. املأ لوحة **جرّبه** لترى الرسائل الدقيقة التي سيرسلها الـ Gateway، ثم احفظ.

بعد حفظ الإعداد المسبق، يرسل **تشغيل الإعداد المسبق المحفوظ** طلبًا حقيقيًا بقيم الاختبار الخاصة بك ويعرض الرد والنموذج وأعداد الـ tokens. ويستهلك أرصدة مساحة عملك. تحتوي اللوحة نفسها على شيفرة cURL وTypeScript وPython للطلب، معبأة بقيم الاختبار الخاصة بك.

**2. أرسل المتغيرات**

أشر إلى الإعداد المسبق في `prompt.id` وضع القيم في `prompt.variables`. احذف `model`، أو اضبطه على المرجع نفسه.

```bash cURL theme={null}
curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": {
      "id": "@support-triage",
      "variables": {
        "company": "Acme",
        "tone": "friendly",
        "ticket": "I was charged twice this month."
      }
    }
  }'
```

```typescript TypeScript theme={null}
import Phaseo from "@phaseo/sdk";

const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });

const completion = await client.generateText({
	model: "@support-triage",
	messages: [],
	prompt: {
		id: "@support-triage",
		variables: {
			company: "Acme",
			tone: "friendly",
			ticket: "I was charged twice this month.",
		},
	},
});
```

```python Python theme={null}
from phaseo import Phaseo

client = Phaseo(api_key="YOUR_API_KEY")

completion = client.generate_text({
    "prompt": {
        "id": "@support-triage",
        "variables": {
            "company": "Acme",
            "tone": "friendly",
            "ticket": "I was charged twice this month.",
        },
    },
})
```

**3. تحقّق من الطلب**

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

## استخدم القوالب من كل نقطة نهاية

يعمل كائن `prompt` نفسه على نقاط النهاية الثلاث. تصبح رسائل النظام والمطوّر في القالب تعليمات النظام لنقطة النهاية، وتأتي رسائله الأخرى قبل أي محادثة يرسلها طلبك.

| نقطة النهاية | تذهب رسائل النظام في القالب إلى | تأتي محادثة القالب قبل |
| - | - | - |
| `/v1/chat/completions` | `messages` (تبقى رسائل نظام) | `messages` الخاصة بك |
| `/v1/responses` | `instructions` | `input` الخاص بك |
| `/v1/messages` | `system` | `messages` الخاصة بك |

يمكنك إرسال محادثة مع القالب. على سبيل المثال، يمكن لطلب دردشة أن يضيف أدوار المتابعة من المستخدم بعد رسائل القالب:

```json theme={null}
{
  "prompt": { "id": "@support-triage", "variables": { "company": "Acme", "ticket": "Refund request" } },
  "messages": [
    { "role": "assistant", "content": "Can you share the order number?" },
    { "role": "user", "content": "It is 10482." }
  ]
}
```

## صيغة القوالب

تستخدم القوالب مجموعة فرعية صغيرة من Mustache خالية من المنطق. لا يُنفَّذ أي شيء في القالب كشيفرة أبدًا.

| الصيغة | ما تفعله |
| - | - |
| `{{name}}` | تُدرج قيمة. يُدرج النص كما هو، والأرقام والقيم المنطقية كنص، والقوائم والكائنات بصيغة JSON. لا تُدرج القيمة الاختيارية المفقودة شيئًا. |
| `{{customer.name}}` | تُدرج حقلًا من متغير كائن. |
| `{{#name}}...{{/name}}` | تعرض الكتلة مرة واحدة عندما تكون القيمة مضبوطة وليست `false`، أو مرة لكل عنصر في قائمة. في الداخل، `{{.}}` هو العنصر الحالي ويمكن استخدام حقوله بأسمائها. |
| `{{^name}}...{{/name}}` | تعرض الكتلة عندما تكون القيمة مفقودة أو `false` أو نصًا فارغًا أو قائمة فارغة. |
| `{{! note }}` | تعليق. يُزال. |
| `\{{` | `{{` حرفية. |

تُدرج القيم كنص عادي، دون تهريب HTML. يمكن للقيمة أن تغيّر نص رسالة لكنها لا تغيّر بنية الطلب أبدًا.

إذا لم ينتج عن عرض رسالة سوى مسافات بيضاء، فإنها تُحذف. استخدم هذا لجعل رسالة كاملة اختيارية:

```text theme={null}
{{#notes}}Notes from the account manager: {{notes}}{{/notes}}
```

لتكرار نص لكل عنصر في قائمة، افتح قسمًا على القائمة واستخدم `{{.}}` للعنصر الحالي:

```text theme={null}
Examples of good replies:
{{#examples}}- {{.}}
{{/examples}}
```

لا تُدعم القوالب الجزئية (`{{> name}}`)، والوسوم غير المهرّبة (`{{{name}}}` و`{{& name}}`)، وتغيير المحددات، ودوال lambda، ويرفض المحرر وواجهة API القوالب التي تستخدمها.

## المتغيرات

لكل متغير نوع. لا تحتاج إلى التصريح عن متغير إلا لتغيير قيمه الافتراضية؛ المتغيرات المستخدمة في الرسائل دون تصريح هي نص مطلوب.

| النوع | يقبل |
| - | - |
| `string` | نصًا. اضبط `max_length` لتحديد طوله. |
| `number` | رقمًا. |
| `boolean` | `true` أو `false`. |
| `enum` | إحدى السلاسل المدرجة في `enum`. |
| `array` | قائمة. |
| `object` | كائن JSON. |
| `any` | أي قيمة JSON. |
| `image` | صورة لرسالة مستخدم. راجع [متغيرات الصور](#image-variables). |

يمكن أن يحتوي كل متغير أيضًا على:

* `required`: يفشل الطلب عندما تكون القيمة مفقودة. لا يمكن أن يكون للمتغير المطلوب قيمة افتراضية.
* `default`: تُستخدم عندما يترك الطلب القيمة. يجب أن تطابق النوع.
* `description`: يُعرض في المحرر وفي رسائل الخطأ، حتى 500 حرف.

الاسم المستخدم فقط لفتح الأقسام، مثل `notes` و`examples` أعلاه، اختياري ويقبل أي قيمة.

تُفحص الطلبات بصرامة. تعيد القيمة المطلوبة المفقودة، أو القيمة من نوع خاطئ، أو الاسم غير الموجود في القالب الخطأ `400` الذي يسرد كل المشكلات دفعة واحدة، حتى لا يُسقط خطأ إملائي جزءًا من الموجّه بصمت.

## متغيرات الصور

يملأ متغير الصورة جزء محتوى كاملًا من رسالة مستخدم، لذا يحدد القالب موضع الصورة. في المحرر، اختر **إضافة صورة** داخل رسالة مستخدم. في واجهة API، استخدم جزءًا من نوع `variable`:

```json theme={null}
{
  "role": "user",
  "content": [
    { "type": "text", "text": "Before:" },
    { "type": "variable", "name": "before" },
    { "type": "text", "text": "After:" },
    { "type": "variable", "name": "after" },
    { "type": "text", "text": "What changed?" }
  ]
}
```

يمكن للطلب إرسال كل صورة كعنوان URL بصيغة `https`، أو عنوان URL بصيغة `data:image/...`، أو جزء صورة بشكل chat completions أو Responses أو Messages. يحوّلها Phaseo إلى صيغة نقطة النهاية التي استدعيتها. يجب أن يقبل النموذج المختار إدخال الصور.

## الأدوات وصيغة الاستجابة

يمكن أن يتضمن القالب `tools` و`tool_choice` و`response_format`، مكتوبة بشكل chat completions (راجع [استدعاء الأدوات](https://phaseo.app/docs/ar/v1/guides/tool-calling.md) و[المخرجات المنظَّمة](https://phaseo.app/docs/ar/v1/guides/structured-outputs.md)). يحوّلها Phaseo لنقطتي النهاية Responses وMessages.

يفوز الطلب دائمًا عندما يضبط الاثنان الشيء نفسه:

* تُدمج الأدوات حسب اسم الدالة. إذا عرّف الطلب أداة بالاسم نفسه، يُستخدم تعريف الطلب.
* تستبدل قيمة `tool_choice` وصيغة الاستجابة في الطلب (`response_format` أو `text.format` أو `output_config.format`) قيم القالب.

تعمل معاملات الطلب مثل `temperature` و`max_tokens` كالمعتاد. لا تملأ القيم الافتراضية للإعداد المسبق إلا الحقول التي يتركها الطلب.

## أنشئ قالبًا عبر API

تُخزَّن القوالب في `config.prompt` الخاص بالإعداد المسبق. أنشئ الإعداد المسبق أو حدّثه باستخدام [مفتاح API للإدارة](https://phaseo.app/docs/ar/v1/developers/management-api-keys.md) يملك صلاحية `presets:write`:

```bash theme={null}
curl https://api.phaseo.app/v1/presets \
  -H "Authorization: Bearer $PHASEO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@support-triage",
    "visibility": "team",
    "config": {
      "models": ["anthropic/claude-haiku-5.5"],
      "prompt": {
        "messages": [
          { "role": "system", "content": "You triage support tickets for {{company}}. Reply in a {{tone}} tone." },
          { "role": "user", "content": "Ticket: {{ticket}}" }
        ],
        "variables": {
          "company": { "type": "string", "required": true },
          "tone": { "type": "enum", "enum": ["formal", "friendly"], "default": "formal" },
          "ticket": { "type": "string", "required": true, "max_length": 4000 }
        }
      }
    }
  }'
```

يتحقق Phaseo من القالب عند حفظه. يُرفض القالب الذي يحتوي على خطأ في الصيغة، أو نوع غير معروف، أو قيمة افتراضية لا تطابق نوعها، بالخطأ `400 invalid_prompt_template` مع موضع كل مشكلة، هنا وفي المحرر على حد سواء.

تصل التغييرات المحفوظة إلى الطلبات خلال دقيقتين تقريبًا.

## الإصدارات والتسميات

في كل مرة تنشر فيها إعدادًا مسبقًا، يحفظ Phaseo إصدارًا غير قابل للتغيير (راجع [الإعدادات المسبقة](https://phaseo.app/docs/ar/v1/guides/presets.md#version-and-roll-back)). تشغّل الطلبات أحدث إصدار منشور ما لم تثبّت إصدارًا. يستخدم الطلب المثبّت نماذج ذلك الإصدار ومعاملاته وقالبه معًا.

ثبّت إصدارًا باستخدام `prompt.version`:

```json theme={null}
{
  "prompt": {
    "id": "@support-triage",
    "version": "production",
    "variables": { "company": "Acme", "ticket": "My invoice is wrong" }
  }
}
```

يقبل `prompt.version` تسمية إصدار مثل `v3` أو `1.2.0` أو `2026.10.27`، أو تسمية مثل `production`. يمكنك أيضًا وضع الإصدار في معرّف النموذج، مع قالب أو بدونه:

```json theme={null}
{
  "model": "@support-triage@production",
  "messages": [{ "role": "user", "content": "My invoice is wrong" }]
}
```

تستخدم الإعدادات المسبقة العامة `@publisher/support-triage@production`. إذا ثبّت كل من `model` و`prompt.version` إصدارًا، فيجب أن يسمّيا الإصدار نفسه.

### التسميات

التسمية اسم، مثل `production` أو `staging`، يشير إلى إصدار منشور واحد. تتكون التسميات من 1 إلى 32 حرفًا لاتينيًا صغيرًا أو رقمًا أو شرطة أو شرطة سفلية، وتبدأ بحرف، ولا يمكن أن تشبه تسمية إصدار (`v1`، `v2`).

في **الإعدادات ← الإعدادات المسبقة**، افتح الإعداد المسبق. يحفظ **نشر**، بجانب **حفظ المسودة**، تغييراتك وينشرها كالإصدار التالي. افتح **الإصدارات والتسميات** لإدارة التسميات: لكل تسمية منتقي إصدار، فاختيار إصدار آخر ينقل التسمية، واختيار إصدار سابق يتراجع إليه. استخدم **إضافة تسمية** لتسمية جديدة. افتح إصدارًا لترى نماذجه ورسائل قالبه وكيف تختلف عن الإصدار الافتراضي (الذي تشغّله الطلبات عندما لا تثبّت إصدارًا)، واستخدم **تشغيل** لتجربة ذلك الإصدار بقيم الاختبار من **قالب الموجّه**. يمكن لمنشئ الإعداد المسبق تغيير تسمياته، وكذلك مالكو مساحة العمل ومسؤولوها عندما يكون الإعداد المسبق مشتركًا. باستخدام [مفتاح API للإدارة](https://phaseo.app/docs/ar/v1/developers/management-api-keys.md) يملك صلاحية `presets:write`:

```bash theme={null}
curl -X PUT https://api.phaseo.app/v1/presets/support-triage/labels/production \
  -H "Authorization: Bearer $PHASEO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "version": "v3" }'
```

يقبل الجسم `version` (تسمية إصدار، أو تسمية أخرى لنسخ ما تشير إليه) أو `version_id`. يسرد `GET /v1/presets/{id}/labels` التسميات، ويزيل `DELETE /v1/presets/{id}/labels/{label}` واحدة منها. تفشل الطلبات التي تثبّت تسمية مُزالة حتى تُضاف مجددًا.

### التراجع

للتراجع، انقل التسمية إلى الإصدار السابق: اختر ذلك الإصدار في منتقي إصدار التسمية في **الإصدارات والتسميات**، أو أرسل الطلب نفسه مع `"version": "v2"`. تشغّل الطلبات التي تثبّت `production` الإصدار v2 مجددًا دون أي تغيير في تطبيقك.

تصل تنقلات التسميات إلى الطلبات خلال دقيقتين تقريبًا، مثل تغييرات الإعداد المسبق الأخرى.

## الأخطاء

تعيد مشكلات القالب في الطلب `400` بالرمز `validation_error`. يحمل `reason` رمز المشكلة الأولى، ويسرد `details` جميعها مع مساراتها:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Template \"@support-triage\" needs variable \"ticket\" (string)",
    "type": "invalid_request_error"
  },
  "code": "validation_error",
  "reason": "template_variable_required",
  "description": "Template \"@support-triage\" needs variable \"ticket\" (string)",
  "details": [
    {
      "message": "Template \"@support-triage\" needs variable \"ticket\" (string)",
      "path": ["prompt", "variables", "ticket"],
      "keyword": "template_variable_required"
    }
  ]
}
```

| السبب | العلة |
| - | - |
| `template_variable_required` | متغير مطلوب مفقود. |
| `template_variable_type` | قيمة لا تطابق نوعها أو قائمة enum أو `max_length`. |
| `template_variable_unknown` | أرسل الطلب متغيرًا غير موجود في القالب، أو لا يحتوي الإعداد المسبق على قالب. |
| `template_variables_invalid` | `prompt.variables` ليس كائنًا. |
| `template_limit_exceeded` | المتغيرات أو النص المعروض أكبر من الحدود أدناه. |
| `template_rendered_empty` | لم يعرض القالب أي رسالة مستخدم أو مساعد، ولم يرسل الطلب أيًا منها. |
| `template_endpoint_unsupported` | يحتوي الإعداد المسبق على قالب واستُدعي من نقطة نهاية غير الثلاث المذكورة أعلاه. |
| `prompt_model_conflict` | يسمّي `model` إعدادًا مسبقًا أو نموذجًا مختلفًا عن `prompt.id`، أو يثبّت إصدارًا مختلفًا عن `prompt.version`. |
| `prompt_version_invalid` | `prompt.version` فارغ، أو أطول من 64 حرفًا، أو يحتوي على أحرف غير الأحرف والأرقام و`.` و`_` و`+` و`-`. |
| `prompt_model_fallbacks_unsupported` | ضبط الطلب بدائل `models`. اسرد النماذج البديلة في الإعداد المسبق بدلًا من ذلك. |

تعيد قيمة `prompt.id` التي لا تسمّي أي إعداد مسبق في مساحة عملك `404`.

يعيد الإصدار أو التسمية المثبّتة غير الموجودة، أو التي لا يستطيع المفتاح استخدامها، `404` بالسبب `preset_version_not_found`.

## الحدود

| الحد | القيمة |
| - | - |
| الرسائل لكل قالب | 64 |
| المتغيرات لكل قالب | 64 |
| طول اسم المتغير | 64 حرفًا |
| نص القالب عبر كل الرسائل | 48,000 حرف |
| عمق تداخل الأقسام | 8 |
| تكرارات الأقسام لكل طلب | 1,000 |
| النص المعروض لكل طلب | 1,000,000 حرف |
| حجم `prompt.variables` | 256 KB |
| القيم لكل `enum` | 100 |

## ضوابط الحماية والسجلات

تفحص [ضوابط الحماية](https://phaseo.app/docs/ar/v1/cookbook/guardrails-for-api-keys.md) قيم المتغيرات كمحتوى مستخدم، حتى عندما يضعها القالب في رسالة نظام. يحجب ضابط الحماية الذي ينقّح قيمة تلك القيمة في كل موضع أدرجها فيه القالب، ويحظر الضابط الذي يحظر قيمة الطلب كله.

تسجّل البيانات الوصفية للطلب الإعداد المسبق وأسماء المتغيرات وعدد الرسائل المعروضة. أما القيم نفسها فلا تُحفظ إلا حيث يُحفظ جسم الطلب، وفق إعدادات التسجيل المعتادة لمساحة عملك.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.