كيف تبني أول وكيل ذكاء اصطناعي: دليل خطوة بخطوة

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

ما تحتاجه قبل البدء (كلا المسارين)

• مفتاح API من Anthropic — كلا المسارين في هذا الدليل يستخدمان Claude كنموذج. أنشئ حساباً وولّد مفتاحاً من Claude Console على platform.claude.com. الحسابات الجديدة تحصل على رصيد مجاني صغير للبدء؛ لا تذكر وثائق Anthropic الحالية رقماً محدداً بالدولار لهذا، لذا تحقق من لوحة التحكم بعد التسجيل بدلاً من افتراض رقم معين.
• للمسار بلا كود: إما حساب n8n Cloud (تجربة مجانية، بلا بطاقة ائتمان، محدودة بـ1000 عملية تنفيذ) أو استضافة ذاتية لـn8n — انظر التحفظ أدناه قبل افتراض أن الاستضافة الذاتية تغطي كل شيء.
• للمسار البرمجي: Python مثبّت على جهازك، وارتياح لتشغيل سكريبت من الطرفية. لا مكتبات أخرى بخلاف تثبيت حزمة واحدة.
• التكلفة الفعلية المتوقعة: تسعير Claude API يُحتسب بالتوكنات، لا برسم ثابت. كنقطة مرجعية ملموسة من صفحة تسعير Anthropic نفسها، معالجة 10,000 محادثة قصيرة نموذجية على أرخص نموذج حالي (Haiku 4.5) تكلف حوالي 37 دولاراً إجمالاً. بناء واختبار وكيلك الأول — عشرات رسائل الاختبار، لا الآلاف — سيكلف سنتات، لا دولارات.

المسار الأول: بلا كود، باستخدام n8n

لدى n8n الآن ميزة وكلاء مخصصة (منفصلة عن، وأحدث من، نمط "أضف عقدة AI إلى سير عمل" الأقدم الذي ستراه في بعض الدروس القديمة). وقت كتابة هذا، هي في مرحلة معاينة (Preview)، أي أن n8n نفسها تقول إنها قد تتغير.

1. في مشروع n8n الخاص بك، افتح تبويب Agents واضغط Create Agent. أعطه اسماً.
2. في حقل النموذج (Model) الخاص بالوكيل، اختر Anthropic كمزوّد، اختر نموذج Claude، وأضف مفتاح API الخاص بك عند الطلب.
3. اكتب تعليمات للوكيل: دوره، نبرته، و— وهذا أهم مما يتوقع الناس — ما يجب ألا يفعله. الحد الذي تذكره صراحة هو حد لن يتجاوزه الوكيل بالخطأ.
4. اذهب إلى قسم Tools واضغط Add tool. يمكنك ربط تكامل مدمج (Slack، Google Sheets)، أو سير عمل آخر في n8n، أو أداة مخصصة معرّفة بمخطط JSON، أو خادم MCP. ابدأ بأداة واحدة بالضبط. قاوم إغراء إضافة خمس أدوات.
5. اضغط Preview للاختبار في لوحة محادثة دون نشر أي شيء. أرسل رسالة يُفترض أن تُفعّل الأداة وراقب ما يحدث.
6. عندما يتصرف كما تريد، اضغط Publish. النسخة المنشورة فقط هي الحية — تغييرات مسودتك في Preview لا تؤثر على أي شيء يعمل في الإنتاج حتى تنشر مجدداً.

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

المسار الثاني: بالكود، مباشرة عبر Claude API

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

ثبّت الحزمة:

pip install anthropic

اضبط مفتاح API كمتغير بيئة حتى لا يكون مكتوباً مباشرة في كودك (لا تضع مفتاح API مباشرة في سكريبت قد تشاركه أو ترفعه إلى git):

# macOS/Linux
export ANTHROPIC_API_KEY="your-key-here"

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "your-key-here"

إليك وكيلاً كاملاً وقابلاً للتشغيل — مُقتبس من الدرس الرسمي لـAnthropic نفسها. يعرّف أداة واحدة (إنشاء حدث تقويم)، يرسل طلباً، ويكرر حتى يتوقف Claude عن طلب استدعاءات الأدوات:

import json
import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "create_calendar_event",
        "description": "Create a calendar event with attendees and optional recurrence.",
        "input_schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "start": {"type": "string", "format": "date-time"},
                "end": {"type": "string", "format": "date-time"},
                "attendees": {
                    "type": "array",
                    "items": {"type": "string", "format": "email"},
                },
                "recurrence": {
                    "type": "object",
                    "properties": {
                        "frequency": {"enum": ["daily", "weekly", "monthly"]},
                        "count": {"type": "integer", "minimum": 1},
                    },
                },
            },
            "required": ["title", "start", "end"],
        },
    }
]

def run_tool(name, tool_input):
    if name == "create_calendar_event":
        # Replace this with a real calendar API call.
        return {"event_id": "evt_123", "status": "created", "title": tool_input["title"]}
    return {"error": f"Unknown tool: {name}"}

messages = [
    {
        "role": "user",
        "content": "Schedule a weekly team standup every Monday at 9am for the next 4 weeks. Invite alice@example.com, bob@example.com, carol@example.com.",
    }
]

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

while response.stop_reason == "tool_use":
    tool_use = next(block for block in response.content if block.type == "tool_use")
    result = run_tool(tool_use.name, tool_use.input)

    messages.append({"role": "assistant", "content": response.content})
    messages.append({
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": json.dumps(result)}
        ],
    })

    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=tools,
        tool_choice={"type": "auto", "disable_parallel_tool_use": True},
        messages=messages,
    )

final_text = next(block for block in response.content if block.type == "text")
print(final_text.text)

شغّله باستخدام python your_file.py. سيستدعي Claude create_calendar_event مرة لكل من المناسبات الأسبوعية الأربع، ودالة run_tool ستُنشئ كل واحدة ("إنشاء" وهمي في هذا المثال — استبدله بواجهة تقويم حقيقية ليصبح وكيلاً حقيقياً)، وتنتهي الحلقة عندما يصبح لدى Claude ما يكفي لتلخيص ما فعله. لاحظ أن النموذج المستخدم هنا هو claude-sonnet-5 — خيار أرخص وقادر تماماً لوكيل أول؛ استبدله بـclaude-opus-5 إذا احتجت استدلالاً أقوى لأداة أكثر تعقيداً لاحقاً.

أخطاء شائعة يقع فيها المبتدئون

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

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

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

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

النشر قبل اختبار حالة الفشل. في n8n، من السهل اختبار المسار السعيد في Preview والنشر. جرّب الطلب الذي لا يُفترض أن يعمل — حقل مطلوب مفقود، تعليمة غامضة — قبل النشر، لتعرف ماذا يفعل الوكيل عندما تسوء الأمور، لا فقط عندما تسير بشكل صحيح.

ما تبنيه بعد ذلك

بمجرد أن تعمل أداة واحدة، أضف ثانية وانظر كيف يختار Claude بينهما — هنا تبدأ جودة الوصف بالأهمية فعلاً. انظر إلى أدوات Anthropic الخادمية (البحث على الويب، تنفيذ الكود) إذا أردت قدرة جديدة دون كتابة معالج تنفيذ بنفسك. إذا بنيت نسخة n8n، جرّب نشرها إلى قناة فعلية — Slack أو مشغّل مجدول — بدلاً من الاختبار في Preview فقط. وإذا أردت رؤية نفس نمط استخدام الأدوات يتعامل مع مهمة أكثر تعقيداً ومتعددة الخطوات، فذلك هو الشيء التالي الطبيعي لبنائه: ليس مفهوماً جديداً، فقط نفس هذه الحلقة مع رهان أكبر.