یک درخواست، یک پاسخ

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

لیلا خب، از کجا شروع کنیم؟ از حلقه؟ از ابزارها؟

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

لیلا معلوم است، خودِ سؤال را. و اینکه کدام مدل را می‌خواهم، چون چند تا مدل هست.

امید خوب است. دیگر چه؟ فکر کن مدل با سؤالت چه می‌کند.

لیلا جواب می‌نویسد، توکن به توکن... تا وقتی که خودش تصمیم بگیرد بایستد. آهان: اگر هیچ‌وقت تصمیم نگیرد بایستد، باید پولِ جوابی بی‌پایان را بدهم. پس باید بگویم جواب حداکثر چقدر بلند باشد.

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

لیلا مدل کجا اجرا می‌شود؟ روی لپ‌تاپِ من؟

امید روی کامپیوترهای شرکتِ سازنده. برنامه‌ات درخواست را از راه اینترنت می‌فرستد و منتظرِ پاسخ می‌ماند. هر کارِ دیگری که عامل می‌کند، خودت می‌نویسی، در این طرفِ خط.

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

وقتی برنامه‌ای از برنامه‌ی دیگر چیزی می‌خواهد، آن هم در قالبی ثابت که از پیش روی آن توافق شده، به آن قالب API (application programming interface) می‌گویند. API Claude دری است که هر برنامه‌ای از آن می‌تواند درخواستی به Claude بفرستد و پاسخ بگیرد. مدل روی کامپیوترهای Anthropic اجرا می‌شود. برنامه‌ی شما هیچ‌وقت خودِ مدل را نمی‌بیند، فقط چیزی را می‌بیند که برمی‌گردد.

درخواست در اصل یک تکه JSON است که از راه HTTPS فرستاده می‌شود، همان‌طور که مرورگر با یک وب‌سایت حرف می‌زند. می‌توانید آن را با دست بسازید، ولی لازم نیست. Anthropic یک SDK (software development kit) منتشر کرده است، یعنی کتابخانه‌ی رسمی‌اش برای پایتون، که درخواست را می‌سازد، می‌فرستد و پاسخ را به شیءهای پایتون تبدیل می‌کند. یک بار نصبش کنید:

pip install anthropic

کلید بیرون از کد می‌ماند

شرکت باید بداند چه کسی درخواست می‌دهد تا هزینه را به حسابِ درست بنویسد. کلید API (API key) برای همین است: رشته‌ای بلند و محرمانه که در Claude Console (سایتِ Anthropic برای برنامه‌نویس‌ها) ساخته می‌شود و برنامه‌ی شما آن را با هر درخواست می‌فرستد. هر کس کلیدِ شما را داشته باشد، می‌تواند پولِ شما را خرج کند.

برای همین، کلید هیچ‌وقت در کد نوشته نمی‌شود. کد کپی می‌شود، در گفت‌وگوها جا می‌گیرد و به جاهای مشترکی مثل git فرستاده می‌شود، و کلیدی که در آن باشد هر جا کد برود همراهش می‌رود. به جای آن، کلید را در محیطِ ترمینال (environment) می‌گذارید، یعنی تنظیم‌هایی که ترمینال به هر برنامه‌ای که اجرا می‌کند می‌دهد، و SDK آن را از همان‌جا می‌خواند. چنین تنظیمی را متغیرِ محیطی (environment variable) می‌گویند:

export ANTHROPIC_API_KEY=sk-ant-...

کوچک‌ترین فراخوانی

کلِ برنامه این است. mini، عاملی که در این دوره می‌سازید، هم همین‌طور شروع می‌شود:

import anthropic
 
MODEL = "claude-opus-5-5"
client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
 
reply = client.messages.create(
    model=MODEL,
    max_tokens=1000,
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
)
for block in reply.content:
    if block.type == "text":
        print(block.text)

به این‌ها دقت کنید:

• anthropic.Anthropic() یک کلاینت می‌سازد، یعنی شیئی که با API حرف می‌زند. کلید را خودش در محیط پیدا می‌کند.
• client.messages.create(...) یک درخواست می‌فرستد و منتظرِ پاسخ می‌ماند. سه آرگومانِ آن همان سه چیزی است که لیلا پیدا کرد: model، max_tokens (بیشترین تعداد توکنی که پاسخ می‌تواند داشته باشد) و messages (گفت‌وگو، که اینجا فقط یک پیام از کاربر است).
• messages فهرستی از دیکشنری‌هاست و هر کدام یک role و یک content دارد. فعلاً یک پیام دارد. چرا فهرست است، موضوعِ بخشِ بعدی است.
• پاسخ رشته نیست. یک شیء است و متن درونِ reply.content است، که فهرستی از بلوک‌هاست. اینکه چرا فهرست است و آن if برای چیست، موضوعِ درسِ بعد است.

MODEL یک ثابت در بالای برنامه است تا فقط یک جا برای عوض کردنش باشد. claude-opus-5-5 بزرگ‌ترین مدلِ روزمره‌ی Claude در اواخرِ ۲۰۲۶ است. برای تمرین، claude-haiku-5-5 حدود ۴۰ برابر ارزان‌تر است و برای بیشترِ تمرین‌های این دوره کافی است.

هزینه‌ی یک فراخوانی

پولِ توکن‌های هر درخواست را می‌پردازید: ورودی‌ای که می‌فرستید و خروجی‌ای که مدل می‌نویسد. در اواخرِ ۲۰۲۶، Opus 5.5 برای هر یک میلیون توکنِ ورودی حدود ۴ دلار و برای هر یک میلیون توکنِ خروجی ۲۰ دلار می‌گیرد. سلامِ بالا حدود دوازده توکن ورودی و کمتر از صد توکن خروجی دارد (فکر کردنش هم جزوِ آن است)، پس حدود یک‌ششمِ سنت خرج دارد. یک جلسه‌ی کار با عامل حسابِ دیگری دارد، چون هر قدمِ آن خیلی بیشتر می‌فرستد. پس بهتر است از همین اول صورت‌حساب را بفهمید. در تمرینِ «قیمتِ یک پاسخ» آن را دقیق حساب می‌کنید.

لیلا همین؟ درونِ Claude Code همین است؟

امید بله، همین فراخوانی درونِ آن است. Claude Code آن را بارها و بارها انجام می‌دهد و هر بار چیزهای خیلی بیشتری در درخواست می‌گذارد. هر کارِ دیگرش کدی معمولی است دورِ همین یک خط.

لیلا پس مدل اصلاً نمی‌داند درونِ یک عامل است.

امید فقط چیزی را می‌داند که در درخواست است. نه بیشتر. یعنی هر ویژگیِ یک عامل چیزی است که خودمان باید در درخواست بگذاریم.

امتحان کنید

اگر کلید API دارید، برنامه را با نامِ hello.py ذخیره کنید، کلید را در ترمینال تنظیم کنید و python hello.py را اجرا کنید. بعد سؤال را عوض کنید، مدل را هم claude-haiku-5-5 کنید و دوباره اجرا کنید. اگر هنوز کلید ندارید، برنامه را خط به خط بخوانید و بگویید هر آرگومان برای چیست. همه‌ی درس‌های بعد روی همین ده خط ساخته می‌شوند.

درست به کار بردن

1. کلید را در محیط نگه دارید، هرگز در فایلی که با دیگران به اشتراک می‌گذارید. اگر کلیدی یک بار در کد یا در گفت‌وگویی رفت، آن را در Console پاک کنید و کلیدِ تازه بسازید.
2. روی مدلِ کوچک تمرین کنید. ایده‌ای که روی Haiku کار کند معمولاً روی Opus هم کار می‌کند. وقتی کار مدلِ بزرگ‌تر را لازم داشت، عوضش کنید.
3. در دورانِ یادگیری، اعتبارِ کمی در حساب بگذارید. یک اشکال در حلقه می‌تواند در یک دقیقه فراخوانی‌های زیادی بسازد، و بهتر است به خاطرِ تمام شدنِ اعتبار بایستد تا اینکه صورت‌حسابِ بزرگی بسازد.
4. نامِ مدل را در یک ثابت بگذارید. زیاد عوضش می‌کنید، و وقتی فقط یک جا برای عوض کردن باشد، هیچ‌وقت نیمی از برنامه روی یک مدل و نیمِ دیگر روی مدلِ دیگر اجرا نمی‌شود.

واژه‌های این درس

• API - قالبی توافق‌شده که برنامه‌ای با آن از برنامه‌ی دیگر چیزی می‌خواهد. API Claude راهی است که برنامه با آن به Claude درخواست می‌فرستد.
• کلید API (API key) - رشته‌ای محرمانه که در هر درخواست حسابِ شما را نشان می‌دهد. در محیط نگه داشته می‌شود، هرگز در کد.
• SDK - کتابخانه‌ای که درخواست‌ها را برایتان می‌سازد و پاسخ‌ها را می‌خواند، اینجا بسته‌ی پایتونیِ anthropic.
• درخواست (request) - یک فراخوانیِ مدل: کدام مدل، بلندترین پاسخِ مجاز، و گفت‌وگو.

ایده‌ی اصلی

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