استخدم حزمة OpenAI

يتحدث K-Agent صيغة OpenAI Chat Completions على المسار /openai/v1. احتفظ بحزمة OpenAI والكود الذي لديك، وغيّر إعدادين، فيجيب وكيلك عن كل طلب — بمعرفته وأدواته وضوابطه وتحويلاته.

الإعداد	القيمة
عنوان الأساس (Base URL)	https://api.k-agent.kerneltics.com/openai/v1
مفتاح API	المفتاح السري لـ K-Agent ‏(kt_sk_…)
model	المعرّف النصي للوكيل (store-assistant) أو معرّفه (agt_…)

أول طلب

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.k-agent.kerneltics.com/openai/v1",
    api_key=os.environ["KAGENT_API_KEY"],
)

completion = client.chat.completions.create(
    model="store-assistant",
    messages=[{"role": "user", "content": "كم رسوم التوصيل؟"}],
)
print(completion.choices[0].message.content)
print(completion.model_extra["kagent"])  # {"run_id": "run_…", "session": None, "handoff": None, "units": 0.25}

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.k-agent.kerneltics.com/openai/v1',
  apiKey: process.env.KAGENT_API_KEY,
});

const completion = await client.chat.completions.create({
  model: 'store-assistant',
  messages: [{ role: 'user', content: 'كم رسوم التوصيل؟' }],
});
console.log(completion.choices[0].message.content);
console.log(completion.kagent); // { run_id: 'run_…', session: null, handoff: null, units: 0.25 }

يعيد client.models.list() وكلاءك، ومعرّفاتهم النصية أسماءً للنماذج.

بلا حالة أو داخل جلسة

دون جلسة (الافتراضي) يكون كل طلب مستقلًا، مثل ask:

• آخر رسالة من المستخدم هي المدخل؛ والرسائل السابقة تُمرَّر إلى الوكيل سجلًا من المستدعي غير موثَّق؛
• رسائل system أو developer في البداية تعيد 400 system_message_not_allowed — فتعليمات الوكيل نفسه هي السارية. وإذا سمح الوكيل بتجاوز instructions_append تُستخدم تعليماتٍ إضافية لذلك الطلب بدلًا من ذلك؛
• يُفوتر مثل ask.

داخل جلسة يحتفظ K-Agent بالسجل وترسل أنت الرسالة الجديدة فقط. سمِّ الجلسة بحقل session في المستوى الأعلى (extra_body في Python) أو بالترويسة x-kagent-session. وهو جلب أو إنشاء، مثل POST /v1/sessions، ويقبل معرّف sess_ أو معرّفك external_id:

Python

completion = client.chat.completions.create(
    model="store-assistant",
    messages=[{"role": "user", "content": "وين طلبي؟"}],
    user="cus_1042",                      # your end user's ID: verified, since this is your server
    extra_body={"session": "order-8812"},  # get-or-create the session
)

JavaScript

const completion = await client.chat.completions.create(
  {
    model: 'store-assistant',
    messages: [{ role: 'user', content: 'وين طلبي؟' }],
    user: 'cus_1042', // your end user's ID: verified, since this is your server
  },
  { headers: { 'x-kagent-session': 'order-8812' } }, // get-or-create the session
);

• السجل المحفوظ هو المرجع. لا يقرأ K-Agent إلا الرسائل الواقعة بعد آخر رسالة assistant في طلبك؛ وإذا تجاهل رسائل أقدم تتضمن الاستجابة "client_history_ignored" في kagent.warnings.
• استخدام الجلسة نفسها مع وكيل مختلف يعيد 409 session_agent_mismatch.
• ما دامت المحادثة بيد فريقك (وضع الموظف) تكون الاستجابة 200 مع content فارغ وfinish_reason: "stop" وkagent.mode: "human".

البث

stream: true يعيد سلسلة الأجزاء المعتادة. وفي K-Agent تفصيل واحد: قبل data: [DONE] مباشرة يأتي جزء أخير بمصفوفة choices فارغة يحمل كائن kagent. تحقّق منه:

Python

stream = client.chat.completions.create(
    model="store-assistant",
    messages=[{"role": "user", "content": "أقدر أغير عنوان التوصيل؟"}],
    extra_body={"session": "order-8812"},
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
    else:
        kagent = chunk.model_extra["kagent"]  # run_id, session, handoff, units

JavaScript

const stream = await client.chat.completions.create(
  { model: 'store-assistant', messages: [{ role: 'user', content: 'أقدر أغير عنوان التوصيل؟' }], stream: true },
  { headers: { 'x-kagent-session': 'order-8812' } },
);
for await (const chunk of stream) {
  if (chunk.choices.length) process.stdout.write(chunk.choices[0].delta.content ?? '');
  else console.log(chunk.kagent); // run_id, session, handoff, units
}

حين يكون رد التصعيد مُعدًّا يُبث النص جولةً جولة، فلا يناقض ما تعرضه الردَّ الذي تفرضه سياستك.

امتداد kagent

تحمل كل استجابة كائن kagent بجانب الحقول القياسية (في TypeScript اقرأه بالصيغة (completion as any).kagent):

الحقل	الوصف
run_id	تشغيل K-Agent. اجلب تتبّعه عبر GET /v1/runs/{run}/steps.
session	الجلسة، إن سمّيت واحدة.
handoff	null، أو التحويل الذي أجراه الوكيل ({id, reason_type, summary, status}).
units	وحدات المحادثات الذكية التي استهلكها هذا الطلب.
mode وwarnings	تظهر عند الحاجة، مثل "human" و["client_history_ignored"].

ويجمع usage كل استدعاءات النموذج التي أجراها الوكيل للرد.

الأدوات

• أدوات الوكيل الخاصة (المدمجة وأدوات HTTP) تعمل داخل K-Agent؛ ولا تراها tool_calls.
• لاستخدام أدوات جهة العميل عرّفها في الوكيل، ثم مرّر tools بالأسماء نفسها في طلب بلا حالة. وحين يستدعي النموذج إحداها تحصل على finish_reason: "tool_calls" كالمعتاد؛ وأرسل النتيجة رسالةً بدور tool في طلبك التالي، وهو تشغيل جديد بلا حالة.
• اسم أداة لا يعرّفه الوكيل يعيد 400 tool_not_declared، وإرسال tools مع جلسة يعيد 400 tools_not_allowed_with_session. وفي الجلسات استخدم مسار أدوات جهة العميل الأصلي.

المعاملات

المعامل	السلوك
model	المعرّف النصي للوكيل أو معرّفه.
messages	حتى 100. انظر «بلا حالة أو داخل جلسة» أعلاه.
user	يُربط بـ external_id للعميل، موثّقًا.
stream	مدعوم.
temperature	يُستخدم فقط إذا سمح الوكيل بتجاوز temperature.
max_tokens وmax_completion_tokens	تُحدّ بقيمة max_reply_tokens في الوكيل.
n أكبر من 1، وlogprobs، وresponse_format مع json_schema	400 unsupported_parameter.
أي شيء آخر	يُتجاهل.

تأتي الأخطاء بصيغة OpenAI — ‏{"error": {"message", "type", "param", "code"}} — مع رموز أخطاء K-Agent الثابتة. ولا تعمل هنا إلا المفاتيح السرية، ولا تُرسل ترويسات CORS: استدعِ هذه الواجهة من خادمك.