شروعِ سریع

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

کاری که انجام می‌دهی:

یک پروژه را با Agent SDK راه‌اندازی می‌کنی
یک فایل با مقداری کدِ باگ‌دار می‌سازی
ایجنتی را اجرا می‌کنی که باگ‌ها را به‌صورت خودکار پیدا و رفع می‌کند

پیش‌نیازها

Node.js 18+ یا Python 3.10+
یک حساب Anthropic (اینجا ثبت‌نام کن)

راه‌اندازی

ساختِ پوشه‌ی پروژه

یک دایرکتوریِ جدید برای این شروعِ سریع بساز:

mkdir my-agent
cd my-agent

برای پروژه‌های خودت، می‌توانی SDK را از هر پوشه‌ای اجرا کنی؛ به‌صورت پیش‌فرض به فایل‌های آن دایرکتوری و زیردایرکتوری‌هایش دسترسی خواهد داشت.

نصبِ SDK

بسته‌ی Agent SDK را برای زبانِ خودت نصب کن:

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

uv یک مدیرِ بسته‌ی سریعِ Python است که محیط‌های مجازی را به‌صورت خودکار مدیریت می‌کند:

uv init
uv add claude-agent-sdk

یک محیط مجازی بساز و فعالش کن، سپس بسته را نصب کن.

روی macOS یا Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

روی Windows:

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

اگر PowerShell به‌خاطر خطای execution policy جلوی Activate.ps1 را گرفت، اول Set-ExecutionPolicy -Scope Process RemoteSigned را اجرا کن.

تنظیمِ کلید API

یک کلید API از Claude Console بگیر، سپس یک فایل .env در دایرکتوریِ پروژه‌ات بساز:

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 را ببین.

ساختِ یک فایلِ باگ‌دار

این شروعِ سریع تو را در ساختِ ایجنتی که می‌تواند باگ‌های کد را پیدا و رفع کند، قدم‌به‌قدم همراهی می‌کند. اول، به یک فایل با چند باگِ عمدی نیاز داری تا ایجنت رفعشان کند. فایلِ utils.py را در دایرکتوریِ my-agent بساز و کدِ زیر را در آن بچسبان:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

این کد دو باگ دارد:

calculate_average([]) با خطای تقسیم بر صفر کرش می‌کند
get_user_name(None) با یک TypeError کرش می‌کند

ساختِ ایجنتی که باگ‌ها را پیدا و رفع می‌کند

اگر از SDKِ Python استفاده می‌کنی فایلِ agent.py و برای TypeScript فایلِ agent.ts را بساز:

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


async def main():
    # Agentic loop: streams messages as Claude works
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Auto-approve these tools
            permission_mode="acceptEdits",  # Auto-approve file edits
        ),
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Final result


asyncio.run(main())

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

// Agentic loop: streams messages as Claude works
for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"], // Auto-approve these tools
    permissionMode: "acceptEdits" // Auto-approve file edits
  }
})) {
  // Print human-readable output
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) {
        console.log(block.text); // Claude's reasoning
      } else if ("name" in block) {
        console.log(`Tool: ${block.name}`); // Tool being called
      }
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`); // Final result
  }
}

این کد سه بخشِ اصلی دارد:

query: نقطه‌ی ورودِ اصلی که حلقه‌ی ایجنتیک را می‌سازد. یک iteratorِ async برمی‌گرداند، پس با async for پیام‌ها را همان‌طور که Claude کار می‌کند استریم می‌کنی. API کاملش را در مرجعِ SDKِ Python یا TypeScript ببین.
prompt: کاری که می‌خواهی Claude انجام دهد. Claude بر اساسِ وظیفه تشخیص می‌دهد از کدام ابزارها استفاده کند.
options: پیکربندیِ ایجنت. این مثال از allowedTools برای پیش‌تأییدِ Read، Edit و Glob و از permissionMode: "acceptEdits" برای تأییدِ خودکارِ تغییراتِ فایل استفاده می‌کند. گزینه‌های دیگر شاملِ systemPrompt، mcpServers و موارد بیشتر است. همه‌ی گزینه‌ها را برای Python یا TypeScript ببین.

حلقه‌ی async for همان‌طور که Claude فکر می‌کند، ابزارها را فرا می‌خواند، نتایج را مشاهده می‌کند و تصمیم می‌گیرد قدمِ بعدی چه باشد، در حال اجرا می‌ماند. هر تکرار یک پیام تولید می‌کند: استدلالِ Claude، یک فراخوانیِ ابزار، یک نتیجه‌ی ابزار، یا نتیجه‌ی نهایی. SDK ارکستراسیون (اجرای ابزار، مدیریتِ کانتکست، تلاش‌های مجدد) را برعهده می‌گیرد و تو فقط استریم را مصرف می‌کنی. حلقه وقتی تمام می‌شود که Claude وظیفه را به پایان برساند یا به خطا بخورد.

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

اجرای ایجنتت

ایجنتت آماده است. آن را با دستورِ زیر اجرا کن:

npx tsx agent.ts

uv run agent.py

در حالی که محیطِ مجازی هنوز فعال است:

python agent.py

بعد از اجرا، utils.py را بررسی کن. کدِ دفاعی‌ای می‌بینی که لیست‌های خالی و کاربرانِ null را مدیریت می‌کند. ایجنتت به‌صورت خودمختار:

utils.py را خواند تا کد را بفهمد
منطق را تحلیل کرد و حالت‌های مرزی‌ای را که کرش می‌کردند شناسایی کرد
فایل را ویرایش کرد تا مدیریتِ خطای مناسب را اضافه کند

این همان چیزی است که Agent SDK را متفاوت می‌کند: Claude ابزارها را مستقیماً اجرا می‌کند، به‌جای اینکه از تو بخواهد آن‌ها را پیاده‌سازی کنی.

پرامپت‌های دیگر را امتحان کن

حالا که ایجنتت راه‌اندازی شده، چند پرامپتِ متفاوت را امتحان کن:

"Add docstrings to all functions in utils.py"
"Add type hints to all functions in utils.py"
"Create a README.md documenting the functions in utils.py"

ایجنتت را سفارشی کن

می‌توانی رفتارِ ایجنتت را با تغییرِ گزینه‌ها عوض کنی. چند مثال:

افزودنِ قابلیتِ جست‌وجوی وب:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)

const _ = {
  options: {
    allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
    permissionMode: "acceptEdits"
  }
};

دادنِ یک پرامپتِ سیستمیِ سفارشی به Claude:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

const _ = {
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
    systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
  }
};

اجرای دستورها در ترمینال:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)

const _ = {
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Bash"],
    permissionMode: "acceptEdits"
  }
};

با فعال بودنِ Bash، این را امتحان کن: "Write unit tests for utils.py, run them, and fix any failures"

مفاهیمِ کلیدی

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

ابزارها	کاری که ایجنت می‌تواند بکند
`Read`، `Glob`، `Grep`	تحلیلِ فقط‌خواندنی
`Read`، `Edit`، `Glob`	تحلیل و تغییرِ کد
`Read`، `Edit`، `Bash`، `Glob`، `Grep`	اتوماسیونِ کامل

حالت‌های دسترسی کنترل می‌کنند چقدر نظارتِ انسانی می‌خواهی:

حالت	رفتار	موردِ استفاده
`acceptEdits`	ویرایش‌های فایل و دستورهای رایجِ فایل‌سیستم را خودکار تأیید می‌کند، برای بقیه‌ی اقدامات می‌پرسد	ورک‌فلوهای توسعه‌ی مورد اعتماد
`dontAsk`	هر چیزی را که در `allowedTools` نباشد رد می‌کند	ایجنت‌های headlessِ قفل‌شده
`auto` (فقط TypeScript)	یک طبقه‌بندِ مدلی هر فراخوانیِ ابزار را تأیید یا رد می‌کند	ایجنت‌های خودمختار با حفاظ‌های ایمنی
`bypassPermissions`	هر ابزار را بدونِ پرسش اجرا می‌کند، مگر اینکه یک قاعده‌ی `ask` صریح مطابقت کند	CIِ سندباکس‌شده، محیط‌های کاملاً مورد اعتماد
`default`	برای مدیریتِ تأیید به یک کالبکِ `canUseTool` نیاز دارد	جریان‌های تأییدِ سفارشی

مثالِ بالا از حالتِ acceptEdits استفاده می‌کند که عملیاتِ فایل را خودکار تأیید می‌کند تا ایجنت بتواند بدونِ پرامپت‌های تعاملی اجرا شود. اگر می‌خواهی از کاربر تأیید بگیری، از حالتِ default استفاده کن و یک کالبکِ canUseTool فراهم کن که ورودیِ کاربر را جمع می‌کند. برای کنترلِ بیشتر، دسترسی‌ها را ببین.

عیب‌یابی

خطای API: `thinking.type.enabled` برای این مدل پشتیبانی نمی‌شود

Claude Opus 4.7، thinking.type.enabled را با thinking.type.adaptive جایگزین می‌کند. نسخه‌های قدیمی‌ترِ Agent SDK وقتی claude-opus-4-7 را انتخاب می‌کنی با خطای API زیر شکست می‌خورند:

API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

برای استفاده از Opus 4.7 به Agent SDK نسخه‌ی v0.2.111 یا بالاتر ارتقا بده.

قدم‌های بعدی

حالا که اولین ایجنتت را ساختی، یاد بگیر چطور قابلیت‌هایش را گسترش دهی و آن را برای موردِ استفاده‌ات تنظیم کنی:

دسترسی‌ها: کنترل کن ایجنتت چه کاری می‌تواند بکند و کِی به تأیید نیاز دارد
Hooks: کدِ سفارشی را پیش یا پس از فراخوانیِ ابزارها اجرا کن
نشست‌ها: ایجنت‌های چندنوبتی بساز که کانتکست را حفظ می‌کنند
سرورهای MCP: به دیتابیس‌ها، مرورگرها، APIها و دیگر سیستم‌های بیرونی متصل شو
Hosting: ایجنت‌ها را روی Docker، ابر و CI/CD مستقر کن
ایجنت‌های نمونه: نمونه‌های کامل را ببین: دستیارِ ایمیل، ایجنتِ پژوهش و موارد بیشتر