بناء وكيل ذكاء اصطناعي ببايثون: Claude Agent SDK خطوة بخطوة

كيف تبني وكيل ذكاء اصطناعي دون أن تكتب الحلقة كلها من الصفر؟ أقصر طريق أعرفه هو Claude Agent SDK، وهي مكتبة لبايثون وTypeScript تمنحنا الأدوات نفسها وحلقة الوكيل نفسها وإدارة السياق نفسها التي يعمل عليها Claude Code. نكتب بضعة عشر سطرًا من الكود، فيقرأ الوكيل الملفات ويصلح الأخطاء وينفّذ الأوامر بنفسه.

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

ما هو وكيل الذكاء الاصطناعي من وجهة نظر المبرمج؟

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

بالنسبة إلى المبرمج، أهم شيء هو الحلقة: يفكر النموذج، ثم يستدعي أداة، ثم ينظر إلى النتيجة ويقرر ما التالي. يتولى Agent SDK هذه الحلقة وتنفيذ الأدوات وإدارة السياق وإعادة المحاولة، ولا يبقى لنا إلا قراءة تدفق الرسائل.

ويميّز التوثيق بين أربع طرق للعمل مع Claude:

1. Agent SDK، مكتبة تشغّل وكيل Claude Code داخل تطبيقنا (في عملية نديرها بأنفسنا)،
2. Claude Code CLI، الطرفية للعمل اليومي التفاعلي (عنه كتبت دليل Claude Code)،
3. Client SDK، وصول مباشر إلى Claude API، حيث نكتب حلقة الأدوات بأنفسنا (أو نتركها لـ“tool runner” التجريبي)،
4. Managed Agents، وكيل تستضيفه Anthropic ويُضبط عبر API.

هذا الدليل يتناول الخيار الأول.

الخطوة 1: كيف تثبّت Claude Agent SDK؟

نحتاج إلى Python 3.10+ (أو Node.js 18.14+ لـ TypeScript) وحساب في Claude Console. أولًا ننشئ مجلد المشروع:

mkdir my-agent
cd my-agent

افتراضيًا، يصل الوكيل إلى الملفات في هذا المجلد ومجلداته الفرعية. ويوصي التوثيق بمدير الحزم uv:

uv init
uv add claude-agent-sdk

ومع pip العادي (macOS وLinux) يبدو الأمر هكذا:

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

اللافت أنك عادةً لا تحتاج إلى تثبيت Claude Code منفصلًا: فكلتا حزمتي SDK تضمّان ملفًا تنفيذيًا أصليًا لـ Claude Code. الاستثناء هو المنصات التي لا تتوفر لها حزمة جاهزة، مثل Windows ARM64 (عندها نثبّت Claude Code يدويًا ويجده SDK في PATH).

الخطوة 2: كيف تضبط مفتاح API؟

ننشئ المفتاح في Claude Console ونضبطه متغير بيئة في الطرفية التي سنشغّل فيها الوكيل:

export ANTHROPIC_API_KEY=your-api-key

لا يحمّل SDK ملفات .env تلقائيًا، فإن احتفظنا بالمفتاح في .env فعلينا تحميله بأنفسنا (مثلًا بحزمة dotenv). وبدلًا من مفتاح Anthropic يمكن استخدام Amazon Bedrock أو Claude Platform on AWS أو Google Cloud أو Microsoft Foundry بضبط المتغير المناسب، مثل CLAUDE_CODE_USE_BEDROCK=1.

تنبيه واحد من التوثيق: دون موافقة مسبقة، لا تسمح Anthropic للمنتجات المبنية على Agent SDK بتقديم تسجيل الدخول بحساب claude.ai ولا باستخدام حدود الاشتراك. يعمل الوكيل بمفتاح API وندفع ثمن التوكنات (وكيف نتتبعها كتبت عنه في تكاليف Claude API).

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

مثال دليل البدء السريع هو وكيل يجد الأخطاء في الكود ويصلحها. أولًا ننشئ ملف utils.py فيه خطآن متعمّدان:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

ستتعطل calculate_average([]) بالقسمة على صفر، وget_user_name(None) بخطأ TypeError. والآن الوكيل نفسه، الملف agent.py:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Agentic loop: streams messages as Claude works
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Auto-approve these tools
            permission_mode="acceptEdits",  # Auto-approve file edits
        ),
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

للكود ثلاثة أجزاء:

1. query تنشئ حلقة الوكيل وتعيد مكرّرًا غير متزامن، فنقرأ الرسائل أولًا بأول عبر async for،
2. prompt هو المهمة. يقرر Claude بنفسه أي الأدوات يستخدم،
3. options هي الإعدادات: هنا توافق allowed_tools مسبقًا على Read وEdit وGlob، ويقبل permission_mode="acceptEdits" تعديلات الملفات تلقائيًا.

نشغّله:

uv run agent.py

(أو python agent.py في بيئة venv مفعّلة). يطبع الوكيل تفكيره وكل أداة يستدعيها، وفي النهاية Done: success. بعد ذلك نجد في utils.py معالجة للقائمة الفارغة ولغياب المستخدم. قرأ الوكيل الملف ووجد الحالات الحدّية وأصلح الكود بنفسه، ولم نكتب نحن دالة واحدة للتعامل مع الأدوات.

إن ظهر الخطأ Not logged in أو Invalid API key، فالأرجح أن المتغير ANTHROPIC_API_KEY غير مضبوط في تلك الطرفية.

الخطوة 4: كيف تحدد ما يفعله الوكيل وحده؟

الأدوات هي التي تحدد ما يستطيعه الوكيل. ويذكر التوثيق ثلاث مجموعات نموذجية:

1. Read وGlob وGrep: تحليل فقط دون تغيير الملفات،
2. Read وEdit وGlob: تحليل وتعديل الكود،
3. Read وEdit وBash وGlob وGrep: أتمتة كاملة مع أوامر الطرفية.

لكي يبحث الوكيل في الويب أو يشغّل الاختبارات مثلًا، يكفي أن نضيف أداة ونغيّر الموجّه:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)

مع تفعيل Bash يقترح دليل البدء السريع المهمة “Write unit tests for utils.py, run them, and fix any failures”. ويمكن أيضًا إعطاء الوكيل دورًا عبر system_prompt، مثل مبرمج بايثون خبير يلتزم بـ PEP 8.

الرافعة الثانية هي وضع الصلاحيات (permission_mode):

1. "default" يمرّر كل استدعاء غير موافَق عليه إلى دالتنا canUseTool، ويرفضه إن لم توجد،
2. "acceptEdits" يقبل تعديلات الملفات والأوامر البسيطة مثل mkdir أو mv في مجلد العمل،
3. "plan" يجعل الوكيل يدرس الكود أولًا ويعدّ خطة،
4. "dontAsk" لا يسأل أبدًا: يعمل فقط ما وافقنا عليه مسبقًا ويُرفض الباقي (مناسب للوكلاء الذين لا يجلس إنسان أمام لوحة مفاتيحهم)،
5. "auto" يمرّر الإجراءات عبر مصنّف يراجع كل إجراء ويحظره أو يسمح به،
6. "bypassPermissions" ينفّذ كل شيء دون سؤال، ووفق التوثيق يصلح فقط للبيئات المعزولة مثل CI أو الحاويات.

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

ومن المفيد أيضًا وضع حدود من البداية: max_turns يحدّ عدد الجولات، وmax_budget_usd يوقف الحلقة عند تجاوز التكلفة التقديرية. من دونهما يعمل الوكيل حتى يقرر بنفسه أنه انتهى، وقد يطول ذلك مع المهام المفتوحة مثل “حسّن هذا المشروع” ;)

الخطوة 5: كيف تضيف للوكيل أداة خاصة؟

الأدوات المدمجة مجرد بداية. نعرّف الأداة الخاصة بالمزخرف @tool (الاسم والوصف ومخطط المدخلات والدالة)، ثم نغلّفها في خادم MCP يعمل في العملية نفسها. مثال التوثيق يجلب درجة الحرارة من Open-Meteo API، لذا نضيف أولًا مكتبة httpx:

uv add httpx

تعريف الأداة:

from typing import Annotated, Any
import httpx
from claude_agent_sdk import tool, create_sdk_mcp_server


# Define a tool: name, description, input schema, handler
@tool(
    "get_temperature",
    "Get the current temperature at a location",
    {
        "latitude": Annotated[float, "Latitude coordinate"],
        "longitude": Annotated[float, "Longitude coordinate"],
    },
)
async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.open-meteo.com/v1/forecast",
            params={
                "latitude": args["latitude"],
                "longitude": args["longitude"],
                "current": "temperature_2m",
                "temperature_unit": "fahrenheit",
            },
        )
        data = response.json()

    # Return a content array - Claude sees this as the tool result
    return {
        "content": [
            {
                "type": "text",
                "text": f"Temperature: {data['current']['temperature_2m']}°F",
            }
        ]
    }


# Wrap the tool in an in-process MCP server
weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_temperature],
)

وفي الملف نفسه نمرّر الخادم إلى الوكيل. الاسم الكامل للأداة بالصيغة mcp__{server}__{tool}، وهو ما نكتبه في allowed_tools لتعمل دون طلب إذن:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"weather": weather_server},
        allowed_tools=["mcp__weather__get_temperature"],
    )

    async for message in query(
        prompt="What's the temperature in San Francisco?",
        options=options,
    ):
        # ResultMessage is the final message after all tool calls complete
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

يستدعي الوكيل أداتنا ويجيب بناءً على النتيجة. ومكان الطقس يمكننا ربط أي شيء: قاعدة بياناتنا أو API داخلية أو سكربت.

الخطوة 6: كيف تربط الوكيل بخادم MCP؟

نربط خوادم MCP الجاهزة (عن البروتوكول نفسه كتبت في ما هو MCP) في الخيار mcp_servers. ومثال التوثيق يربط الوكيل عبر HTTP بخادم توثيق Claude Code البعيد:

options = ClaudeAgentOptions(
    mcp_servers={
        "claude-code-docs": {
            "type": "http",
            "url": "https://code.claude.com/docs/mcp",
        }
    },
    allowed_tools=["mcp__claude-code-docs__*"],
)

النجمة في allowed_tools توافق على جميع أدوات ذلك الخادم. ومع الموجّه “Use the docs MCP server to explain what hooks are in Claude Code” يبحث الوكيل في التوثيق ويعيد الإجابة.

ماذا بعد الوكيل الأول؟

يملك Agent SDK أيضًا بقية ميزات Claude Code:

1. الخطافات (hooks): كود خاص بنا يعمل قبل استدعاء الأداة أو بعده،
2. الوكلاء الفرعيون للمهام الفرعية المستقلة،
3. الجلسات: المعرّف من ResultMessage.session_id يتيح استئناف المحادثة بكامل سياقها أو تفريعها،
4. المهارات والأوامر والذاكرة المحمّلة من المجلد .claude/، تمامًا كما في Claude Code.

توجد تطبيقات نموذجية جاهزة (منها مساعد بريد ووكيل بحثي) في المستودع claude-agent-sdk-demos.

ما الذي يجب الانتباه إليه؟

أولًا، التكاليف. يكبر السياق مع كل جولة، وقد يستهلك ملف كبير أو أمر كثير المخرجات آلاف التوكنات دفعة واحدة. الأجزاء الثابتة (موجّه النظام وتعريفات الأدوات) تُخزَّن مؤقتًا تلقائيًا، لكن يبقى من الأفضل ضبط max_budget_usd من اليوم الأول (قد يُتجاوز السقف بمقدار تكلفة رد واحد، فلنترك هامشًا).

ثانيًا، الصلاحيات. وكيل مع Bash وbypassPermissions على حاسوب محمول عادي هو بحث عن المتاعب، فلنترك الأتمتة الكاملة للحاويات.

ثالثًا، العلامة التجارية. وفق التوثيق، يمكن أن يُسمّى المنتج المبني على SDK مثلًا “Claude Agent” أو “ Powered by Claude”، لكن ليس “Claude Code”، ولا يجوز أن يتظاهر بأنه منتج من Anthropic.

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

كيف تبني وكيل ذكاء اصطناعي دون كتابة الحلقة من الصفر؟

الأسهل هو مكتبة فيها هذه الحلقة جاهزة، مثل Claude Agent SDK. نثبّت claude-agent-sdk، ونضبط ANTHROPIC_API_KEY، ونستدعي query() مع موجّه وقائمة بالأدوات المسموح بها. والباقي، أي استدعاء الأدوات وإدارة السياق، يتولاه SDK.

هل Claude Agent SDK مجاني؟

المكتبة نفسها مجانية، لكن الوكيل يستخدم Claude API، فندفع ثمن التوكنات المستهلكة. ودون موافقة Anthropic لا يمكن ربطه باشتراك claude.ai.

ما الفرق بين Agent SDK وClaude API؟

في Client SDK العادي (Claude API) نكتب حلقة الأدوات بأنفسنا أو نستخدم tool runner التجريبي. أما Agent SDK فيأتي بأدوات Claude Code المدمجة (قراءة الملفات وتعديلها، الأوامر، البحث في الويب)، والصلاحيات، والجلسات، والخطافات.

هل يمكن كتابة الوكيل بـ TypeScript؟

نعم. الحزمة هي @anthropic-ai/claude-agent-sdk، وتتطلب Node.js 18.14+، وفي أمثلة التوثيق تحمل الخيارات الأسماء نفسها كما في بايثون، لكن بصيغة camelCase (allowedTools وpermissionMode).