وصفات عملية

اختر الوصفة حسب السلوك المطلوب

توضح هذه الأمثلة إعدادات لسلوك محدد. ابدأ بملف Config يعمل ويحتوي version: "2"، مثل أول Tool، ثم أضف القسم المناسب. المقطع الذي يبدأ بـ - id: عنصر في قائمة tools، أما request: أو behavior: فهما قسم داخل Tool موجودة.

قبل نسخ المقطع، عرّف كل Input path يقرأه، وكل Dependency يسميها، وكل Tool ينتقل إليها. استخدم مثال الحجز إذا أردت ملفًا كاملًا يعمل دون تجميع.

افهم النتيجة قبل نسخ النمط

لا يحمل GET العام بيانات اعتماد مستخدم، ويجب أن يعرض بيانات عامة فقط. يمرّر GET بمصادقة session قيمة Token ويعتمد صلاحيات API. ويمثل service key الخادم؛ استخدمه عندما تتوافق سلطة الخادم مع صلاحيات REST Endpoint.

عند إضافة Confirmation، يعيد AGENTO الحالة needs_confirmation وينتظر الموافقة قبل تنفيذ الكتابة. ويغيّر إخفاء option ID ما يراه العميل، وليس قيمة API الداخلية المستخدمة في Mapping. وتغيّر إضافة مخزن أو limiter مخصص مكان حفظ الحالة، مع ضرورة الالتزام بقواعد الـ Runtime للتخزين والتزامن.

تحقّق من الوصفة بعد تركيبها

تحقق من الإعداد بعد الدمج، ثم استدعِ Tool القراءة على بيئة اختبار من API لديك وقارن الطلب المتوقع. استخدم Responses محفوظة أو Mock لاختبار الأخطاء وتكرار الكتابة دون إحداث تغييرات حقيقية. اختبر القيمة الغائبة ومسار الرفض أيضًا. لا تنسخ معاينة تقرأ $.service_name دون تعريف الحقل وتعبئته، ولا تضف Recovery لـ availability دون تعريفها كـ Dependency في الـ Tool نفسها.

تفترض مقاطع التطبيق أدناه وجود قيم Session ورسالة والـ Token مصرح بها، ودوال عرض من تطبيقك. هي أمثلة ربط، ويظل التعامل مع الحالات في مسار التشغيل مطلوبًا.

كل مقطع أدناه يعالج قرارًا محددًا. لا يمثل ملف إعداد كاملًا إلا إذا احتوى جذر version وقائمة tools وما تشير إليه من Tools. راجع المتطلبات الموضحة أعلاه قبل الدمج.

GET عامة للقراءة فقط

- id: list-categories
  tool:
    description: List public categories.
    input_schema:
      type: object
      properties: {}
  request:
    method: GET
    url: https://api.example.com/categories

GET بمصادقة المستخدم

- id: my-bookings
  tool:
    description: List the signed-in user's bookings.
    input_schema:
      type: object
      properties: {}
  request:
    method: GET
    url: https://api.example.com/bookings
    auth:
      type: session

في التطبيق المضيف:

runtime.chat({
  sessionId,
  message: "Show my bookings",
  auth: { token: accessToken },
});

API key لخدمة

request:
  auth:
    type: api-key
    env: PARTNER_API_KEY
    header: X-API-Key

POST مع Confirmation

behavior:
  effect: side-effect
  confirmation:
    required: true
    preview:
      service: $.service_name
      date: $.date
request:
  method: POST
  url: https://api.example.com/bookings

إجراء مدمّر للبيانات

behavior:
  effect: destructive
  confirmation:
    required: true

استخدم معاينة واضحة وواجهة في التطبيق المضيف تميّز بصريًا أثر الإجراء المدمّر.

استدعاء مباشر دون AI Model

const runtime = await AgentRuntime.create({
  configPath: "./config.yml",
  presentation: "raw",
});

await runtime.invoke({
  sessionId,
  tool: "list-categories",
  arguments: {},
});

محادثة بالـ AI Model مع واجهة تعتمد على البيانات الخام

const result = await runtime.chat({
  sessionId,
  message,
  presentation: "both",
});

renderNaturalLanguage(result.message);
renderStructuredCards(result.data);

سياق tenant موثوق

await runtime.chat({
  sessionId,
  message,
  context: {
    tenant: { id: tenantId },
  },
});

request:
  map:
    headers:
      X-Tenant-Id:
        source: session
        path: $.tenant.id

إلغاء طلب

const controller = new AbortController();

const promise = runtime.chat({
  sessionId,
  message,
  signal: controller.signal,
});

controller.abort();

إخفاء الـ ID الأصلي للخيار

selection:
  items_path: $.accounts
  id_path: $.internal_id
  label_path: $.display_name
  id_sensitive: true

التعافي عند تغيّر التوافر

behavior:
  effect: side-effect
  confirmation:
    required: true
  recovery:
    refresh_dependency: availability
    statuses: [409, 410]

استخدمه عندما يمكن أن تصبح بيانات الكتابة المؤكدة قديمة بين Selection والتنفيذ. يحدّث Runtime الـ Dependency المخصصة للقراءة فقط، ويسأل المستخدم مجددًا، بدل إعادة الكتابة بصمت.

محدّد معدل مخصص

const runtime = await AgentRuntime.create({
  configPath: "./config.yml",
  rateLimiter: sharedLimiter,
});

نفّذ الواجهة:

interface RateLimiter {
  consume(key: string, limit: number, windowMs: number): Promise<void>;
}

Retriever مخصص لآلاف الـ Tools

const runtime = await AgentRuntime.create({
  configPath: "./config.yml",
  retriever: myVectorOrDomainRetriever,
});

أعد IDs لـ Tools موجودة ودرجات مطابقتها فقط؛ يستمر ToolRouter في التحقق من المرشحين واستدعاءات الـ Tools النهائية.