# إجابات بسؤال واحد

> اطرح على وكيلك سؤالًا واحدًا عبر POST /v1/agents/{agent}/ask — مع الهوية، والسجل الذي يرسله المستدعي، والإجراءات، ووضع الخصوصية، والتجاوزات، والتحويل لموظف.

طلب `ask` يرسل سؤالًا واحدًا ويستلم إجابة واحدة، دون جلسة تديرها. يستخدم الوكيل كل إعداداته — التعليمات والمعرفة والأدوات والضوابط — فتأتي الإجابات بجودة المحادثة نفسها. استخدمه لأزرار المساعدة داخل تطبيقك، وللإجابات في صفحات المنتجات، ولصياغة ردود مقترحة لفريقك، أو لأي مهمة في الخادم تحتاج معرفة الوكيل.

## طلب أساسي

**curl**

```bash
curl https://api.k-agent.kerneltics.com/v1/agents/store-assistant/ask \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "كم رسوم التوصيل؟"}'
```

**JavaScript**

```js
const res = await fetch('https://api.k-agent.kerneltics.com/v1/agents/store-assistant/ask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KAGENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ input: 'كم رسوم التوصيل؟' }),
});
const run = await res.json();
if (!res.ok) throw new Error(`${run.error.code}: ${run.error.message}`);

if (run.outcome === 'handed_off') {
  console.log('Passed to the team:', run.handoff.summary);
}
console.log(run.output_text);
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.k-agent.kerneltics.com/v1/agents/store-assistant/ask",
    headers={"Authorization": f"Bearer {os.environ['KAGENT_API_KEY']}"},
    json={"input": "كم رسوم التوصيل؟"},
    timeout=120,
)
run = r.json()
if not r.ok:
    raise RuntimeError(f"{run['error']['code']}: {run['error']['message']}")
if run["outcome"] == "handed_off":
    print("Passed to the team:", run["handoff"]["summary"])
print(run["output_text"])
```

الاستجابة [تشغيل](/docs/concepts/runs-and-streaming/#كائن-التشغيل). اقرأ `output_text` للإجابة، و`outcome` لتعرف هل أجاب الوكيل (`answered`) أم حوّل لموظف (`handed_off`).

## حقول الطلب

| الحقل | النوع | الوصف |
|---|---|---|
| `input` | نص أو `[{type: "text", text}]` | السؤال. حتى 32,000 حرف مع المفتاح السري، و4,000 مع بيانات اعتماد المتصفح. |
| `end_user` | كائن | `{external_id, name?, traits?}`. مع المفتاح السري يكون المستخدم **موثّقًا**، فتعمل الأدوات المرتبطة بالهوية والذاكرة الخاصة بكل مستخدم. |
| `history` | مصفوفة | أدوار سابقة من تطبيقك، مثل `[{"role": "user", "content": "…"}, {"role": "assistant", "content": "…"}]`. تُستخدم نصًا وتوسم بأنها سياق من المستدعي غير موثَّق. |
| `variables` | كائن | قيم [متغيرات](/docs/concepts/settings/#المتغيرات-variables) الوكيل، بما فيها السرية (تُستخدم لهذا الطلب فقط). |
| `allow_actions` | منطقي | الافتراضي `false`: لا تُعرض الأدوات ذات الأثر. اجعله `true` للسماح بها. |
| `store` | منطقي | الافتراضي `true`. ومع `false` لا يُحفظ أي سجل للمحادثة (انظر أدناه). |
| `stream` | منطقي | بث الإجابة على شكل [Server-Sent Events](/docs/concepts/runs-and-streaming/#البث). |
| `version` | عدد صحيح | إصدار منشور يُستخدم بدل الأحدث. |
| `overrides` | كائن | تغييرات لهذا الطلب يسمح بها الوكيل (انظر أدناه). |
| `metadata` | كائن | أزواج مفتاح وقيمة خاصة بك، تُعاد مع التشغيل. |
| `wait_seconds` | عدد صحيح | مدة انتظار الإجابة (الافتراضي 60 والحد الأقصى 110) قبل إعادة `202`. |

## من الذي يسأل

أرسل `end_user` حين تعرف الشخص. طلبات السؤال الواحد الموثّقة تستطيع استخدام أدوات HTTP التي تحتاج الهوية — كالاستعلام عن طلب *هذا* العميل — وتشارك ذاكرة الإجراءات وحدود ذلك العميل في جلساته:

```json
{
  "input": "وين طلبي؟",
  "end_user": { "external_id": "cus_1042", "name": "فهد", "traits": { "plan": "gold" } }
}
```

## الإجراءات معطّلة ما لم تطلبها

لأن طلبات السؤال الواحد تكون مؤتمتة في الغالب، تُزال الأدوات ذات الأثر (`create_ticket` وأدوات HTTP ذات `effect: "action"` وأدوات جهة العميل) افتراضيًا. أما أدوات القراءة والتحويل لموظف فتعمل دائمًا. أرسل `"allow_actions": true` حين يجب أن يكون الطلب قادرًا على التصرف.

## وضع الخصوصية: `store: false`

مع `"store": false`:

- لا تُحفظ أي رسائل، وتُحذف أحداث التشغيل عند انتهائه؛
- لا تحتفظ خطوات التشغيل بأي معاملات أو نتائج أو ملخصات؛
- لا يُطلق الحدث `message.created`، ولا تحمل الويب هوك أي نص؛
- يعيد `GET /v1/runs/{run}` الحالة والاستخدام فقط؛
- لا تُعرض أدوات جهة العميل.

ويبقى الاستخدام مسجّلًا لأغراض الفوترة.

## التجاوزات في الطلب

يمكن للوكيل أن يسمح بتغيير بعض الإعدادات لكل طلب. اسردها في `overrides.allowed` لدى الوكيل (والنماذج في `overrides.models` حين تسمح بـ `model`)، ثم أرسل:

```json
{
  "input": "لخّص سياسة الإرجاع عندنا.",
  "overrides": {
    "dialect": "msa",
    "tone": "formal",
    "instructions_append": "أجب في ثلاث جمل على الأكثر."
  }
}
```

الحقول المسموحة هي `dialect` و`tone` و`instructions_append` و`temperature` و`model` و`tools_disable` و`history_limit`. ولا يمكن أبدًا تجاوز قائمة «لا تتعامل معها بنفسك» ولا الرد الحرفي عند التصعيد ولا صلاحيات الأدوات، ولا يرسل التجاوزاتِ إلا المفاتيحُ السرية؛ وأي شيء آخر يعيد `422 override_not_allowed`.

## حين يحوّل الوكيل لموظف

تنطبق الضوابط على طلبات السؤال الواحد أيضًا. موضوع من قائمة «لا تتعامل معها بنفسك»، أو سؤال لا يستطيع الوكيل الإجابة عنه مما يعرفه، ينتهي بتحويل يراه فريقك:

```json
{
  "object": "run",
  "mode": "one_shot",
  "status": "completed",
  "outcome": "handed_off",
  "output_text": "شكرًا لتواصلك. حوّلنا طلبك إلى المسؤول المختص وسيتواصل معك قريبًا.",
  "handoff": { "id": "ho_01k6rz6c8e0g2j4m6p8r0t2v4x", "reason_type": "liability", "summary": "العميل يذكر أن العطر سبّب حساسية في الجلد", "status": "recorded" }
}
```

- في حالة المسؤولية القانونية مع رد تصعيد مُعدّ، يكون `output_text` هو ردك بالحرف.
- لا توجد جلسة لإيقافها، فيكون التحويل `recorded`. يظهر في مكتب التحويل تحت مرشّح **سؤال واحد**، ويُطلق الويب هوك `handoff.requested` مع `run_id` — استخدمه للمتابعة عبر قناتك الخاصة.
- التشغيلات المحوّلة لموظف لا تُفوتر.

## أخطاء يجب التعامل معها

| الحالة والرمز | متى |
|---|---|
| `409 agent_not_ready` | الوكيل لا يستطيع الرد بعد (مثل غياب مفتاح النموذج). راجع `readiness.blockers`. |
| `413 input_too_large` | المدخل أطول من المسموح. |
| `422 variable_missing` و`variable_unknown` | المتغيرات لا تطابق تعريفات الوكيل. |
| `429 quota_exceeded` | استُنفدت المحادثات الذكية الشهرية في الخطة المجانية (`x-should-retry: false`). |
| `429 cost_cap_exceeded` | بلغت المنظمة حد التكلفة اليومي. |

## الفوترة

السؤال الواحد يكلّف **0.25 × وزن النموذج** لكل كتلة إدخال مبدوءة من 50,000 رمز — أي 0.25 من محادثة ذكية للسؤال المعتاد. انظر [الاستخدام والفوترة](/docs/concepts/usage-and-billing/).