Claude Code: وكيل SDK

آخر تحديث: 2026-08-31

Agent SDK يحوّل قدرات Claude Code إلى API قابل للبرمجة — ضمّن قدرات البرمجة بالذكاء الاصطناعي في تطبيقاتك، وابنِ سير عمل AI مخصص.

💡 نصيحة: Agent SDK لا يجعل Claude Code خادم API؛ بل يوفّر SDK لاستدعاء قدرات وكيل Claude Code في كودك — قراءة/كتابة الملفات، توليد الكود، تنفيذ الاختبارات، إلخ.

📋 المتطلبات السابقة: الفصل 23 - سير عمل Git و إجراءات جيتهب

1. ما ستتعلمه


2. بنية Agent SDK

(1) SDK مقابل CLI

البُعد CLI SDK
الاستخدام أمر طرفية استدعاء برمجي
التفاعل محادثة بشرية واجهة برمجية
قابلية التخصيص محدودة قابلة للتخصيص بالكامل
التكامل أنابيب/سكربتات تضمين عميق
حالة الاستخدام التطوير اليومي بناء تطبيقات AI

▶ مثال 1: الاستخدام الأساسي لـ SDK

TYPESCRIPT
import { Agent } from "@anthropic-ai/claude-code-sdk";

const agent = new Agent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: "claude-sonnet-4-20250514",
  workingDir: "./my-project",
});

const result = await agent.run("Add user login with JWT authentication");

console.log(result.summary);
console.log(`Files modified: ${result.files.length}`);
console.log(`Tests passed: ${result.testsPassed}`);

3. API الأساسية

(1) إنشاء الوكيل وتهيئته

TYPESCRIPT
const agent = new Agent({
  apiKey: "sk-ant-api03-xxxxx",
  model: "claude-sonnet-4-20250514",
  workingDir: "/path/to/project",
  tools: ["Read", "Write", "Bash"],
  maxTurns: 30,
  style: "concise",
});

(2) تنفيذ المهام

TYPESCRIPT
// تنفيذ أساسي
const result = await agent.run("Fix all TypeScript errors");

// تنفيذ تدفقي
const stream = agent.runStream("Refactor auth module");
for await (const event of stream) {
  console.log(event.type, event.data);
}

// مع سياق
const result = await agent.run("Modify this function", {
  files: ["src/auth/jwt.ts"],
  context: "Use RS256 instead of HS256",
});

(3) معالجة النتائج

TYPESCRIPT
interface AgentResult {
  summary: string;
  files: FileChange[];
  commands: CommandResult[];
  testsPassed: number;
  testsFailed: number;
  tokensUsed: number;
  cost: number;
}

▶ مثال 2: سير عمل مخصص

TYPESCRIPT
async function reviewAndFix(projectDir: string) {
  const agent = new Agent({
    apiKey: process.env.ANTHROPIC_API_KEY!,
    workingDir: projectDir,
    tools: ["Read", "Write", "Bash"],
  });

  // الخطوة 1: مراجعة الكود
  const review = await agent.run(
    "Review project code quality, list all issues to fix"
  );

  // الخطوة 2: إصلاح تلقائي
  if (review.summary.includes("issue")) {
    const fix = await agent.run("Fix all listed quality issues, run tests");
    console.log(`Tests: ${fix.testsPassed} passed, ${fix.testsFailed} failed`);
  }
}

4. وكيل مخصص

(1) أدوات مخصصة

TYPESCRIPT
const databaseQueryTool: Tool = {
  name: "database_query",
  description: "Execute a read-only SQL query",
  parameters: {
    sql: { type: "string", description: "SQL query (SELECT only)" },
  },
  execute: async ({ sql }) => {
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      throw new Error("Only SELECT queries allowed");
    }
    const result = await db.query(sql);
    return { rows: result.rows, count: result.rowCount };
  },
};

const agent = new Agent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  tools: ["Read", "Write", databaseQueryTool],
});

(2) الاستماع للأحداث

TYPESCRIPT
agent.on("file:write", (data) => {
  console.log(`Modified: ${data.filePath}`);
  auditLog.record(data);
});

agent.on("bash:execute", (data) => {
  if (data.command.includes("DROP")) {
    throw new Error("Dangerous command blocked");
  }
});

▶ مثال 3: روبوت مراجعة كود

TYPESCRIPT
class CodeReviewBot {
  private agent: Agent;

  constructor(apiKey: string) {
    this.agent = new Agent({
      apiKey,
      model: "claude-sonnet-4-20250514",
      tools: ["Read", "Bash"],
    });
  }

  async reviewPR(repoDir: string, prDiff: string) {
    this.agent.setWorkingDir(repoDir);
    const result = await this.agent.run(
      `Review PR changes:\n${prDiff}\n\nCheck security, performance, style, test coverage`
    );
    return { review: result.summary, score: this.calculateScore(result.summary) };
  }

  private calculateScore(text: string): number {
    let score = 100;
    if (text.includes("critical")) score -= 30;
    if (text.includes("warning")) score -= 10;
    return Math.max(0, score);
  }
}

5. تعاون SDK و CLI

السيناريو CLI SDK
التطوير اليومي
CI/CD ✅ (headless)
أدوات مخصصة
تكامل تطبيقات الويب
أتمتة دفعية ⚠️ (سكربتات)

❓ أسئلة شائعة

س هل يحتاج SDK تثبيت CLI منفصل؟
ج لا. SDK حزمة npm مستقلة. كلاهما يشتركان في نفس مفتاح API.
س هل API الخاص بـ SDK مستقر؟
ج API الأساسي مستقر، لكن التفاصيل قد تتغير مع الإصدارات. ثبت أرقام الإصدارات، وراقب سجل التغييرات.
س هل يمكن تشغيل SDK في المتصفح؟
ج لا. يحتاج بيئة Node.js؛ يتضمن عمليات نظام الملفات والصدفة.
س نفس تسعيرة CLI؟
ج نعم. كلاهما يستدعي Anthropic API بنفس الفوترة.

📖 ملخص


📝 تمارين

  1. أساسي (⭐): أنشئ وكيلاً باستخدام SDK، ونفّذ مهمة بسيطة، واطبع النتائج.
  2. متوسط (⭐⭐): ابنِ سكربت مراجعة كود آلي بإخراج منظم.
  3. متقدم (⭐⭐⭐): ابنِ روبوت مراجعة كود متكامل مع GitHub Webhook لمراجعة طلبات السحب تلقائياً.
Web-Tutorial.com

فريق Web-Tutorial التقني

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

100%