Introduction

عنوان اصلی: Module 1 — Introduction هدف یادگیری: درک جایگاه Anthropic در اکوسیستم AI، شناخت سه لایه‌ی دسترسی به Claude (Console، Workbench، API)، و انتخاب درست بین Opus، Sonnet و Haiku بر اساس workload. مفاهیم کلیدی: Claude API، Messages API، Claude Console، Workbench، Constitutional AI، Acceptable Use Policy، Responsible Scaling Policy، stop_reason، claude-fable-5، claude-opus-4-8، claude-sonnet-5، claude-haiku-4-5، context window، model snapshots vs aliases.

۱.۱ خوش‌آمدگویی به دوره — چرا Messages API «ستون فقرات» همه چیز است

دوره‌ی Building with the Claude API یک صعود عمودی است: از یک تک‌فراخوانی curl ساده شروع می‌کنید و در پایان به agentهای کاملاً مستقل tool-using می‌رسید. تمام این صعود حول یک نقطه می‌چرخد — endpoint واحد POST https://api.anthropic.com/v1/messages. هر ماژول بعدی (RAG، MCP، computer use، agents) صرفاً payload غنی‌تری برای همین فراخوانی است. Anthropic این تصمیم را عامدانه گرفته: یک endpoint مکالمه‌محور stateful، به علاوه‌ی چند endpoint اختیاری برای batch، token counting، models و بتاهای Files / Skills / Agents. هر چه دیگر می‌شنوید — caching، citations، vision، thinking، web search، tool use — همگی روی همان Messages payload سوار می‌شوند.

پیش از نوشتن هر خط کد، بهتر است سه لایه‌ی دسترسی به Claude را بشناسید: claude.ai (چت مصرف‌کننده، رابط کاربری برای کاربر نهایی)، Workbench (playground مرورگری در Console که کد آماده برای copy/paste تولید می‌کند) و API خام. این دوره عمداً از claude.ai می‌گذرد؛ ارزش API در programmability است — branching، batching، evaluations، agents — و کل دوره برای تدریس همین programmability وجود دارد.

ساختار آموزشی، یک spiral طراحی‌شده است. درس‌های ۲ تا ۱۰ یک chat-bot را از صفر می‌سازند، از درس ۱۱ به بعد لایه‌های prompt engineering، evaluation، tools، retrieval و agentic workflowها افزوده می‌شوند. این دقیقاً ترتیبی است که Anthropic در راهنمای prompt-engineering overview توصیه می‌کند: «اول success criteria تعریف کنید، بعد evaluations بسازید، سپس prompt-engineer کنید.» دانشجویانی که از evaluation رد می‌شوند، تقریباً همیشه prompt را over-engineer می‌کنند.

مثال عملی — کوچک‌ترین فراخوانی ممکن

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

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(response.content[0].text)

اشتباهات رایج

• اشتباه گرفتن حساب claude.ai با حساب Console (billing جدا دارند).
• چسباندن API key داخل JavaScript سمت کلاینت (همیشه باید از طریق backend خودتان proxy شود).
• فراموش کردن header anthropic-version: 2023-06-01 در درخواست HTTP خام (SDKها این کار را خودکار انجام می‌دهند).

۱.۲ معرفی Anthropic — ایمنی به‌عنوان زیرساخت رفتار API

Anthropic در سال ۲۰۲۱ به‌عنوان یک آزمایشگاه AI safety تاسیس شد. سه artifact کلیدی، رفتار روزانه‌ی شما در کار با API را شکل می‌دهند: Acceptable Use Policy (AUP) که مشخص می‌کند چه چیزی می‌توانید بسازید، Responsible Scaling Policy (RSP) که چگونگی تصمیم Anthropic برای انتشار مدل‌های جدید را تعیین می‌کند، و Constitutional AI که روش train شدن Claude برای رد کردن یا چالش کردن درخواست‌های خطرناک را رقم می‌زند.

از منظر developer، باید AUP را مانند یک schema سخت در نظر بگیرید. promptهایی که سیاست را نقض کنند، اغلب در runtime به‌صورت stop_reason: "refusal" ظاهر می‌شوند — این یک stop reason درجه یک است و loop شما باید آن را صراحتاً مدیریت کند.

عملیاتی، Anthropic ویژگی‌هایی مانند Zero Data Retention (ZDR) برای workloadهای regulated، classifierهای دفاع از prompt-injection روی computer use، و یک red-team داخلی از safety researcher که سطح انتشار قابلیت‌های جدید را تعیین می‌کنند، عرضه می‌کند. این موضوع نحوه‌ی debug شما را تغییر می‌دهد: وقتی Claude به‌طور غیرمنتظره توضیح بیشتر می‌خواهد، یا تایید می‌گیرد، یا رد می‌کند، علت معمولاً یک policy یا classifier است — نه یک اشتباه prompt-engineering.

مثال عملی — مدیریت تمام stop reasonها

این loop را تا انتهای دوره بارها استفاده خواهید کرد:

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
)

if resp.stop_reason == "end_turn":
    print(resp.content[0].text)
elif resp.stop_reason == "max_tokens":
    print("Truncated — increase max_tokens or chunk the request.")
elif resp.stop_reason == "stop_sequence":
    print(f"Hit custom stop: {resp.stop_sequence}")
elif resp.stop_reason == "tool_use":
    print("Model wants a tool — see Module 5.")
elif resp.stop_reason == "refusal":
    print("Refused per Acceptable Use Policy.")
elif resp.stop_reason == "pause_turn":
    print("Server tool paused — re-send to continue.")

اشتباهات رایج

• در نظر گرفتن stop_reason به‌عنوان صرفاً اطلاعاتی — این مقدار load-bearing است؛ بدون مدیریت آن، حلقه‌ی tool use به‌طور صامت می‌شکند.
• ارسال promptهایی که در claude.ai کار می‌کنند ولی روی API شکست می‌خورند، چون API فیلترهای jailbreak سمت مصرف‌کننده را جلوی خود ندارد.

۱.۳ مرور مدل‌های Claude، از Fable 5 تا Haiku

کاتالوگ فعلی Anthropic (تیر ۱۴۰۵ / ژوئیه ۲۰۲۶) چند رده‌ی همزمان دارد:

• Claude Fable 5 (خانواده‌ی Claude 5): توانمندترین مدل فعلی Anthropic، با تدابیر ایمنی اضافه. snapshot: claude-fable-5. قیمت: 10$ ورودی / 50$ خروجی به‌ازای هر MTok.
• Opus: frontier reasoning، کار agentic بلندمدت، vision سنگین؛ مدل پیش‌فرض توصیه‌شده. آخرین snapshot: claude-opus-4-8. قیمت: 5$ / 25$ به‌ازای هر MTok.
• Sonnet: workhorse تولیدی با تعادل کیفیت/هزینه/سرعت؛ Sonnet 5 در coding و کار agentic به Opus نزدیک است. آخرین snapshot: claude-sonnet-5. قیمت: 3$ / 15$ به‌ازای هر MTok (قیمت معرفی 2$ / 10$ تا 2026-08-31).
• Haiku: سریع، ارزان، embeddable برای classification و chat با حجم بالا. آخرین snapshot: claude-haiku-4-5. قیمت: 1$ / 5$ به‌ازای هر MTok.

داخل هر خانواده، شماره‌ی نسخه (5، 4.8، 4.5) جدید بودن را نشان می‌دهد. نسخه‌های قبلی مثل claude-opus-4-7 و claude-sonnet-4-6 همچنان فعال‌اند. همیشه در production به یک snapshot نسخه‌بندی‌شده pin کنید (مثلاً claude-opus-4-8) به‌جای alias مانند claude-opus-latest. این کار باعث می‌شود تغییرات رفتاری opt-in باشند، نه ناگهانی.

heuristic انتخاب مدل، workload-led است:

اختلاف هزینه بین tierها تقریباً ۵ تا ۲۰ برابر است. به همین دلیل، انتخاب کوچک‌ترین مدلی که evalهای شما را پاس می‌کند (ماژول ۳) قوی‌ترین اهرم کاهش هزینه است. اهرم بعدی token counting (POST /v1/messages/count_tokens) و سپس Batch API (با ۵۰٪ تخفیف، async) هستند.

context window امروز در همه‌ی مدل‌های فعلی ۱M token است (به‌جز Haiku 4.5 با ۲۰۰k)، و حداکثر خروجی ۱۲۸K token است (Haiku 4.5: ۶۴K). اما طولانی‌تر بودن مجانی نیست: latency با context رشد می‌کند، prompt caching بالای ~۱۰k token پیشوند تکراری اجباری می‌شود، و retrieval (ماژول ۶) معمولاً بهتر از پر کردن context پنجره عمل می‌کند.

مثال عملی — listing مدل‌ها و انتخاب smart

# List all models programmatically
models = client.models.list()
for m in models.data:
    print(m.id, m.display_name, m.created_at)

# Pin a snapshot, count tokens before sending, and fall back to Haiku for cheap calls
def smart_call(prompt: str, expensive: bool = False):
    model = "claude-opus-4-8" if expensive else "claude-haiku-4-5"
    count = client.messages.count_tokens(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    )
    if count.input_tokens > 150_000:
        raise ValueError("Prompt too large; chunk or RAG it.")
    return client.messages.create(
        model=model,
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
    )

اشتباهات رایج

• hard-code کردن aliasها (claude-opus-latest) که رفتار را به‌طور صامت تغییر می‌دهند.
• فراموش کردن این‌که مدل‌های نسل فعلی (Fable 5، Opus 4.7/4.8، Sonnet 5) از thinking تطبیقی استفاده می‌کنند و budget_tokens دستی را با خطای 400 رد می‌کنند (جزئیات در ماژول ۷).
• benchmark زدن فقط روی Opus و سپس deploy روی Haiku بدون اعتبارسنجی مجدد.