الرد المتدفق

POST /v1/agents/{agent_id}/chat/stream يأخذ الطلب نفسه تمامًا الذي تأخذه نقطة نهاية الدردشة المتزامنة: نفس الجسم، نفس ترويستي Authorization وIdempotency-Key، نفس صلاحية full، نفس قواعد المحادثة والفوترة ورموز الأخطاء. الفرق الوحيد هو وسيلة النقل: الرد من نوع text/event-stream.

الأحداث

لكل حدث اسم ويحمل سطر data واحدًا بصيغة JSON.

الحدث	البيانات	متى
`response.created`	`{"request_id", "conversation_id"}`	فور تحديد المحادثة
`response.output_text.delta`	`{"delta": "..."}`	لكل جزء من نص الإجابة أثناء توليد النموذج له؛ يتكرر
`response.completed`	رد الدردشة الكامل (`request_id` و`conversation_id` و`message` و`usage`)	دائمًا آخر حدث في التدفق الناجح
`error`	`{"code", "message", "request_id"}`	دائمًا آخر حدث في التدفق الفاشل

event: response.created
data: {"request_id":"7f20a5f0-...","conversation_id":"1c2e..."}

event: response.output_text.delta
data: {"delta":"The basic"}

event: response.output_text.delta
data: {"delta":" plan is $19 per month."}

event: response.completed
data: {"request_id":"7f20a5f0-...","conversation_id":"1c2e...","message":{"id":"66e0...","role":"assistant","content":"The basic plan is $19 per month.","created_at":"2026-09-13T12:00:00Z"},"usage":{"prompt_tokens":120,"completion_tokens":45,"total_tokens":165,"charged_usd":"0.00123400"}}

نص الاستدلال ونشاط الأدوات لا يكونان جزءًا من التدفق أبدًا. response.completed يحمل دائمًا النص النهائي الكامل، لذا يستطيع العميل الذي فاتته بعض الأجزاء أن يعتمد عليه بدلًا من الأجزاء المتسلسلة.

الأخطاء في التدفق

الإخفاقات قبل إنشاء التدفق (مفتاح غير صالح، خطأ تحقق، idempotency_conflict، conversation_busy، وكيل معطّل، حد معدل) هي أغلفة أخطاء JSON عادية بحالة HTTP الخاصة بها؛ تحقق من response.ok قبل أن تبدأ قراءة الأحداث. بعد إرسال الترويسات تكون الحالة 200 بالفعل. الإخفاق بعد تلك النقطة (مثل insufficient_balance أو internal_error) يصل كحدث error، بنفس حقول الغلاف، ويغلق التدفق.

الانقطاع وإعادة المحاولة

العميل الذي يقطع الاتصال لا يوقف الرد: يستمر توليده وتخزينه، ويُكمَل سجل التكرار الآمن. إعادة المحاولة بنفس Idempotency-Key تبث response.created ثم مباشرة response.completed بالنتيجة المخزّنة؛ الأجزاء لا تُعاد. راجع التكرار الآمن.

أمثلة

curl -N -X POST "$CHATTLER_BASE_URL/v1/agents/$CHATTLER_AGENT_ID/chat/stream" \
  -H "Authorization: Bearer $CHATTLER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "customer-123", "message": "Tell me more"}'

import json
import os
import uuid

import httpx


def stream_chat(external_user_id: str, message: str) -> dict:
    url = f"{os.environ['CHATTLER_BASE_URL']}/v1/agents/{os.environ['CHATTLER_AGENT_ID']}/chat/stream"
    headers = {
        "Authorization": f"Bearer {os.environ['CHATTLER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    }
    with httpx.stream("POST", url, headers=headers, timeout=120,
                      json={"external_user_id": external_user_id, "message": message}) as response:
        if response.status_code >= 400:
            response.read()
            raise RuntimeError(response.json()["error"])
        event, completed = None, None
        for line in response.iter_lines():
            if line.startswith("event: "):
                event = line[len("event: "):]
            elif line.startswith("data: "):
                data = json.loads(line[len("data: "):])
                if event == "response.output_text.delta":
                    print(data["delta"], end="", flush=True)
                elif event == "response.completed":
                    completed = data
                elif event == "error":
                    raise RuntimeError(f"{data['code']}: {data['message']}")
            elif line == "":
                event = None
        return completed


stream_chat("customer-123", "Tell me more")

const baseUrl = process.env.CHATTLER_BASE_URL;
const agentId = process.env.CHATTLER_AGENT_ID;
const apiKey = process.env.CHATTLER_API_KEY;

async function streamChat(externalUserId, message, onDelta) {
  const response = await fetch(`${baseUrl}/v1/agents/${agentId}/chat/stream`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Idempotency-Key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ external_user_id: externalUserId, message }),
  });
  if (!response.ok) {
    const body = await response.json();
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  let completed = null;
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    let boundary;
    while ((boundary = buffer.indexOf("\n\n")) >= 0) {
      const frame = buffer.slice(0, boundary);
      buffer = buffer.slice(boundary + 2);
      const event = frame.match(/^event: (.+)$/m)?.[1];
      const data = JSON.parse(frame.match(/^data: (.+)$/m)?.[1] ?? "{}");
      if (event === "response.output_text.delta") onDelta(data.delta);
      else if (event === "response.completed") completed = data;
      else if (event === "error") throw new Error(`${data.code}: ${data.message}`);
    }
  }
  return completed;
}

const result = await streamChat("customer-123", "Tell me more", (t) => process.stdout.write(t));
console.log("\n", result.usage);

استخدم curl -N (بلا تخزين مؤقت) لرؤية الأحداث فور وصولها. في المتصفحات لا يستطيع EventSource إرسال أجسام POST ولا ترويسات مخصصة، والمفتاح يجب ألا يصل إلى المتصفح أصلًا؛ ابثّ من خادمك الخاص ومرّر النص إلى العميل.

البداية

الأدلة

الرد المتدفق

الأحداث

الأخطاء في التدفق

الانقطاع وإعادة المحاولة

أمثلة

​الأحداث

​الأخطاء في التدفق

​الانقطاع وإعادة المحاولة

​أمثلة

الأحداث

الأخطاء في التدفق

الانقطاع وإعادة المحاولة

أمثلة