البث
انتظار 20 ثانية حتى ينتهي الوكيل قبل رؤية أي شيء تجربة سيئة. تبث وكلاء DYPAI مخرجاتها — النص واستدعاءات الأدوات ونتائج الأدوات — في الوقت الفعلي، حتى تعرض واجهتك الردود الجزئية أثناء توليدها.
مع React SDK (موصى به)
يغلّف خطاف useChat من @dypai-ai/client-sdk/react كل آليات البث لك:
import { useChat } from '@dypai-ai/client-sdk/react'
function ChatBox() {
const {
messages, // full message history
sendMessage, // send a new message
isLoading, // true while the agent is responding
stop, // abort the current stream
error, // any error that occurred
} = useChat('my_agent_endpoint')
return (
<div>
<div className="messages">
{messages.map((m, i) => (
<div key={i} className={`msg msg-${m.role}`}>
{m.content}
</div>
))}
{isLoading && <div className="typing">...</div>}
</div>
<ChatInput
onSubmit={text => sendMessage(text)}
disabled={isLoading}
/>
{isLoading && (
<button onClick={stop}>Stop</button>
)}
{error && <div className="error">{error.message}</div>}
</div>
)
}
هذه واجهة دردشة كاملة في نحو 20 سطراً. يتحدّث messages مع وصول الرموز، فيشغّل إعادة عرض React حتى يرى المستخدمون النص يظهر تدريجياً.
سطح useChat الكامل
يُرجع useChat(endpoint, options?) كل ما تحتاجه لبناء واجهة دردشة كاملة:
const {
messages, // full message history
status, // 'ready' | 'submitted' | 'streaming' | 'error'
input, // controlled input value
setInput, // set the input value
sendMessage, // send a message
setMessages, // replace the message array
stop, // abort the current stream
isLoading, // true while the agent is responding
error, // any error that occurred
chatId, // the current conversation id
newChat, // start a fresh conversation
} = useChat('my_agent_endpoint')
استئناف محادثة
إذا استخدم وكيلك ذاكرة، مرّر id المحادثة حتى يحمّل الخطاف المحادثة الصحيحة ويحفظها:
const { messages, sendMessage } = useChat('my_agent_endpoint', {
id: 'conv-123',
})
الخيار هو id (وليس sessionId). خزّنه في الحالة (لمحادثة واحدة) أو في قاعدة بياناتك (لشريط جانبي بمحادثات متعددة). يساعد خطاف useChatList في الأخيرة — راجع الذاكرة.
HTTP الخام يستخدم session_id
عند استدعاء endpoint مباشرة (دون SDK)، حقل جسم الطلب ما زال session_id — راجع مثال الجلب الخام أدناه. خيار id هو الاسم على مستوى SDK.
ما في الرسالة
لكل رسالة في messages:
role—"user"أو"assistant"أو"tool"content— النص المعروض للمستخدمparts— أجزاء Vercel AI SDK الخام (نص واستدعاء أداة ونتيجة أداة). مفيدة إذا أردت عرض استدعاءات الأدوات بشكل خاص.
لواجهة دردشة نموذجية، استخدم content فقط. لواجهة أغنى تُظهر «الوكيل يبحث عن منتجات…»، افحص parts واعرض مكوّنات مخصصة لكل نوع جزء.
إظهار استدعاءات الأدوات في الواجهة
إذا أردت أن يرى المستخدمون ما يفعله الوكيل (مثلاً «البحث في الطلبات…» و «البحث عن المستخدم…»)، افحص parts:
messages.map((m, i) => (
<div key={i}>
{m.parts?.map((p, j) => {
if (p.type === 'text') return <span key={j}>{p.text}</span>
if (p.type === 'tool-call')
return <ToolBadge key={j} name={p.toolName} args={p.args} />
if (p.type === 'tool-result')
return <ToolResult key={j} result={p.result} />
})}
</div>
))
يعطيك هذا النمط مؤشرات «تفكير» بأسلوب ChatGPT مجاناً.
الإيقاف أثناء البث
يلغي stop() التوليد الحالي. يُحفظ الرد الجزئي في messages (مقطوعاً)، وتحفظ الذاكرة ما وُلّد حتى تلك النقطة.
مفيد لـ:
- زر «إيقاف التوليد»
- الإلغاء عندما ينتقل المستخدم بعيداً
- تحديد معدّل وكيل جامح
دون SDK
إذا لم تستخدم React، أو أردت بناء واجهتك، استدعِ endpoint مباشرة. تبث endpoints الوكيل باستخدام بروتوكول Vercel AI SDK UI Message Stream عبر Server-Sent Events. تتضمن الردود x-vercel-ai-ui-message-stream: v1.
const res = await fetch(`${DYPAI_URL}/api/v0/my_agent_endpoint`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${jwt}`,
'Accept': 'text/event-stream',
},
body: JSON.stringify({
messages: [{ role: 'user', content: 'Hello' }],
session_id: 'conv-123',
}),
})
const reader = res.body.getReader()
const decoder = new TextDecoder()
while (true) {
const { value, done } = await reader.read()
if (done) break
// Each chunk contains one or more SSE events.
// See the Vercel AI SDK docs for the full protocol.
console.log(decoder.decode(value))
}
لمعظم الحالات، استخدم SDK — يتولى إعادة الاتصال وحدود الأخطاء وتنسيق الرسائل لك.
استدعاءات دون بث
إذا احتجت رداً نهائياً كقيمة JSON عادية (لاستدعاء من خادم إلى خادم أو cron أو webhook لا يتعامل مع التدفقات)، استدعِ الوكيل كأي endpoint آخر بـ dypai.api.post:
const { data, error } = await dypai.api.post('my_agent_endpoint', {
prompt: 'Summarize today\'s orders',
})
console.log(data.content) // final text answer
console.log(data.usage) // tokens used
console.log(data.steps) // tool calls made
تنتظر DYPAI تلقائياً الرد الكامل وتُرجع الكائن النهائي.
المخرج المنظَّم يصل في data.object
إذا كان للوكيل output_schema مضبوط، يكون الناتج في data.object (مطابقاً لمخططك)، لا data.content. راجع المخرج المنظَّم.
المزالق الشائعة
| المشكلة | الإصلاح |
|---|---|
| الرسائل لا تظهر | تأكد من أن endpoint الوكيل مضبوط على مصادقة jwt وأن SDK مصادَق. |
يُعاد تعيين messages عند إلغاء التركيب | حالة useChat محلية. للمحادثات الدائمة، استخدم الذاكرة ومرّر id المحادثة. |
| يتوقف البث | راجع max_iterations — إذا كان الوكيل يتكرر على الأدوات، قد يستغرق أطول مما تتوقع. |
| استدعاءات الأدوات لا تظهر | يكشف SDK أجزاء استدعاء الأداة فقط عندما تقرأ message.parts. يتضمن message.content النص النهائي فقط. |