Claude Code: وكيل SDK
آخر تحديث: 2026-08-31
Agent SDK يحوّل قدرات Claude Code إلى API قابل للبرمجة — ضمّن قدرات البرمجة بالذكاء الاصطناعي في تطبيقاتك، وابنِ سير عمل AI مخصص.
💡 نصيحة: Agent SDK لا يجعل Claude Code خادم API؛ بل يوفّر SDK لاستدعاء قدرات وكيل Claude Code في كودك — قراءة/كتابة الملفات، توليد الكود، تنفيذ الاختبارات، إلخ.
📋 المتطلبات السابقة: الفصل 23 - سير عمل Git و إجراءات جيتهب
1. ما ستتعلمه
- تموضع Agent SDK وبنيته
- تثبيت SDK واستخدامه الأساسي
- نظرة عامة على API الأساسية
- بناء وكيل مخصص
- الفرق بين SDK و CLI
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 بنفس الفوترة.
📖 ملخص
- Agent SDK يوفّر واجهة برمجية لقدرات Claude Code في الكود
- API الأساسية: إنشاء وكيل، تنفيذ مهام، معالجة نتائج، الاستماع للأحداث
- أدوات مخصصة، خطافات أحداث، بناء سير عمل كامل
- CLI للتطوير اليومي، وSDK للتطبيقات المخصصة والتكامل العميق
- كلاهما يشتركان في مفتاح API والفوترة
📝 تمارين
- أساسي (⭐): أنشئ وكيلاً باستخدام SDK، ونفّذ مهمة بسيطة، واطبع النتائج.
- متوسط (⭐⭐): ابنِ سكربت مراجعة كود آلي بإخراج منظم.
- متقدم (⭐⭐⭐): ابنِ روبوت مراجعة كود متكامل مع GitHub Webhook لمراجعة طلبات السحب تلقائياً.