ساخت ایجنت‌های AI با Claude Agent SDK: یک راهنمای عملی

Claude Agent SDK دسترسی برنامه‌نویسی به همان حلقه ایجنت را در اختیار شما قرار می‌دهد که Claude Code را به کار می‌اندازد. ایجنت‌های شما می‌توانند فایل‌ها را بخوانند، دستورات shell را اجرا کنند، در وب جستجو کنند، کد را ویرایش کنند، از طریق سرورهای MCP با APIهای خارجی ارتباط برقرار کنند، و ایجنت‌های فرعی را هماهنگ کنند - همه از چند خط TypeScript یا Python.

برخلاف Anthropic Client SDK استاندارد که در آن حلقه ابزار خودتان را می‌سازید، Agent SDK اجرای ابزار، مدیریت context، تلاش‌های مجدد، و هماهنگ‌سازی را به صورت داخلی مدیریت می‌کند. شما توصیف می‌کنید که چه می‌خواهید، ابزارها را فراهم می‌کنید، و ایجنت بقیه را حل می‌کند.

معماری

SDK از یک حلقه ساده پیروی می‌کند: context جمع کن، اقدام کن، تایید کن، تکرار کن.

نقطه ورود اصلی query() است، که یک async iterator برمی‌گرداند که در حین کار ایجنت پیام‌ها را stream می‌کند. هر پیام به شما می‌گوید ایجنت چه کار می‌کند: استدلال، فراخوانی ابزار، دریافت نتیجه، یا ارائه خروجی نهایی.

شروع کار

نصب

# 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",
  },
});

برای استفاده در محیط تولید، همیشه ایجنت‌ها را در محیط‌های ایزوله (کانتینرها، VMها) اجرا کنید و محدودکننده‌ترین حالت مجوزی را استفاده کنید که همچنان به ایجنت اجازه انجام کارش را بدهد.

ساخت ابزارهای سفارشی با 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} پیروی می‌کنند. می‌توانید از wildcard در 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 را ترکیب کنید. ایجنت تمام ابزارها از تمام سرورهای متصل را می‌بیند و در صورت نیاز از آنها استفاده می‌کند.

هماهنگ‌سازی چند ایجنتی

برای جریان‌های کاری پیچیده، می‌توانید ایجنت‌های فرعی تخصصی تعریف کنید که ایجنت والد کار را به آنها واگذار می‌کند. هر ایجنت فرعی prompt، ابزارها، و حوزه تمرکز خود را دارد.

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 والد قرار دهید. ایجنت‌های فرعی با ابزارهای خود اجرا می‌شوند و نمی‌توانند به ابزارهای والد دسترسی داشته باشند مگر اینکه صراحتاً اجازه داده شود.

جلسات و تداوم

ایجنت‌ها می‌توانند با استفاده از جلسات، context را در چندین کوئری حفظ کنند. 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. همیشه Sandbox کنید

هرگز ایجنت‌ها را با مجوزهای نامحدود روی ماشین تولید اجرا نکنید. از کانتینرها (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، سرریز پنجره context. همیشه نوع پیام‌ها را بررسی کنید.

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. مصرف توکن را نظارت کنید

حلقه‌های ایجنت می‌توانند توکن‌های قابل توجهی مصرف کنند، به خصوص با codebaseهای بزرگ. SDK شامل فشرده‌سازی خودکار context است، اما همچنان باید مصرف را نظارت کنید.

نتیجه‌گیری

Claude Agent SDK یک LLM را از ماشین پاسخ‌دهی به سوال به چیزی نزدیک‌تر به یک توسعه‌دهنده تازه‌کار تبدیل می‌کند. ایجنت‌های شما می‌توانند بخوانند، بنویسند، اجرا کنند، تایید کنند، و تکرار کنند - همان جریان کاری که یک انسان دنبال می‌کند.

از کوچک شروع کنید: ایجنتی با چند ابزار داخلی بسازید. سپس ابزارهای MCP سفارشی برای دامنه خاص خود اضافه کنید. وقتی جریان‌های کاری شما نیاز به تخصص دارند، به هماهنگ‌سازی چند ایجنتی مقیاس دهید.

حلقه ایجنت همان است که Claude Code را به کار می‌اندازد. اگر آن می‌تواند نرم‌افزار بسازد، ایجنت‌های شما هم می‌توانند.

چک‌لیست شروع:

• SDK را نصب کنید (npm install @anthropic-ai/claude-agent-sdk)
• ANTHROPIC_API_KEY را در محیط خود تنظیم کنید
• یک ایجنت ساده با ابزارهای داخلی (Read, Glob, Grep) بسازید
• یک ابزار سفارشی از طریق سرور MCP درون‌فرآیندی اضافه کنید
• یک سرور MCP خارجی (GitHub, PostgreSQL و غیره) متصل کنید
• هماهنگ‌سازی چند ایجنتی با ایجنت‌های فرعی را پیاده‌سازی کنید
• محیط ایزوله برای تولید راه‌اندازی کنید
• hooks برای ثبت وقایع و حفاظ‌ها اضافه کنید