# Wkala documentation Release 0.1.0. Generated from the same canonical pages as the documentation site. # شغّل وكيلك الأول ثبّت حزمة SDK، وأنشئ جلسة، وتابع تنفيذًا كاملًا عبر البث من خادمك الخلفي. ## قبل البدء أنشئ حسابًا في Wkala. أكّد بريدك الإلكتروني. انتظر موافقة المشغّل. يعيّن لك المشغّل المزوّد والنماذج والحدود. أنشئ مفتاحًا في [لوحة التحكم](/dashboard/keys). ابدأ بصلاحيتي القراءة والتشغيل. أضف صلاحية التهيئة لتسجيل الأدوات أو المهارات أو ملفات التعريف. احتفظ بمفتاح الخدمة في خادمك الخلفي. لا تضعه في حزمة المتصفح أو متغيّر بيئة عام أو موجّه ذكاء اصطناعي منسوخ. يستخدم عميل المتصفح المسار `/app` من الأصل نفسه. ## ١. ثبّت حزمة SDK ### Python تُدعَم Python بالإصدار 3.11 أو أحدث. ثبّت حزمة الإصدار القابلة للتنزيل. ```bash python -m pip install "wkala @ https://wkala.okal.io/downloads/wkala-0.1.0-py3-none-any.whl" ``` لخدمة Go مباشرة، مرّر `base_url="http://localhost:8080/v1"` عند إنشاء العميل. يستخدم مدخل Compose العنوان `http://localhost:8088/v1`، ويستخدم التطوير الأصلي متعدد الخدمات العنوان `http://localhost:18080/v1`، ويستخدم الإنتاج أصلًا عامًا مُهيأً. يقبل Python أيضًا عنوان الأصل دون إصدار للتوافق. ### TypeScript استخدم Node بالإصدار 22.13 أو أحدث. ثبّت حزمة الإصدار القابلة للتنزيل. ```bash npm install "https://wkala.okal.io/downloads/wkala-client-0.1.0.tgz" ``` لخدمة Go مباشرة، مرّر `baseUrl: "http://localhost:8080/v1"` عند إنشاء عميل الخادم. يستخدم مدخل Compose العنوان `http://localhost:8088/v1`، ويستخدم التطوير الأصلي متعدد الخدمات العنوان `http://localhost:18080/v1`، ويستخدم الإنتاج أصلًا عامًا مُهيأً. ## ٢. اضبط المفتاح اضبط هذا المتغيّر في بيئة خادمك الخلفي: ```bash export WKALA_API_KEY="your-private-service-key" ``` ## ٣. أنشئ تشغيلًا وراقبه ينشئ هذا المثال جلسة ويرسل مهمة لإعداد قائمة مراجعة للإصدار. يراقب التحديثات ويفحص النتيجة النهائية. احفظ معرّف الطلب المُولَّد قبل الإرسال إذا كان تطبيقك يحتاج إلى التعافي بعد إعادة التشغيل. ### Python احفظ المثال باسم `first_agent.py`: ```python import asyncio import os import uuid from wkala import AgentClient, SnapshotUpdate async def main(): async with AgentClient(api_key=os.environ["WKALA_API_KEY"]) as agents: session = await agents.sessions.create(title="First task") request_id = str(uuid.uuid4()) run = await session.send( "Draft a concise release checklist for a web application.", idempotency_key=request_id, ) print("Session:", session.id, "Run:", run.id) async with run.stream() as stream: async for update in stream: if isinstance(update, SnapshotUpdate): print("Snapshot restored") else: print(update.type, update.model_dump(mode="json", by_alias=True)) result = await run.result() print(result.status, result.stop_reason) print(result.messages) asyncio.run(main()) ``` شغّله: ```bash python first_agent.py ``` ### TypeScript احفظ هذا المثال المتوافق مع JavaScript باسم `first_agent.mjs`: ```typescript import { createServerClient } from "@wkala/client/server" const apiKey = process.env.WKALA_API_KEY if (!apiKey) { throw new Error("Set WKALA_API_KEY in your backend environment") } const agents = createServerClient({ apiKey }) const session = await agents.sessions.create({ title: "First task" }) const requestId = crypto.randomUUID() const run = await session.send( "Draft a concise release checklist for a web application.", { idempotencyKey: requestId }, ) console.log("Session:", session.id, "Run:", run.id) for await (const event of run.events()) { console.log(event.type, event.data) } const result = await run.result() console.log(result.run.status, result.run.stop_reason) console.log(result.messages) ``` شغّله: ```bash node first_agent.mjs ``` تعيد `send()` التحكم بعد قبول الطلب. تواصل الخدمة التنفيذ بينما يراقبه تطبيقك. تشمل النتيجة الرسائل واستدعاءات الأدوات واستدعاءات الخادم الخلفي والتفاعلات والاستخدام. تظل عمليات التشغيل الفاشلة أو الملغاة قابلة للفحص. تحقّق من الحالة وسبب التوقف. إذا احتاج التشغيل إلى إدخال، فقد تظل المراقبة مفتوحة حتى يستجيب مكوّن آخر مخوّل. اتبع دليل [الموافقات والأسئلة](/docs/raw/interactions?locale=ar). ### Python يُتاح الإصدار 0.1.0 كحزمة wheel قابلة للتنزيل. لا يفترض أمر التثبيت نشر الحزمة في سجلّ حزم. تجد قيم التحقّق وروابط التنزيل في [الصفحة الرئيسية للتوثيق](/llms.txt?locale=ar). ### TypeScript يُتاح الإصدار 0.1.0 كأرشيف npm قابل للتنزيل. لا يفترض أمر التثبيت نشر الحزمة في سجلّ حزم. تجد قيم التحقّق وروابط التنزيل في [الصفحة الرئيسية للتوثيق](/llms.txt?locale=ar). ## ٤. اختر الخطوة التالية - [ابثث الرسائل والأدوات](/docs/raw/streaming?locale=ar). - [اربط أدوات الخادم الخلفي](/docs/raw/backend-tools?locale=ar). - [اربط واجهة React](/docs/raw/react?locale=ar) عبر خادمك الخلفي الذي يتحقّق من الهوية. - [تعرّف على التكلفة والحدود](/docs/raw/usage-and-limits?locale=ar) قبل قبول أعمال بيئة الإنتاج. --- # بثّ الرسائل والأدوات والنتائج راقب التنفيذ كاملًا أثناء حدوثه، مع حالة محفوظة بشكل دائم وسلوك مدمج لإعادة الاتصال. ## ما الذي يُبثّ؟ قد ينتج عن التنفيذ رسائل واستدعاءات أدوات ونتائجها واستدعاءات للخادم الخلفي وتحديثات تقدّم وبيانات استخدام وطلبات إدخال. لا يعني اكتمال رسالة اكتمال التشغيل. تصل وسائط الأدوات بمستوى التفصيل الذي توفّره الخدمة. لا تنشئ API أجزاءً مصطنعة من رموز الوسائط. لسجلّات الأدوات واستدعاءات الخادم الخلفي معرّفات مستقلة. قد ترسل أداة واحدة عدة طلبات إلى الخادم الخلفي. وقد لا يكون للأداة المدمجة في بيئة التنفيذ أي استدعاء للخادم الخلفي. لا تربط معرّفاتها ببعضها. ولا تفترض أن الآثار الفعلية على بيانات العمل تحدث مرة واحدة فقط. ## راقب التحديثات ### Python يحمّل بث Python عالي المستوى لقطة متّسقة، ويطبّق الأحداث بالترتيب، ويتجاهل التكرارات، ويستعيد الحالة عند غياب أحد المتطلبات. استبدل العرض عند وصول `SnapshotUpdate`. ```python from wkala import SnapshotUpdate, ToolUpdated, MCPInvocationUpdated async with run.stream() as stream: async for update in stream: if isinstance(update, SnapshotUpdate): print(stream.state.runs[run.id].status) elif isinstance(update, ToolUpdated): tool = update.data.tool print(tool.title, tool.status) print(tool.arguments, tool.output, tool.content) elif isinstance(update, MCPInvocationUpdated): call = update.data.invocation print(call.server_name, call.status, call.result) ``` ### TypeScript استخدم مخزن TypeScript الذي تعيده `run.stream()` أو استخدم `useSession()` في React للحصول على لقطة متّسقة وتحديثات مرتبة ومعالجة للتكرارات والتعافي. المُكرِّر `run.events()` أدناه منخفض المستوى. يتحقّق من التسلسل وقد يطلق `RecoveryRequired` عند وجود فجوة. احصل على لقطة جديدة بدلًا من المتابعة من حالة ناقصة. ```typescript const observer = new AbortController() for await (const event of run.events({ signal: observer.signal })) { switch (event.type) { case "message.delta": console.log(event.data.message_id, event.data.part_id, event.data.delta) break case "tool.updated": console.log(event.data.tool) break case "mcp.invocation.updated": console.log(event.data.invocation.result) break case "interaction.updated": console.log(event.data.interaction) break case "run.updated": console.log(event.data.run.status, event.data.run.usage) break } } ``` تحلّ سجلّات `tool.updated` و`message.updated` المعتمدة محل الإصدارات السابقة من السجلّ نفسه. تحافظ النتائج على أنواع JSON، بما فيها المصفوفات والقيم المفردة وحقلا MCP المسمّيان `structuredContent` و`isError`. قد يتضمّن محتوى الرسائل الغني نصوصًا وصورًا أو صوتًا مضمّنًا وموارد وروابط موارد. أظهر المحتوى غير المدعوم بوضوح. لا تجلب روابط الموارد العشوائية تلقائيًا. ## المراقبة والتنفيذ مستقلّان يوقف إغلاق البث أو إزالة المكوّن أو فقدان اتصال المتصفح المراقبة. يستمر التشغيل المقبول. اطلب الإلغاء صراحةً عندما تريد إيقاف التنفيذ: ### Python ```python await run.cancel() ``` ### TypeScript ```typescript await run.cancel() ``` ينتهي المُكرِّر المحدّد بنطاق تشغيل بعد حدثه النهائي. راقب الجلسة أو اطلب لقطة لاحقة لرؤية تسوية عملية خلفية غير مؤكدة. تتطلّب `tool.incomplete` أو الاستدعاءات بالحالة `uncertain` تسويةً من التطبيق. ## سلوك الوكيل الوسيط استخدم [وكيل Next الوسيط](/docs/raw/nextjs?locale=ar) و[مثال الخادم الخلفي للعميل](/docs/raw/python-backend?locale=ar) المرفقين للحفاظ على التحقّق من الهوية والملكية. يستخدم المثال المرفق خادم Python خلفيًا. يجب أن يمرّر الوكيل ترويسات الاستجابة قبل استهلاك جسمها. يجب أن يعطّل التخزين المؤقت للأحداث ويُبقي الجسم مفتوحًا طوال المراقبة. يمكن لمهلة الاتصال أن تحدّ وقت بدء الاستجابة. يجب ألّا تقطع بثًّا طويلًا يعمل بصورة سليمة. بث SDK ليس استجابة رموز عامة لروبوت محادثة. فالجلسات وعمليات التشغيل الدائمة والأدوات والصلاحيات والاستخدام أجزاء مستقلة من حالة التنفيذ نفسها. --- # أبقِ خادمك الخلفي متحكّمًا ضع التحقّق من الهوية والملكية ومنطق العمل بين واجهتك الأمامية وحزمة Wkala SDK. ## حدود التطبيق يسجّل المستخدمون الدخول إلى تطبيقك. يتحقّق خادمك الخلفي من صلاحياتهم، ويحتفظ بمفتاح خدمة Wkala، ولا يرسل إلا الأعمال المصرّح بها. تتحقّق Wkala من مفتاح الخادم الخلفي وتفرض حدود الحساب؛ لكنها لا تحلّ محل نموذج المستخدمين في تطبيقك. يوجد المثال الكامل القابل للتشغيل والمكتوب بلغة Python في `apps/customer-backend`. يتضمّن المثال: - مسارات FastAPI وتخزينًا دائمًا في PostgreSQL عبر SQLAlchemy. - جلسات HttpOnly وفحوصات Origin وCSRF والتحقق من ملكية الجلسات. - أدوات مدمجة موقّعة. - إيصالًا لعملية عمل يُسجَّل في المعاملة نفسها التي تسجّل تأثيرها الفعلي. لا يتضمن الإصدار مثال خادم عميل خلفي مكتوبًا بلغة TypeScript. يتطلب وكيل Next المرفق خادم العميل المكتوب بلغة Python. يستخدم المسار `/dashboard/playground` في تطبيق Next ذلك الخادم الخلفي وحزمة React SDK المشتركة. ## عميل واحد طوال دورة حياة التطبيق ### Python يوفّر عميل الخادم نقطة نهاية الخدمة المستضافة داخليًا. لخدمة Go مباشرة، مرّر `base_url="http://localhost:8080/v1"`. يستخدم مدخل Compose العنوان `http://localhost:8088/v1`، ويستخدم التطوير الأصلي متعدد الخدمات العنوان `http://localhost:18080/v1`، ويستخدم الإنتاج أصلًا عامًا مُهيأً. يقبل Python أيضًا عنوان الأصل دون إصدار للتوافق. ```python from contextlib import asynccontextmanager import os from fastapi import FastAPI from wkala import AgentClient @asynccontextmanager async def lifespan(app: FastAPI): async with AgentClient( api_key=os.environ["WKALA_API_KEY"], ) as agents: app.state.agents = agents yield app = FastAPI(lifespan=lifespan) ``` ### TypeScript أنشئ عميل الخادم مرة واحدة وأعِد استخدامه طوال دورة حياة التطبيق. يوفّر العميل نقطة نهاية الخدمة المستضافة داخليًا. لخدمة Go مباشرة، مرّر `baseUrl: "http://localhost:8080/v1"`. يستخدم مدخل Compose العنوان `http://localhost:8088/v1`، ويستخدم التطوير الأصلي متعدد الخدمات العنوان `http://localhost:18080/v1`، ويستخدم الإنتاج أصلًا عامًا مُهيأً. ```typescript import { createServerClient } from "@wkala/client/server" const apiKey = process.env.WKALA_API_KEY if (!apiKey) { throw new Error("Set WKALA_API_KEY in your backend environment") } const agents = createServerClient({ apiKey }) ``` ## أدرج منطق العمل قبل قبول التنفيذ تمثّل هذه الدالة نقطة تكامل في خادمك الخلفي. استمد هوية المستخدم ومعرّف الجلسة المملوكة له ومعرّف طلب العمل المحفوظ بشكل دائم من تطبيقك الذي تحقّق من الهوية ومن قاعدة بياناتك. لا تثق في بيانات JSON التي يمرّرها المتصفح للحصول على هذه القيم. ### Python ```python from wkala import AgentClient async def start_order_review( agents: AgentClient, *, user_id: str, owned_session_id: str, persisted_request_id: str, order_id: str, approved_company_tool_id: str, ): session = agents.sessions.handle(owned_session_id) return await session.send( f"Review order {order_id} and explain the next steps.", idempotency_key=persisted_request_id, subject={"id": user_id}, context={"order_id": order_id}, mcp_server_ids=[approved_company_tool_id], ) ``` ### TypeScript ```typescript import type { AgentClient } from "@wkala/client" async function startOrderReview( agents: AgentClient, userId: string, ownedSessionId: string, persistedRequestId: string, orderId: string, approvedCompanyToolId: string, ) { const session = agents.sessions.handle(ownedSessionId) return session.send( `Review order ${orderId} and explain the next steps.`, { idempotencyKey: persistedRequestId, subject: { id: userId }, context: { order_id: orderId }, mcp_server_ids: [approvedCompanyToolId], }, ) } ``` تحقّق من الملكية قبل الإرسال والقراءة والبثّ والإلغاء والردّ على التفاعلات وجلب الموارد التابعة. يجب ألّا يسمح وكيل المتصفح الوسيط المتاح للعامة للمستخدم بما يلي: - تسجيل نقاط نهاية MCP عشوائية. - تغيير ملف تعريف ذي امتيازات. - تقديم هوية موثوقة لمستخدم آخر. - اختيار مضيف الخدمة الذي تُمرَّر إليه الطلبات. ## مرّر الحالة لا الأسرار استخدم عقد المسارات `/app` المرفق عند ربط [React](/docs/raw/react?locale=ar) أو [Next.js](/docs/raw/nextjs?locale=ar). يتلقّى `AgentClient` في المتصفح عنوان URL أساسيًا من الأصل نفسه ودالة استدعاء للتحقّق من CSRF. ولا يتضمّن خيارًا لمفتاح API. يتحقّق خادمك الخلفي من هوية صاحب الطلب ومن الملكية، ثم يستخدم عميل SDK الخاص به لاستدعاء Wkala. إذا أتحت نقطة نهاية أحداث منفصلة خاصة بمنطق عملك، فسلسِل لقطات الحالة الأولية والأحداث اللاحقة بصيغة تطبيق موثّقة. لا تحذف حالة اللقطة الأولية وتتوقّع أن يعيد متصفح بدأ للتو بناء الرسائل السابقة اعتمادًا على التحديثات الجزئية المستقبلية وحدها. يتولّى المثال المرفق بالفعل معالجة عقد الجلسة كاملًا. ## أدوات العمل المدمجة استخدم أدوات MCP المصرّح بها للوصول إلى قاعدة بياناتك وخدماتك. يوفّر مثال Python المرفق مكوّنًا مساعدًا يستضيف الأدوات داخل FastAPI. لا يتوفر مكوّن استضافة مماثل في TypeScript. راجع [أدوات الخادم الخلفي](/docs/raw/backend-tools?locale=ar) لإرشادات الخيارين. لا تُرفَع دوالك إلى البنية التحتية للوكيل. ## اختبر حدود التطبيق اختبر الحالات التالية على الأقل: - مستخدمَين مختلفَين للتطبيق. - محاولة قراءة جلسة المستخدم الآخر. - هوية مزوّرة. - طلب عمل مكرّرًا. - انقطاع البثّ. - تأثيرًا لأداة لم تتّضح نتيجته. لا يكفي التحقّق من الملكية في الواجهة الأمامية وحدها. يجب أن تعيد إعادة الاتصال المراقبة دون قبول عملية تشغيل أخرى. --- # عرّف الأدوات داخل خادمك الخلفي امنح الوكلاء وصولًا إلى دوال Python المصرّح بها دون نقل منطق العمل خارج تطبيقك. ### Python ## ثبّت المكوّن المساعد للخادم الخلفي ```bash python -m pip install "wkala[mcp,postgres] @ https://wkala.okal.io/downloads/wkala-0.1.0-py3-none-any.whl" fastapi uvicorn ``` توفّر إضافة MCP الاختيارية حزمة الخادم القياسية. وتوفّر إضافة PostgreSQL سجلّ إيصالات محفوظًا بشكل دائم. يسجّل المكوّن المساعد واصفًا، ويتحقّق من سياق الاستدعاء الموقّع، ويربط نقطة نهاية يمكن الوصول إليها. ولا يحوّل دوالك إلى صيغة قابلة للنقل، ولا يفتح نفقًا لاتصال عامل تنفيذ. ## مضيف أدوات كامل باستخدام FastAPI اضبط `INVENTORY_MCP_URL` على نقطة النهاية التي تستطيع خدمة Wkala الوصول إليها، مثل `https://backend.example/internal/mcp/inventory/`. واضبط `MCP_STATE_DATABASE_URL` على قاعدة بيانات PostgreSQL خاصة. احتفظ بمفتاح التوقيع بشكل دائم عبر عمليات إعادة التشغيل. المخزون الموجود في الذاكرة في هذا المثال مخصّص عمدًا للقراءة فقط. استبدله باستعلام إلى قاعدة بياناتك يراعي الصلاحيات. اضبط `WKALA_API_KEY` في خادمك الخلفي. يتصل العميل بخدمة Wkala افتراضيًا. ```python from contextlib import asynccontextmanager import os from fastapi import FastAPI from mcp.server import MCPServer from pydantic import BaseModel from wkala import AgentClient from wkala.mcp import ( BackendMCP, current_invocation, load_or_create_signing_key, ) class InventoryItem(BaseModel): name: str available: int server = MCPServer("Inventory") @server.tool() async def get_inventory(item: str) -> InventoryItem: authority = current_invocation() owned = { "alice": {"notebook": 12}, "bob": {"pen": 5}, } stock = owned.get(authority.subject, {}) if item not in stock: raise PermissionError("Item is unavailable to this account member") return InventoryItem(name=item, available=stock[item]) binding = BackendMCP( server, name="inventory", url=os.environ["INVENTORY_MCP_URL"], signing_key=load_or_create_signing_key("./data/inventory-signing.key"), allowed_tools=["get_inventory"], state_url=os.environ["MCP_STATE_DATABASE_URL"], ) @asynccontextmanager async def lifespan(app: FastAPI): async with AgentClient( api_key=os.environ["WKALA_API_KEY"], ) as agents: async with binding.lifespan(agents): app.state.agents = agents app.state.inventory = binding yield app = FastAPI(lifespan=lifespan) app.mount(binding.mount_path, binding.app) ``` يحتاج المفتاح المستخدم للتسجيل إلى نطاق صلاحية التهيئة. شغّل تطبيق HTTP، ثم تحقّق من صلاحية الواصف من مهمة تهيئة أولية. لا تتحقّق من نقطة نهاية مطلوبة قبل أن يبدأ الخادم الاستماع للطلبات. ```python # Run after your HTTP application is accepting requests. await agents.mcp_servers.validate(registered_server_id) session = await agents.sessions.create(title="Inventory check") run = await session.send( "How many notebooks are available?", idempotency_key=persisted_request_id, subject={"id": authenticated_user_id}, mcp_server_ids=[registered_server_id], ) ``` يكون المعرّف المسجّل هو `binding.attachment.id` بعد التسجيل خلال دورة حياته. احفظه بشكل دائم أو اقرأه من كائن الربط الذي جرت تهيئته في خادمك الخلفي. تأتي الهوية الموثوقة من تسجيل الدخول إلى تطبيقك. وليست وسيطًا يُسمح للنموذج باختلاقه. ## قيّد الصلاحيات لا تتيح قائمة `allowed_tools` الفارغة أي أدوات. وتسمح `['*']` صراحةً بكل أداة مكتشفة. استخدم قائمة سماح بأسماء محدّدة لتكاملات العمل. تمنع الأدوات المطلوبة غير الجاهزة قبول التنفيذ. وتحتفظ التحديثات بسجلّ المراجعات للأعمال التي قُبلت بالفعل. توفّر `current_invocation()` الحساب والهوية اللذين جرى التحقّق منهما، ومعرّفات عملية التشغيل والجلسة، ومعرّف الاستدعاء، والموعد النهائي، وبصمة الطلب، ومراجعة الخادم. استخدم هذه القيم للتحقّق من الصلاحيات على مستوى السجلّ وللتدقيق. يثبت الاستدعاء الموقّع مصدره. لكنه لا يضمن بمفرده حدوث التأثير الفعلي مرة واحدة فقط. في عمليات الكتابة، سجّل إيصال الاستدعاء أو إيصال منع تكرار عملية العمل وتأثيرها الفعلي في معاملة قاعدة البيانات نفسها. تحقّق من نتيجة العملية الملتبسة وسوِّ حالتها بدلًا من إعادة محاولتها عشوائيًا. يتضمّن الخادم الخلفي للعميل المرفق هذا النمط لتحديث طلب شراء. ## متطلّبات الشبكة تبقى الأدوات المدمجة في خادمك الخلفي، لكن يجب أن تكون نقطة نهايتها المرتبطة قابلة للوصول من خدمة Wkala. تُدعَم الشبكات الخاصة عندما يسمح المشغّل بالوجهة صراحةً. إذا تعذّرت الاتصالات الواردة، فلن يتمكّن هذا المكوّن المساعد المعتمد على HTTP من الوصول إلى دوالك. ولا يتضمّن هذا الإصدار نفقًا لاتصال صادر من عامل تنفيذ. ### TypeScript لا تتضمن حزمة TypeScript المكوّن المساعد `BackendMCP` لاستضافة الأدوات المتاح في Python. استضف خادم MCP مستقلًا واتبع [دليل MCP البعيد](/docs/raw/remote-tools?locale=ar). يجب أن يسمح المشغّل بوجهة الخادم. احتفظ بتفويض عمليات التطبيق وبيانات الاعتماد في خادمك الخلفي. --- # ربط خادم MCP بعيد اربط خدمة أدوات قائمة بنقطة نهاية صريحة وقائمة بالأدوات المسموح بها ومرجع لبيانات اعتماد يديره المشغّل. خادم MCP البعيد هو خدمة تشغّلها بالفعل أو تثق بها. أما الخادم المدمج فيُعرَّف داخل تطبيقك باستخدام [الأداة المساعدة للواجهة الخلفية بلغة Python](/docs/raw/backend-tools?locale=ar). ويمكن ربط كليهما بملف تعريف وكيل أو بعملية تشغيل مقبولة باستخدام معرّف خادم بسيط. يجب على المشغّل السماح بوجهة نقطة النهاية وتجهيز أي مرجع لبيانات اعتماد الخدمة البعيدة. لا يمكن للجهات المستدعية من المتصفح تسجيل نقاط نهاية أو تقديم مراجع لبيانات اعتماد خاصة. نفّذ ذلك باستخدام مفتاح للواجهة الخلفية يملك نطاق صلاحية التهيئة. ### Python ```python server = await agents.mcp_servers.create( name="Knowledge search", kind="remote", url="https://tools.example/mcp/", allowed_tools=["search_documents"], required=True, secret_ref="knowledge-service", ) ready = await agents.mcp_servers.validate(server.id) print(ready.status, ready.tools) session = await agents.sessions.create(title="Research request") run = await session.send( "Find the published support policy and summarize the escalation steps.", idempotency_key=persisted_request_id, mcp_server_ids=[server.id], ) ``` ### TypeScript ```typescript const server = await agents.mcpServers.create({ name: "Knowledge search", kind: "remote", url: "https://tools.example/mcp/", allowed_tools: ["search_documents"], required: true, secret_ref: "knowledge-service", }) const ready = await agents.mcpServers.validate(server.id) console.log(ready.status, ready.tools) const session = await agents.sessions.create({ title: "Research request" }) const run = await session.send( "Find the published support policy and summarize the escalation steps.", { idempotencyKey: persistedRequestId, mcp_server_ids: [server.id], }, ) ``` `secret_ref` مرجع يجهّزه المشغّل، وليس قيمة سرية ولا اسم متغير بيئة يمكن للمستخدم اختياره بحرية. احذفه عند استخدام خدمة مسموح بها لا تحتاج إلى بيانات اعتماد. تتحقق واجهة API من الوجهات وعمليات إعادة التوجيه والإمكانات المطلوبة. ## إعادة استخدام الأدوات من خلال ملف تعريف ### Python ```python profile = await agents.profiles.create( name="Support researcher", instructions="Use the approved sources. Cite the document identifiers.", mcp_server_ids=[server.id], max_cost_microusd=300_000, timeout_seconds=120, ) session = await agents.sessions.create( title="Support research", profile_id=profile.id, ) ``` ### TypeScript ```typescript const profile = await agents.profiles.create({ name: "Support researcher", instructions: "Use the approved sources. Cite the document identifiers.", mcp_server_ids: [server.id], max_cost_microusd: 300_000, timeout_seconds: 120, }) const session = await agents.sessions.create({ title: "Support research", profile_id: profile.id, }) ``` تحتفظ عملية التشغيل بإصدار الأدوات والفهرس الذي اعتُمد عند قبولها. لا تؤدي إعادة تهيئة الخادم إلى توسيع صلاحيات العمل الجاري بصمت. ويمنع إلغاء صلاحية الخادم استخدامه مستقبلًا؛ أما إلغاء العمل الجاري فيظل إجراءً صريحًا مستقلًا. إذا فشل التحقق، فافحص الحالة المُعادة ورسالة الخطأ الآمنة. لا تعتبر نجاح اتصال TCP دليلًا على أن الخادم يوفّر الأدوات المتوقعة أو تفويضًا صالحًا للاستخدام. --- # إضافة مهارات وتعليمات قابلة لإعادة الاستخدام جهّز حزم التعليمات مرة واحدة واربط إصداراتها غير القابلة للتغيير بملف تعريف وكيل. المهارة حزمة تعليمات تحتوي على ملف `SKILL.md` وموارد داعمة اختيارية، وهي توجّه سلوك الوكيل. مكان عمليات الأعمال هو الأدوات المصرّح بها صراحةً؛ ولا تُفعَّل نصوص المهارات القابلة للتنفيذ في هذا الإصدار. أنشئ مجلدًا مثل `skills/release-review` يحتوي على ملف `SKILL.md` التالي: ```markdown # Release review Review a proposed release in three steps: 1. Identify the user-visible change and its acceptance criteria. 2. List meaningful boundary and failure-path checks. 3. Report observed evidence separately from assumptions. Use only attached, authorized tools. Ask for clarification when the target environment or required permissions are missing. ``` ارفع الحزمة من خادمك الخلفي: ### Python تجهّز `upload_directory` المجلد وموارده. ```python skill = await agents.skills.upload_directory( "skills/release-review", name="Release review", description="A repeatable review checklist for application releases.", ) profile = await agents.profiles.create( name="Release reviewer", instructions="Be concise and cite the observed evidence.", skill_ids=[skill.id], max_cost_microusd=300_000, timeout_seconds=120, ) session = await agents.sessions.create( title="Review release candidate", profile_id=profile.id, ) ``` ### TypeScript يقرأ المثال ملف `SKILL.md` فقط. أدرج كل الموارد المطلوبة في `files` بمسارات نسبية آمنة ومحتوى بترميز base64. ```typescript import { readFile } from "node:fs/promises" const content = await readFile("skills/release-review/SKILL.md") const skill = await agents.skills.create({ name: "Release review", description: "A repeatable review checklist for application releases.", files: [ { path: "SKILL.md", content_base64: content.toString("base64"), }, ], }) const profile = await agents.profiles.create({ name: "Release reviewer", instructions: "Be concise and cite the observed evidence.", skill_ids: [skill.id], max_cost_microusd: 300_000, timeout_seconds: 120, }) const session = await agents.sessions.create({ title: "Review release candidate", profile_id: profile.id, }) ``` تتطلب الحزم مسارات نسبية آمنة وملف `SKILL.md`؛ والحدود الحالية هي 64 ملفًا، و1 MiB لكل ملف، و2 MiB إجمالًا. تُحفَظ الموارد الثنائية كما هي. وتُحفَظ بصمات المهارات المرفوعة وإصدار ملف التعريف الفعلي لكل عملية تشغيل مقبولة، حتى لا تتمكن التعديلات اللاحقة من تغيير سلوكها بصمت. يتحكم المشغّل في النماذج المتاحة. ويمكن لملف التعريف اختيار نموذج مسموح به باستخدام معرّفه المُعلن؛ لكنه لا يستطيع تجاوز مزوّد الخدمة المعيّن للحساب أو حدود الإنفاق. إذا تغيّر التوجيه، فابدأ جلسة جديدة بدلًا من محاولة مواصلة السجل الأصلي في ظل إعدادات مختلفة لمزوّد الخدمة. --- # بناء واجهة React تفاعلية مباشرة استخدم مخزن جلسة مشتركًا واحدًا للرسائل والأدوات والتفاعلات والاستخدام والتعافي. ## التثبيت ```bash npm install "https://wkala.okal.io/downloads/wkala-client-0.1.0.tgz" "https://wkala.okal.io/downloads/wkala-react-0.1.0.tgz" ``` تعمل حزمة React مع React 19، ولا تعتمد على Next.js أو موجّه مسارات أو shadcn أو مكتبة تنسيق. وهي تستخدم مخزن الجلسة نفسه الذي يعتمد عليه عميل TypeScript ويتحقق من صحة البيانات. ويستخدم تطبيق Next المرفق هذا المخزن مع مكوّنات shadcn مشتركة. ## الاتصال من خلال واجهتك الخلفية توفّر واجهتك الخلفية مسارات `/app` المحمية بالمصادقة، وملف تعريف ارتباط للجلسة من نوع HttpOnly، وحماية CSRF، والتحقق من الملكية. تأتي قيمة `csrfToken` أدناه من استجابة الهوية المحمية بالمصادقة في تلك الواجهة الخلفية. وهي ليست مفتاح خدمة Wkala الخاص بك. يستخدم عميل المتصفح `/app` من الأصل نفسه افتراضيًا، وليس عنوان API العام المخصص لعملاء الخادم. يجب أن يشير هدف `createAppProxy` إلى أصل خادمك الخلفي فقط، دون مسار. ```tsx "use client" import { useState } from "react" import { AgentClient, isTerminal } from "@wkala/client" import { AgentProvider, useSession } from "@wkala/react" export function AgentWorkspace({ sessionId, csrfToken }: { sessionId: string csrfToken: string }) { const [client] = useState(() => new AgentClient()) client.csrfToken = csrfToken return ( ) } function Execution({ sessionId }: { sessionId: string }) { const session = useSession(sessionId) const [message, setMessage] = useState("") const [error, setError] = useState(null) const [submitting, setSubmitting] = useState(false) const busy = submitting || session.runs.some(run => !isTerminal(run.status)) async function submit() { setSubmitting(true) setError(null) try { await session.send(message, { idempotencyKey: crypto.randomUUID() }) setMessage("") } catch (cause) { setError(cause instanceof Error ? cause.message : "Unable to start work") } finally { setSubmitting(false) } } return (

{session.connection}

{session.error &&

{session.error.message}

} {session.messages.map(message => (
{message.role} {message.parts.map(part => (

{part.type === "text" ? part.text : "[attached content]"}

))}
))} {session.tools.map(tool => (
{tool.title}: {tool.status}
{JSON.stringify(tool.output, null, 2)}
))} {session.interactions.some(item => item.status === "pending") && (

Input is required. Present the offered interaction to the user.

)}
{ event.preventDefault() void submit() }}>