بناء وكلاء AI باستخدام Claude Agent SDK: دليل عملي

يمنحك Claude Agent SDK وصولاً برمجياً إلى نفس حلقة الوكيل التي تشغل Claude Code. يمكن لوكلائك قراءة الملفات، وتنفيذ أوامر shell، والبحث في الويب، وتحرير الكود، واستدعاء واجهات API خارجية من خلال خوادم MCP، وتنسيق الوكلاء الفرعيين - كل ذلك من بضعة أسطر من TypeScript أو Python.

على عكس Anthropic Client SDK المعياري حيث تبني حلقة الأدوات الخاصة بك، يتولى Agent SDK تنفيذ الأدوات وإدارة السياق وإعادة المحاولات والتنسيق داخلياً. أنت تصف ما تريد، وتوفر الأدوات، والوكيل يكتشف الباقي.

البنية المعمارية

يتبع SDK حلقة بسيطة: اجمع السياق، اتخذ إجراءً، تحقق، كرر.

نقطة الدخول الرئيسية هي query()، التي تعيد async iterator يبث الرسائل أثناء عمل الوكيل. كل رسالة تخبرك بما يفعله الوكيل: التفكير، أو استدعاء أداة، أو استلام نتيجة، أو تقديم المخرج النهائي.

البدء

التثبيت

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

تحتاج إلى تعيين مفتاح Anthropic API كـ ANTHROPIC_API_KEY في بيئتك.

وكيلك الأول

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

هذا كل شيء. سيستخدم الوكيل Glob للعثور على الملفات، وGrep للبحث عن أنماط TODO، وRead لفحص التطابقات، ويعيد ملخصاً منظماً. لا تحتاج لكتابة منطق التنسيق - SDK يتولى ذلك.

المعادل في Python

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

الأدوات المدمجة

يأتي SDK مع نفس الأدوات المتوفرة في Claude Code:

تتحكم في الأدوات التي يمكن للوكيل استخدامها من خلال allowedTools. إذا لم تكن أداة في القائمة، فلا يمكن للوكيل استدعاؤها.

أوضاع الصلاحيات

بما أن الوكلاء ينفذون أوامر حقيقية على أنظمة حقيقية، فالصلاحيات مهمة.

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

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

بناء أدوات مخصصة مع MCP

القوة الحقيقية لـ SDK تأتي من توسيع الوكلاء بأدواتك الخاصة. تُعرَّف الأدوات المخصصة كخوادم MCP داخل العملية - بدون إدارة عمليات فرعية، وبدون حمل إضافي على الشبكة.

مثال: أداة الطقس

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

تتبع الأدوات المخصصة اتفاقية التسمية mcp__{server_name}__{tool_name}. يمكنك استخدام أحرف البدل في allowedTools: "mcp__weather__*" تسمح بجميع أدوات خادم الطقس.

مثال: أداة استعلام قاعدة البيانات

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

الاتصال بخوادم MCP خارجية

بالإضافة إلى الأدوات داخل العملية، يمكنك الاتصال بأي خادم MCP موجود - نفس الخوادم التي تعمل مع Claude Desktop وCursor وعملاء MCP الآخرين.

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

يمكنك دمج خوادم MCP متعددة. يرى الوكيل جميع الأدوات من جميع الخوادم المتصلة ويستخدمها حسب الحاجة.

تنسيق متعدد الوكلاء

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

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

أضف "Agent" إلى allowedTools الخاص بالوكيل الأصلي لتمكين التفويض. تعمل الوكلاء الفرعيون بأدواتهم الخاصة ولا يمكنهم الوصول إلى أدوات الأصل إلا إذا مُنحت لهم صراحة.

الجلسات والاستمرارية

يمكن للوكلاء الحفاظ على السياق عبر استعلامات متعددة باستخدام الجلسات. التقط session_id من التفاعل الأول ومرره في resume للاستعلامات اللاحقة.

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

إذا كنت لا تريد استضافة بنية الوكيل التحتية بنفسك، فإن Claude Managed Agents (أُطلق في أبريل 2026) يوفر خدمة سحابية مدارة بالكامل. تشغل Anthropic الحاويات، وتتولى التوسع، وتوفر واجهة API للبث.

الفرق الرئيسي: مع Agent SDK، تشغل حلقة الوكيل في بنيتك التحتية الخاصة. مع Managed Agents، تستضيف Anthropic الوكيل وتشغله لك. تتفاعل عبر واجهة API قائمة على الجلسات وتتلقى الأحداث عبر Server-Sent Events.

التسعير:

• Agent SDK: أسعار رموز Claude API المعيارية فقط. أنت تتولى الاستضافة.
• Managed Agents: أسعار الرموز بالإضافة إلى $0.08 لكل ساعة جلسة (الفوترة بالمللي ثانية).

أفضل الممارسات للإنتاج

1. استخدم العزل دائماً

لا تشغل أبداً وكلاء بصلاحيات غير مقيدة على جهاز إنتاج. استخدم الحاويات (Docker, Fly.io, Modal) أو البيئات المعزولة (E2B, Vercel Sandbox).

2. حدد الوصول إلى الأدوات

اتبع مبدأ أقل الامتيازات. الوكيل الذي يولد تقارير لا يحتاج إلى Bash أو Write.

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. استخدم Hooks للحواجز الأمنية

تتيح لك Hooks اعتراض استدعاءات الأدوات قبل وبعد التنفيذ. استخدمها للتسجيل والتحقق وتحديد المعدل.

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. تعامل مع الأخطاء بأناقة

يمكن لحلقة الوكيل إنتاج أخطاء - فشل الأدوات، حدود معدل API، تجاوز نافذة السياق. تحقق دائماً من أنواع الرسائل.

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. راقب استهلاك الرموز

يمكن لحلقات الوكيل استهلاك رموز كبيرة، خاصة مع قواعد الكود الكبيرة. يتضمن SDK ضغط سياق تلقائي، لكن يجب عليك مراقبة الاستهلاك.

الخلاصة

يحول Claude Agent SDK نموذج اللغة الكبير من آلة للإجابة على الأسئلة إلى شيء أقرب إلى مطور مبتدئ. يمكن لوكلائك القراءة والكتابة والتنفيذ والتحقق والتكرار - نفس سير العمل الذي يتبعه الإنسان.

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

حلقة الوكيل هي نفسها التي تشغل Claude Code. إذا كان يمكنه بناء البرمجيات، فيمكن لوكلائك ذلك أيضاً.

قائمة مراجعة البدء:

• ثبت SDK (npm install @anthropic-ai/claude-agent-sdk)
• عيّن ANTHROPIC_API_KEY في بيئتك
• ابنِ وكيلاً بسيطاً بالأدوات المدمجة (Read, Glob, Grep)
• أضف أداة مخصصة عبر خادم MCP داخل العملية
• اتصل بخادم MCP خارجي (GitHub, PostgreSQL, إلخ.)
• نفّذ تنسيق متعدد الوكلاء مع وكلاء فرعيين
• أعد بيئة معزولة للإنتاج
• أضف hooks للتسجيل والحواجز الأمنية