Voice Agent

أدوات العميل

دع الوكيل الصوتي يشغّل دوالًا في متصفح المستخدم، مثل البحث عن طلب أو فتح صفحة، وينطق النتيجة.

أداة العميل دالة في صفحتك يستطيع الوكيل استدعاءها أثناء المحادثة. تعرّفها في طلب الجلسة وتعالجها في المتصفح. يقرر الوكيل متى يستدعيها بناءً على وصفها، وينتظر النتيجة، ويستخدمها في رده.

عرّف أداة

أضف الأداة إلى 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.

في هذه الصفحة