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

عرض بصيغة Markdown

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

طلب أساسي

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": "كم رسوم التوصيل؟"}'

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);

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"])

الاستجابة تشغيل. اقرأ 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`	كائن	قيم متغيرات الوكيل، بما فيها السرية (تُستخدم لهذا الطلب فقط).
`allow_actions`	منطقي	الافتراضي `false`: لا تُعرض الأدوات ذات الأثر. اجعله `true` للسماح بها.
`store`	منطقي	الافتراضي `true`. ومع `false` لا يُحفظ أي سجل للمحادثة (انظر أدناه).
`stream`	منطقي	بث الإجابة على شكل Server-Sent Events.
`version`	عدد صحيح	إصدار منشور يُستخدم بدل الأحدث.
`overrides`	كائن	تغييرات لهذا الطلب يسمح بها الوكيل (انظر أدناه).
`metadata`	كائن	أزواج مفتاح وقيمة خاصة بك، تُعاد مع التشغيل.
`wait_seconds`	عدد صحيح	مدة انتظار الإجابة (الافتراضي 60 والحد الأقصى 110) قبل إعادة `202`.

من الذي يسأل

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

{
  "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)، ثم أرسل:

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

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

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

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

{
  "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 من محادثة ذكية للسؤال المعتاد. انظر الاستخدام والفوترة.