كيف نحدد نطاق وكيل الذكاء الاصطناعي قبل تقديم سعر ثابت: مواصفات الأسبوع الأول

أي عرض لبناء وكيل (agent) يقول "الذكاء الاصطناعي سيتولى الأمر" مقابل رسوم ثابتة هو عرض لم يتم تحديد نطاقه، بل هو مجرد تخمين. هذا التخمين يظهر لاحقاً على شكل حلقة مفرغة (loop) تستنزف رصيد الـ API في عطلة نهاية الأسبوع وتتوقف بسبب خطأ غير معالج في حدود الطلبات (rate-limit error). ولا أحد يستطيع أن يحدد ما كان مسموحاً للنظام بفعله في المقام الأول.

نحن نقدم تسعيراً ثابتاً لبناء الوكلاء لأننا نقضي الأسبوع الأول في تحويل الطلب إلى مواصفات دقيقة يمكن هندستها. مخرجات هذا الأسبوع هي رقم نهائي يمكنك التوقيع عليه، وليس نطاقاً سعرياً قابلاً للنقاش. ما يلي هو المواصفات بحد ذاتها: المتغيرات الأربعة التي نقيسها، قائمة التسليمات، المستويات، ونمط الكود الذي يضمن ثبات السعر.

لماذا تكسر الوكلاء قواعد تحديد النطاق المعتادة

في تطبيقات الويب العادية، يتناسب الجهد طردياً مع نقاط النهاية (endpoints). تكلفة نقطة النهاية العاشرة تقارب تكلفة الأولى. مساحة الحالة (state space) محدودة، وكل نقطة نهاية تتصرف بنفس الطريقة في كل مرة.

الوكلاء لا يتصرفون بهذه الطريقة. وكيل بأداتين (tools) أكثر تعقيداً بشكل ملحوظ من وكيل بأداة واحدة. النموذج (model) الآن يجب أن يختار بينهما، ويمرر الحالة (state) بينهما، ويتعافى عند فشل أي منهما. أضف أداة ثالثة وسيصبح لديك مشكلة توجيه (routing) بالإضافة إلى مشكلة الاستنتاج (reasoning).

Traditional API: input → validation → business logic → DB write (deterministic)
Agent:           input → planner → tool selection → tool call → reflection → state update → write

كل سهم في السطر الثاني هو مكان يمكن للنظام أن يدخل فيه في حلقة مفرغة، أو ينحرف، أو يخترع معطيات. بدون حدود صارمة، يمكن للمخطط (planner) استدعاء نفسه حتى تنفد نافذة السياق (context window) أو تنفد الميزانية. من هنا تأتي وكلاء "السباغيتي": ترقيعات في الموجّه (prompt) تضاف في بيئة الإنتاج للتعامل مع حالات شاذة (edge cases) لم يحدد نطاقها أحد.

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

المتغيرات الأربعة التي نقيسها قبل تقديم السعر

قبل كتابة أي سعر على الورق، نقوم بتدقيق سير العمل بناءً على أربعة متغيرات. كل منها يرتبط بتكلفة: عدد التوكنز لكل طلب، معدل الفشل تحت الضغط، والساعات التي يجب تخصيصها لضوابط الحماية (guardrails) والتقييم.

1. حجم المخطط (Graph size). نرسم سير العمل كمخطط حالة (state graph). كل حالة عبارة عن عقدة (node): استخراج البيانات، التحقق من حمولة البيانات (payload)، استدعاء API خارجي، أو انتظار تدخل بشري. كل انتقال هو حافة (edge). التدفق الخطي المكون من ثلاث عقد يعتبر رخيصاً. أما المخطط الذي يحتوي على دورات للتصحيح الذاتي والتوجيه الشرطي فليس كذلك. إذا لم يتسع المخطط في صفحة واحدة، فهو نظام متعدد الوكلاء (multi-agent system)، ونسعره على هذا الأساس.

2. صرامة مخطط الأداة (Tool schema strictness). البحث في قاعدة بيانات المتجهات (vector store) يتطلب نصاً (string). لكن كتابة قيد يومية في نظام ERP يتطلب مخططاً صارماً مع تحقق (validation)، ومفاتيح منع التكرار (idempotency keys)، ودعم للتشغيل التجريبي (dry-run). النوع الثاني من الأدوات يحتاج إلى كود أكثر بكثير حوله. النموذج سينتج معطيات مشوهة عاجلاً أم آجلاً، ويجب أن يرفضها التكامل (integration) بشكل نظيف بدلاً من إفساد البيانات في الأنظمة اللاحقة.

3. حجم حمولة الحالة (State payload size). إذا كان الوكيل يمرر فقط معرّف المعاملة (transaction ID) بين الخطوات، فالحالة بسيطة. أما إذا كان يحمل سجلاً طبياً مهيكلاً أو فاتورة متعددة الصفحات عبر عشرات خطوات الاستنتاج (reasoning)، فإن انحراف الحالة (state drift) يصبح نمط الفشل الرئيسي. قد يسقط النموذج حقلاً، أو يعيد تسمية مفتاح، أو يغير نوع البيانات بصمت. هذه التدفقات تحتاج إلى مخططات حالة محددة الأنواع (typed schemas) ومختزلات صريحة (explicit reducers)، وليس مجرد قاموس بيانات فضفاض.

4. سطح التقييم (Evaluation surface). لا يمكنك إطلاق وكيل لا يمكنك تقييمه. قبل تقديم السعر، نقدر عدد الأمثلة الذهبية (golden examples) اللازمة لتغطية المسارات الحرجة: المدخلات التي تكون فيها الإجابة الخاطئة مكلفة. هذا الرقم يحدد تكلفة البناء وحزمة اختبارات الانحدار (regression suite) التي سنسلمها. مجموعة البيانات الذهبية وبوابة CI مشروحة خطوة بخطوة في مقال التقييمات.

ماذا تتضمن تسليمات الأسبوع الأول

المواصفات التي ننتجها في الأسبوع الأول هي الوثيقة التي يتم بناءً عليها تقديم السعر الثابت. إنها قصيرة، ملموسة، ومخصصة لسير عملك. كل قسم موجود لأن تركه غامضاً هو ما يجعل المشاريع تتجاوز الميزانية.

• ▸مخطط الحالة (State graph diagram). كل عقدة، كل حافة، وكل شرط إنهاء. إذا كانت هناك حلقة (cycle)، يُكتب الحد الأقصى لتكرارها بجانبها.
• ▸قائمة الأدوات (Tool inventory). لكل أداة: المخطط الدقيق، ما إذا كانت تقرأ أو تكتب، النظام الذي تتصل به، وما إذا كانت الإخفاقات قابلة لإعادة المحاولة أو نهائية.
• ▸مخطط الحالة (State schema). الهيكل محدد النوع الذي يحمله المخطط بين العقد، مع الحقول التي يمكن لكل عقدة قراءتها وكتابتها.
• ▸قائمة ضوابط الحماية (Guardrail list). حدود صارمة: الحد الأقصى للخطوات لكل تشغيل، الحد الأقصى للتوكنز لكل خطوة، مهلة الاستجابة (timeout) لكل استدعاء خارجي، الحد الأقصى للتكلفة لكل طلب. تُكتب كأرقام، وليس كصفات.
• ▸نقاط التسليم للتدخل البشري (Human-in-the-loop handoff points). الظروف الدقيقة التي يتوقف فيها الوكيل ويطلب تدخلاً بشرياً، والقناة التي يستخدمها. أين توضع نقاط التسليم، وما يحتاج المراجع لرؤيته، هو قرار تصميمي نتخذه معك.
• ▸مجموعة التقييم (Evaluation set). الأمثلة الذهبية التي يجب أن يجتازها الوكيل قبل الإطلاق، والمقاييس التي نقيّم بناءً عليها.
• ▸هدف النشر (Deployment target). أين يعمل، كيف تتم مراقبته، ومن المسؤول عن التنبيهات.

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

المستويات التي نسعرها

نحن نصنف العمل الوارد إلى ثلاثة مستويات بناءً على المتغيرات الثلاثة الأولى. تقع جميعها ضمن النطاق المنشور الذي يتراوح بين 8,000 و 45,000 دولار لوكلاء أتمتة سير العمل. ما يحدد سعر البناء داخل هذا النطاق هو موضوع لمقال منفصل.

تزداد ساعات ضوابط الحماية والتقييم مع كل مستوى. نذكرها في المواصفات كافتراضات تخطيطية، وليس كوعود، وهي الجزء الذي غالباً ما يكون مفقوداً في التقديرات الأخرى. لنفترض أنك تلقيت عرض سعر لوكيل يكتب في عشرة أنظمة إنتاج، بدون خطوة مراجعة بشرية وبسعر منخفض جداً. أنت تشتري عرضاً تجريبياً (demo). المواصفات أعلاه هي كيف يمكنك التمييز.

ضوابط الحماية الهيكلية التي تضمن ثبات السعر

الكود أدناه هو النمط الذي يتيح لنا الالتزام برقم ثابت. يستخدم LangGraph لآلة الحالة (state machine) و Pydantic للتحقق من معطيات الأدوات. وجود حد صارم للتكرار (recursion limit) يعني أن المخطط المرتبك لا يمكنه إفلاسك بطلب واحد في كل مرة.

import os
from typing import Annotated, Dict, Any, List, Literal
from typing_extensions import TypedDict
from pydantic import BaseModel, Field
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from litellm import completion

class State(TypedDict):
    messages: Annotated[List[Dict[str, Any]], add_messages]
    user_id: int
    tax_rate: float
    execution_errors: List[str]

class TaxCalculationSchema(BaseModel):
    user_id: int
    country_code: str = Field(..., description="ISO 3166-1 alpha-2 code, e.g. 'AE'")

def calculate_tax(payload: TaxCalculationSchema) -> Dict[str, Any]:
    if payload.country_code == "AE":
        return {"tax_rate": 0.05, "status": "success"}
    return {"tax_rate": 0.15, "status": "success"}

def call_model(state: State) -> Dict[str, Any]:
    # LiteLLM lets us swap model families without touching the graph.
    response = completion(
        model=os.environ["AGENT_MODEL"],
        messages=state["messages"],
        tools=[{
            "type": "function",
            "function": {
                "name": "calculate_tax",
                "description": "Calculate tax rate based on user location.",
                "parameters": TaxCalculationSchema.model_json_schema(),
            },
        }],
        tool_choice="auto",
    )
    return {"messages": [response.choices[0].message]}

def execute_tools(state: State) -> Dict[str, Any]:
    last = state["messages"][-1]
    results, errors = [], []
    for call in last.get("tool_calls", []):
        if call["function"]["name"] != "calculate_tax":
            continue
        try:
            args = TaxCalculationSchema.model_validate_json(call["function"]["arguments"])
            result = calculate_tax(args)
            results.append({
                "role": "tool", "tool_call_id": call["id"],
                "name": "calculate_tax", "content": str(result),
            })
        except Exception as e:
            errors.append(str(e))
            results.append({
                "role": "tool", "tool_call_id": call["id"],
                "name": "calculate_tax", "content": f"Error: {e}",
            })
    return {"messages": results, "execution_errors": errors}

def route(state: State) -> Literal["tools", "__end__"]:
    return "tools" if state["messages"][-1].get("tool_calls") else "__end__"

workflow = StateGraph(State)
workflow.add_node("agent", call_model)
workflow.add_node("tools", execute_tools)
workflow.add_edge(START, "agent")
workflow.add_conditional_edges("agent", route)
workflow.add_edge("tools", "agent")

app = workflow.compile()

# recursion_limit is the hard financial boundary per request.
config = {"recursion_limit": 10}

هذا النمط يقوم بثلاثة أشياء. حد التكرار يضع سقفاً للخطوات لكل طلب؛ وبمجرد أن يتجاوزه التشغيل، يطلق LangGraph خطأ GraphRecursionError، كما تصف مستندات graph API. التحقق عبر Pydantic في كل استدعاء لأداة يعني أن المعطيات المشوهة تفشل بسرعة بدلاً من إفساد نظام لاحق. والتوجيه (routing) صريح: لا يمكن للوكيل الانتقال إلا إلى الحالات التي رسمناها في الأسبوع الأول.

لا شيء من هذا يعتبر جديداً. ولكن يتم تخطيه بالكامل في العروض التجريبية التي تنهار في بيئة الإنتاج.

لماذا نصمم للتسليم البشري، وليس للاستقلالية الكاملة

جعل الوكيل يتعامل مع المسار الشائع لسير عمل محدد النطاق بمفرده هي مشكلة محلولة. السعي وراء الاستقلالية الكاملة هو ما يفجر الميزانيات. الجزء الأخير المتبقي يتمثل في المدخلات العدائية، والحالات الشاذة في اللهجات، والمستندات المرفوعة التي تحتوي على حقن موجّهات (prompt injections)، والذيل الطويل (long tail) من الحالات التي لا يمكن لأحد حصرها مسبقاً.

لذلك نحن لا نسعر على أساس الاستقلالية الكاملة. كل نظام نبنيه يحتوي على مخرج صريح (off-ramp). يتوقف التنفيذ وتنتقل المهمة إلى شخص في ثلاث حالات: انخفاض ثقة النموذج عن حد تم إعداده، وصول الحالة إلى انتقال لم نرسمه، أو فشل أداة أكثر من مرة. عملية التسليم تحمل حمولة الحالة كاملة، بحيث يرى الإنسان بالضبط ما رآه الوكيل.

مقال أنماط إنتاج LangGraph يغطي الآليات. النقطة التجارية بسيطة. يمكننا الالتزام بسعر ثابت لأننا لا نعد بحل كل حالة شاذة. نحن نعد بنظام يتعامل مع المسار الشائع بشكل ممتاز، ويحدد المسار غير الشائع بوضوح، ولا يقوم بالتخمين الصامت أبداً.

الأسئلة الشائعة

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

ماذا يحدث عندما يغير مزود النموذج شيئاً ويتعطل الوكيل؟ كل استدعاء للنموذج يمر عبر LiteLLM. التبديل بين Claude أو GPT أو Mistral أو نموذج Qwen أو Llama مستضاف محلياً يصبح مجرد تغيير في الإعدادات. حزمة اختبارات الانحدار من الأسبوع الأول تخبرنا ما إذا كان النموذج الجديد ينجح قبل إطلاقه. إذا لم ينجح، نبقى على النموذج القديم.

كيف تمنع الوكيل من القيام بشيء ضار؟ يتم فصل طبقة الاستنتاج (reasoning) عن طبقة التنفيذ. الوكيل لا يحتفظ أبداً ببيانات اعتماد قاعدة البيانات الخام أو وصول API مفتوح. إنه ينتج حمولات JSON تذهب إلى بوابة (gateway)، وتقوم البوابة بفرض المخطط وقواعد العمل. استرداد مبلغ يتجاوز حداً معيناً يحتاج إلى موافقة؛ والكتابة في الجداول المحمية يتم حظرها. يمكن للوكيل أن يخطئ؛ لكن البوابة تجعل "الخطأ" رخيصاً.

هذا الأسبوع، خذ سير عمل واحد تريد أتمتته وارسم مخطط الحالة الخاص به في صفحة واحدة. حدد كل عقدة، وكل أداة يستدعيها، وكل حلقة. ثم قم بعدها لترى في أي مستوى يقع المخطط. إذا لم يتسع في الصفحة، فقد تعلمت الحقيقة الأكثر تكلفة حول المشروع قبل أن يسعره أي شخص.