مرورِ کلیِ Agent SDK

ساخت ایجنت‌های هوش‌مصنوعیِ آماده‌ی محصول، با Claude Code به‌عنوان یک کتابخانه

ایجنت‌های هوش‌مصنوعی بساز که خودمختار فایل‌ها را می‌خوانند، دستورها را اجرا می‌کنند، در وب جست‌وجو می‌کنند، کد را ویرایش می‌کنند و خیلی کارهای دیگر. Agent SDK همان ابزارها، حلقه‌ی ایجنت و مدیریت کانتکستی را که Claude Code را پیش می‌برند در اختیارت می‌گذارد، قابل‌برنامه‌نویسی در Python و TypeScript.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)  # Claude reads the file, finds the bug, edits it


asyncio.run(main())

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

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message); // Claude reads the file, finds the bug, edits it
}

Agent SDK ابزارهای داخلیِ آماده‌ای برای خواندن فایل‌ها، اجرای دستورها و ویرایش کد دارد، پس ایجنت تو می‌تواند بی‌درنگ کار را شروع کند، بی‌آنکه مجبور باشی اجرای ابزار را خودت پیاده‌سازی کنی. سری به شروعِ سریع بزن یا ایجنت‌های واقعیِ ساخته‌شده با SDK را کاوش کن:

شروعِ سریع

یک ایجنتِ رفع‌باگ را در چند دقیقه بساز

ایجنت‌های نمونه

دستیار ایمیل، ایجنت پژوهش و بیشتر

شروع کن

نصب SDK

TypeScript
Python

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

pip install claude-agent-sdk

پکیج Python به Python 3.10 یا بالاتر نیاز دارد. اگر pip گزارش داد No matching distribution found for claude-agent-sdk، یعنی مفسرت قدیمی‌تر از 3.10 است. روی macOS یا Linux دستور python3 --version و روی Windows دستور py --version را برای بررسی اجرا کن.

کلید API را تنظیم کن

یک کلید API از Console بگیر، سپس آن را به‌عنوان یک متغیر محیطی تنظیم کن:

export ANTHROPIC_API_KEY=your-api-key

SDK احراز هویت از طریق ارائه‌دهنده‌های API شخصِ ثالث را هم پشتیبانی می‌کند:

Amazon Bedrock: متغیر محیطی CLAUDE_CODE_USE_BEDROCK=1 را تنظیم کن و اعتبارنامه‌های AWS را پیکربندی کن
Claude Platform on AWS: CLAUDE_CODE_USE_ANTHROPIC_AWS=1 و ANTHROPIC_AWS_WORKSPACE_ID را تنظیم کن، سپس اعتبارنامه‌های AWS را پیکربندی کن
Google Vertex AI: متغیر محیطی CLAUDE_CODE_USE_VERTEX=1 را تنظیم کن و اعتبارنامه‌های Google Cloud را پیکربندی کن
Microsoft Azure: متغیر محیطی CLAUDE_CODE_USE_FOUNDRY=1 را تنظیم کن و اعتبارنامه‌های Azure را پیکربندی کن

برای جزئیات، راهنماهای راه‌اندازیِ Bedrock، Claude Platform on AWS، Vertex AI یا Azure AI Foundry را ببین.

اولین ایجنتت را اجرا کن

این مثال یک ایجنت می‌سازد که با استفاده از ابزارهای داخلی، فایل‌های دایرکتوریِ جاری‌ات را فهرست می‌کند.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

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

for await (const message of query({
  prompt: "What files are in this directory?",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

آماده‌ی ساختنی؟ برای ساخت ایجنتی که در چند دقیقه باگ‌ها را پیدا و رفع می‌کند، شروعِ سریع را دنبال کن.

قابلیت‌ها

هر چیزی که Claude Code را قدرتمند می‌کند، در SDK هم در دسترس است:

ایجنت تو می‌تواند بدون هیچ تنظیم اضافی فایل‌ها را بخواند، دستورها را اجرا کند و کدبیس‌ها را جست‌وجو کند. ابزارهای کلیدی شامل این‌هاست:

ابزار	چه می‌کند
Read	خواندن هر فایلی در دایرکتوریِ کاری
Write	ساخت فایل‌های جدید
Edit	اعمال ویرایش‌های دقیق روی فایل‌های موجود
Bash	اجرای دستورهای ترمینال، اسکریپت‌ها، عملیات git
Monitor	تماشای یک اسکریپتِ پس‌زمینه و واکنش به هر خط خروجی به‌عنوان یک رویداد
Glob	یافتن فایل‌ها بر اساس الگو (`*/.ts`, `src/*/.py`)
Grep	جست‌وجوی محتوای فایل با regex
WebSearch	جست‌وجوی وب برای اطلاعاتِ روز
WebFetch	واکشی و تجزیه‌ی محتوای صفحه‌ی وب
AskUserQuestion	پرسیدن سؤال‌های شفاف‌کننده از کاربر با گزینه‌های چندگزینه‌ای

این مثال یک ایجنت می‌سازد که کدبیست را برای کامنت‌های TODO جست‌وجو می‌کند:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Find all TODO comments and create a summary",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

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

for await (const message of query({
  prompt: "Find all TODO comments and create a summary",
  options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if ("result" in message) console.log(message.result);
}

کد سفارشی‌ات را در نقاط کلیدیِ چرخه‌ی عمر ایجنت اجرا کن. Hookهای SDK از توابع callback برای اعتبارسنجی، ثبت لاگ، مسدودسازی یا تبدیل رفتار ایجنت استفاده می‌کنند.

Hookهای در دسترس: PreToolUse، PostToolUse، Stop، SessionStart، SessionEnd، UserPromptSubmit و بیشتر.

این مثال همه‌ی تغییرات فایل‌ها را در یک فایل ممیزی ثبت می‌کند:

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher


async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}


async def main():
    async for message in query(
        prompt="Refactor utils.py to improve readability",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const logFileChange: HookCallback = async (input) => {
  const filePath = (input as any).tool_input?.file_path ?? "unknown";
  await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
  return {};
};

for await (const message of query({
  prompt: "Refactor utils.py to improve readability",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

درباره‌ی hookها بیشتر بدان ←

ایجنت‌های تخصصی به وجود بیاور تا زیرتسک‌های متمرکز را انجام دهند. ایجنت اصلی‌ات کار را واگذار می‌کند و ساب‌ایجنت‌ها نتیجه را گزارش می‌دهند.

ایجنت‌های سفارشی با دستورالعمل‌های تخصصی تعریف کن. ساب‌ایجنت‌ها از طریق ابزار Agent فراخوانی می‌شوند، پس Agent را در allowedTools بگنجان تا آن فراخوانی‌ها خودکار تأیید شوند:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    async for message in query(
        prompt="Use the code-reviewer agent to review this codebase",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer for quality and security reviews.",
                    prompt="Analyze code quality and suggest improvements.",
                    tools=["Read", "Glob", "Grep"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

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

for await (const message of query({
  prompt: "Use the code-reviewer agent to review this codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Agent"],
    agents: {
      "code-reviewer": {
        description: "Expert code reviewer for quality and security reviews.",
        prompt: "Analyze code quality and suggest improvements.",
        tools: ["Read", "Glob", "Grep"]
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

پیام‌هایی که از درون کانتکستِ یک ساب‌ایجنت می‌آیند، فیلد parent_tool_use_id دارند که به تو امکان می‌دهد ردیابی کنی هر پیام به کدام اجرای ساب‌ایجنت تعلق دارد.

درباره‌ی ساب‌ایجنت‌ها بیشتر بدان ←

از طریق Model Context Protocol به سیستم‌های بیرونی متصل شو: پایگاه‌های داده، مرورگرها، APIها و صدها مورد دیگر.

این مثال سرور Playwright MCP را وصل می‌کند تا به ایجنت تو قابلیت‌های خودکارسازی مرورگر بدهد:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Open example.com and describe what you see",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

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

for await (const message of query({
  prompt: "Open example.com and describe what you see",
  options: {
    mcpServers: {
      playwright: { command: "npx", args: ["@playwright/mcp@latest"] }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

درباره‌ی MCP بیشتر بدان ←

دقیقاً کنترل کن ایجنتت کدام ابزارها را می‌تواند استفاده کند. عملیاتِ بی‌خطر را مجاز کن، خطرناک‌ها را مسدود کن، یا برای کارهای حساس تأیید بخواه.

این مثال یک ایجنتِ فقط‌خواندنی می‌سازد که می‌تواند کد را تحلیل کند اما تغییرش ندهد. allowed_tools ابزارهای Read، Glob و Grep را از پیش تأیید می‌کند.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Review this code for best practices",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

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

for await (const message of query({
  prompt: "Review this code for best practices",
  options: {
    allowedTools: ["Read", "Glob", "Grep"]
  }
})) {
  if ("result" in message) console.log(message.result);
}

درباره‌ی دسترسی‌ها بیشتر بدان ←

کانتکست را در چندین تبادل حفظ کن. Claude فایل‌های خوانده‌شده، تحلیل‌های انجام‌شده و تاریخچه‌ی گفت‌وگو را به یاد می‌سپارد. نشست‌ها را بعداً از سر بگیر، یا آن‌ها را فورک کن تا رویکردهای متفاوت را کاوش کنی.

این مثال شناسه‌ی نشست را از کوئریِ اول می‌گیرد، سپس آن را از سر می‌گیرد تا با کانتکست کامل ادامه دهد:

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


async def main():
    session_id = None

    # First query: capture the session ID
    async for message in query(
        prompt="Read the authentication module",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Resume with full context from the first query
    async for message in query(
        prompt="Now find all places that call it",  # "it" = auth module
        options=ClaudeAgentOptions(resume=session_id),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)


asyncio.run(main())

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

let sessionId: string | undefined;

// First query: capture the session ID
for await (const message of query({
  prompt: "Read the authentication module",
  options: { allowedTools: ["Read", "Glob"] }
})) {
  if (message.type === "system" && message.subtype === "init") {
    sessionId = message.session_id;
  }
}

// Resume with full context from the first query
for await (const message of query({
  prompt: "Now find all places that call it", // "it" = auth module
  options: { resume: sessionId }
})) {
  if ("result" in message) console.log(message.result);
}

درباره‌ی نشست‌ها بیشتر بدان ←

قابلیت‌های Claude Code

SDK پیکربندیِ مبتنی بر فایل‌سیستمِ Claude Code را هم پشتیبانی می‌کند. با گزینه‌های پیش‌فرض، SDK این‌ها را از پوشه‌ی .claude/ در دایرکتوریِ کاری‌ات و از ~/.claude/ بارگذاری می‌کند. برای محدودکردن منابعی که بارگذاری می‌شوند، در گزینه‌هایت setting_sources (در Python) یا settingSources (در TypeScript) را تنظیم کن.

قابلیت	توضیح	مکان
Skills	قابلیت‌های تخصصی که Claude خودکار استفاده می‌کند یا تو با `/name` فراخوانی‌شان می‌کنی	`.claude/skills/*/SKILL.md`
Commands	دستورهای سفارشی در قالب قدیمی. برای دستورهای سفارشیِ جدید از skills استفاده کن	`.claude/commands/*.md`
Memory	کانتکست و دستورالعمل‌های پروژه	`CLAUDE.md` یا `.claude/CLAUDE.md`
Plugins	گسترش با skills، agents، hooks و سرورهای MCP	برنامه‌ای، از طریق گزینه‌ی `plugins`

مقایسه‌ی Agent SDK با دیگر ابزارهای Claude

Claude Platform چند راهِ مختلف برای ساختن با Claude پیش روی تو می‌گذارد. جایگاه Agent SDK در میان آن‌ها این‌گونه است:

Anthropic Client SDK دسترسیِ مستقیم به API می‌دهد: تو پرامپت می‌فرستی و اجرای ابزار را خودت پیاده‌سازی می‌کنی. Agent SDK به تو Claude را همراه با اجرای داخلیِ ابزار می‌دهد.

با Client SDK، تو یک حلقه‌ی ابزار را پیاده‌سازی می‌کنی. با Agent SDK، Claude خودش از پسش برمی‌آید:

# Client SDK: You implement the tool loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK: Claude handles tools autonomously
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

// Client SDK: You implement the tool loop
let response = await client.messages.create({ ...params });
while (response.stop_reason === "tool_use") {
  const result = yourToolExecutor(response.tool_use);
  response = await client.messages.create({ tool_result: result, ...params });
}

// Agent SDK: Claude handles tools autonomously
for await (const message of query({ prompt: "Fix the bug in auth.ts" })) {
  console.log(message);
}

قابلیت‌های یکسان، رابطِ متفاوت:

کاربرد	بهترین انتخاب
توسعه‌ی تعاملی	CLI
خط‌لوله‌های CI/CD	SDK
اپلیکیشن‌های سفارشی	SDK
کارهای یک‌باره	CLI
خودکارسازیِ محصول	SDK

خیلی از تیم‌ها از هر دو استفاده می‌کنند: CLI برای توسعه‌ی روزمره، SDK برای محصول. ورک‌فلوها مستقیم بین این دو ترجمه می‌شوند.

Managed Agents یک REST API میزبانی‌شده است: Anthropic ایجنت و سندباکس را اجرا می‌کند و اپلیکیشن تو رویدادها را می‌فرستد و نتیجه‌ها را به‌صورت استریم بازمی‌گیرد. Agent SDK کتابخانه‌ای است که حلقه‌ی ایجنت را درون فرایندِ خودت اجرا می‌کند.

	Agent SDK	Managed Agents
اجرا در	فرایند تو، زیرساخت تو	زیرساختِ مدیریت‌شده توسط Anthropic
رابط	کتابخانه‌ی Python یا TypeScript	REST API
ایجنت روی چه کار می‌کند	فایل‌های روی زیرساخت تو	یک سندباکسِ مدیریت‌شده برای هر نشست
وضعیت نشست	JSONL روی فایل‌سیستمِ تو	لاگ رویدادِ میزبانی‌شده توسط Anthropic
ابزارهای سفارشی	توابع درون‌فرایندیِ Python یا TypeScript	Claude ابزار را فعال می‌کند؛ تو اجرا می‌کنی و نتیجه را برمی‌گردانی
بهترین برای	نمونه‌سازیِ محلی، ایجنت‌هایی که مستقیم روی فایل‌سیستم و سرویس‌های تو کار می‌کنند	ایجنت‌های محصول بدون نیاز به راهبریِ زیرساختِ سندباکس یا نشست، نشست‌های طولانی‌مدت و ناهمگام

یک مسیر رایج این است که با Agent SDK به‌صورت محلی نمونه‌سازی کنی، سپس برای محصول به Managed Agents کوچ کنی.

Changelog

برای دیدن changelogِ کامل به‌همراه به‌روزرسانی‌های SDK، رفع‌باگ‌ها و قابلیت‌های جدید:

TypeScript SDK: view CHANGELOG.md
Python SDK: view CHANGELOG.md

گزارش باگ‌ها

اگر با باگ یا مشکلی در Agent SDK روبه‌رو شدی:

TypeScript SDK: گزارش مشکلات در GitHub
Python SDK: گزارش مشکلات در GitHub

راهنمای برندینگ

برای شرکای یکپارچه‌کننده‌ی Claude Agent SDK، استفاده از برندِ Claude اختیاری است. هنگام ارجاع به Claude در محصولت:

مجاز:

«Claude Agent» (ترجیحی برای منوهای کشویی)
«Claude» (وقتی درون منویی هستی که از پیش با برچسب «Agents» نام‌گذاری شده)
«{YourAgentName} Powered by Claude» (اگر نامِ ایجنتِ موجودی داری)

مجاز نیست:

«Claude Code» یا «Claude Code Agent»
هنرِ ASCII با برندِ Claude Code یا عناصر بصری‌ای که Claude Code را تقلید کنند

محصول تو باید برندینگ خودش را حفظ کند و نباید چنان به نظر برسد که انگار Claude Code یا هر محصول دیگری از Anthropic است. برای پرسش درباره‌ی پایبندی به برندینگ، با تیم فروش‌ِ Anthropic تماس بگیر.

مجوز و شرایط

استفاده از Claude Agent SDK تابع شرایط تجاریِ خدماتِ Anthropic است، از جمله هنگامی که از آن برای پیش‌بردنِ محصولات و خدماتی استفاده می‌کنی که در اختیار مشتریان و کاربران نهاییِ خودت می‌گذاری، مگر تا حدی که یک مؤلفه یا وابستگیِ خاص تحت مجوز دیگری باشد، آن‌گونه که در فایل LICENSE آن مؤلفه ذکر شده است.

گام‌های بعدی

شروعِ سریع

ایجنتی بساز که در چند دقیقه باگ‌ها را پیدا و رفع می‌کند

ایجنت‌های نمونه

دستیار ایمیل، ایجنت پژوهش و بیشتر

TypeScript SDK

مرجع کامل API و مثال‌های TypeScript

Python SDK

مرجع کامل API و مثال‌های Python