الأدوات والسلوك
عرّف الأدوات داخل خادمك الخلفي
امنح الوكلاء وصولًا إلى دوال Python المصرّح بها دون نقل منطق العمل خارج تطبيقك.
ثبّت المكوّن المساعد للخادم الخلفي
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 افتراضيًا.
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، ثم تحقّق من صلاحية الواصف من مهمة تهيئة أولية. لا تتحقّق من نقطة نهاية مطلوبة قبل أن يبدأ الخادم الاستماع للطلبات.
# 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 من الوصول إلى دوالك. ولا يتضمّن هذا الإصدار نفقًا لاتصال صادر من عامل تنفيذ.