أدوات العميل
دع الوكيل الصوتي يشغّل دوالًا في متصفح المستخدم، مثل البحث عن طلب أو فتح صفحة، وينطق النتيجة.
أداة العميل دالة في صفحتك يستطيع الوكيل استدعاءها أثناء المحادثة. تعرّفها في طلب الجلسة وتعالجها في المتصفح. يقرر الوكيل متى يستدعيها بناءً على وصفها، وينتظر النتيجة، ويستخدمها في رده.
عرّف أداة
أضف الأداة إلى agent.client_tools عندما تبدأ الجلسة:
{
"agent": {
"prompt": "You help customers track their orders.",
"client_tools": [
{
"name": "lookup_order",
"description": "Look up the delivery status of an order by its number.",
"parameters": {
"type": "object",
"properties": {
"order": { "type": "string", "description": "Order number, such as T-1182." }
},
"required": ["order"]
}
}
]
}
}| الحقل | مطلوب | المعنى |
|---|---|---|
name | نعم | من 1 إلى 64 حرفًا: حروف وأرقام و_ و-. فريد داخل الجلسة. الاسمان client_tool_call وend_call محجوزان. |
description | نعم | ما تفعله الأداة ومتى تُستخدم، بحد أقصى 4,096 حرفًا. يعتمد عليه الوكيل ليقرر متى يستدعي الأداة. |
parameters | لا | كائن JSON Schema يصف الوسائط. احذفه للأداة التي لا تأخذ وسائط. |
تستطيع الجلسة تعريف 16 أداة على الأكثر؛ راجع الحدود.
عالج الاستدعاء في المتصفح
مرّر معالجًا واحدًا لكل أداة معرّفة إلى AgentSession.start(). يتلقى المعالج الوسائط
التي اختارها الوكيل ويعيد النتيجة:
import { AgentSession } from '@humain-voice/agent';
const call = await AgentSession.start({
token: () => fetch('/agent-session', { method: 'POST' }).then((res) => res.json()),
clientTools: {
lookup_order: async ({ order }) => {
const res = await fetch(`/orders/${encodeURIComponent(String(order))}`);
if (!res.ok) throw new Error('order not found');
const body = await res.json();
return { status: body.status, eta: body.eta };
},
},
});| القاعدة | التفاصيل |
|---|---|
| النتيجة | أي قيمة JSON. يقرؤها الوكيل ويجيب بكلماته. |
| رد مقترح | أعد { "response": "…" } لتعطي الوكيل الجملة التي يقولها. |
| الفشل | أطلق خطأ. يخبر الوكيل المستخدم أنه لم يتمكن من إكمال الإجراء. |
| المهلة | 120 ثانية؛ يفشل بعدها استدعاء الأداة. |
| حجم النتيجة | 15 KiB من JSON. أعد فقط ما يحتاجه الوكيل. |
| معالج مفقود | تفشل استدعاءات تلك الأداة، ويُبلغ onError بالرمز CLIENT_TOOL_NOT_HANDLED. |
أثناء تشغيل الأداة يستطيع الوكيل ملء الصمت؛ اضبط ذلك بـ عبارات انتظار الأدوات.
دع الوكيل ينهي المكالمة
لكل جلسة أداة مدمجة اسمها end_call. يستخدمها الوكيل عندما تنتهي المحادثة، مثلًا
بعد أن يودّعه المستخدم؛ وتنتهي المكالمة بـagent_ended. أخبر الوكيل في التعليمات متى ينهي
المكالمة، مثل: "عندما لا تبقى لدى المستخدم أسئلة، ودّعه وأنهِ المكالمة."
عالج الأدوات دون SDK
يستدعي الوكيل الأدوات عبر LiveKit RPC. سجّل الطريقة client_tool_call على المشارك
الخاص بالمستخدم. حمولة الطلب JSON:
{ "tool": "lookup_order", "arguments": { "order": "T-1182" } }استجب بالنتيجة كسلسلة JSON، أو بـ{ "ok": false, "error": "…" } عند الفشل:
room.registerRpcMethod('client_tool_call', async ({ payload }) => {
const { tool, arguments: args } = JSON.parse(payload);
if (tool !== 'lookup_order') return JSON.stringify({ ok: false, error: `unknown tool ${tool}` });
const res = await fetch(`/orders/${encodeURIComponent(String(args.order))}`);
if (!res.ok) return JSON.stringify({ ok: false, error: 'order not found' });
return JSON.stringify(await res.json());
});بقية العقد الخام في دون SDK.