Claude Agent SDK: Python و TypeScript
ساخت عاملها با Claude Agent SDK در Python و TypeScript: نام بستههای رسمی، query()، ClaudeSDKClient و اجرا از طریق QCode (2026).
به کلید API نیاز دارید؟ ثبتنام ←نقاط پایانی و Base URL ←
در این صفحه
آخرین بازبینی: 2026-10-20 · 📄 بر اساس مستندات رسمی (نمای کلی Claude Agent SDK، مراجع Python و TypeScript، بررسیشده در 2026-10-20)
Claude Agent SDK بسته رسمی Anthropic برای استفاده از Claude Code بهعنوان یک کتابخانه است: claude-agent-sdk را برای Python یا @anthropic-ai/claude-agent-sdk را برای TypeScript نصب کنید، سپس query() را فراخوانی کنید. این کتابخانه فایل اجرایی Claude Code را اجرا میکند و ابزارهای داخلی، مجوزها، نشستها و هوکها را همراه دارد، تا بتوانید قابلیتهای Claude Code را در برنامه خود بگنجانید (بررسیشده در 2026-10-20).
Claude Agent SDK چیست؟¶
Claude Agent SDK بلوکهای سازندهای فراهم میکند تا به شما در ساخت برنامههایی کمک کند که میتوانند:
- دستورهای زبان طبیعی را درک کنند و وظایف پیچیده را اجرا کنند
- از ابزارها استفاده کنند (جستوجو، اجرای کد، عملیات فایل و غیره)
- زمینه گفتگو را حفظ کنند برای تعاملات چندنوبتی
- به سرویسهای بیرونی متصل شوند (از طریق سرورهای MCP)
نصب Agent SDK¶
Python¶
pip install claude-agent-sdk
TypeScript¶
npm install @anthropic-ai/claude-agent-sdk
نسخه SDK از نسخه Claude Code همراه آن پیروی میکند: در مثال رسمی، SDK v0.3.191 نسخه Claude Code v2.1.191 را همراه دارد (بررسیشده در 2026-10-20).
شروع سریع با query()¶
Python¶
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions()
async for message in query(prompt="Create a Python web server", options=options):
print(message)
asyncio.run(main())
TypeScript¶
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Create a Python web server",
options: {}
})) {
console.log(message);
}
query() بهطور پیشفرض یک نشست جدید میسازد؛ برای چند تبادل در همان نشست، از ClaudeSDKClient در Python استفاده کنید (بررسیشده در 2026-10-20).
پیکربندی QCode¶
ClaudeAgentOptions(env={...}) در Python متغیرها را روی محیط فرایند ارثبریشده ادغام میکند:
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
env={
"ANTHROPIC_BASE_URL": "https://api.qcode.cc/api",
"ANTHROPIC_AUTH_TOKEN": "cr_your_api_key",
}
)
در TypeScript، options.env جای process.env را میگیرد، بنابراین ...process.env را گسترش دهید تا متغیرهای ارثبریشده مانند PATH حفظ شوند:
const options = { env: { ...process.env, ANTHROPIC_BASE_URL: "https://api.qcode.cc/api", ANTHROPIC_AUTH_TOKEN: "cr_..." } };
با یک کلید API احراز هویت کنید: مستندات رسمی بیان میکند که توسعهدهندگان ثالث مجاز نیستند برای محصولات ساختهشده بر پایه SDK، ورود claude.ai را ارائه کنند (بررسیشده در 2026-10-20). QCode بهازای هر توکن صورتحساب میکند و نرخهای هر مدل در qcode.cc/models فهرست شده است.
Agent SDK در برابر Claude Code CLI در برابر Client SDK¶
| مورد | Agent SDK | Claude Code CLI | Client SDK |
|---|---|---|---|
| قالب | کتابخانه Python / TypeScript | رابط ترمینال | anthropic / @anthropic-ai/sdk |
| نحوه اجرا | کتابخانهای که باینری Claude Code را اجرا میکند | استفاده تعاملی در ترمینال | فراخوانی مستقیم Messages API |
| قابلیتهای داخلی | ابزارها، مجوزها، نشستها و هوکها | ابزارها، مجوزها، نشستها و هوکها | شما فراخوانیهای ابزار را در کد خودتان مدیریت میکنید |
| کاربرد آن | جاسازی Claude Code در برنامه خودتان | توسعه تعاملی روزانه | فراخوانی مستقیم Messages API |
Client SDK: فراخوانی مستقیم Messages API¶
مثالهای زیر از Client SDK (anthropic / @anthropic-ai/sdk) استفاده میکنند، نه Agent SDK؛ زمانی از آن استفاده کنید که فقط به فراخوانی مستقیم Messages API نیاز دارید.
نصب Client SDK¶
Python SDK¶
pip install anthropic
TypeScript SDK¶
npm install @anthropic-ai/sdk
فراخوانی ساده پیام¶
from anthropic import Anthropic
# Via QCode.cc API
client = Anthropic(
base_url="https://api.qcode.cc/api",
api_key="cr_your_api_key"
)
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{"role": "user", "content": "Explain what a RESTful API is"}
]
)
print(message.content[0].text)
پاسخ استریمی¶
with client.messages.stream(
model="claude-opus-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Write a Python quicksort function"}
]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
استفاده از ابزار¶
استفاده از ابزار قابلیت اصلی عاملها است و به مدل اجازه میدهد ابزارهای خارجی را فراخوانی کند.
تعریف ابزارها¶
from anthropic import Anthropic
client = Anthropic(
base_url="https://api.qcode.cc/api",
api_key="cr_your_api_key"
)
# Define search tool
tools = [
{
"name": "search_web",
"description": "Search the web for information",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search keywords"
}
},
"required": ["query"]
}
},
{
"name": "calculate",
"description": "Perform mathematical calculations",
"input_schema": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "Mathematical expression, e.g., '2 + 3 * 4'"
}
},
"required": ["expression"]
}
}
]
# Send message with tools
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{"role": "user", "content": "Calculate (15 + 25) * 2 and search for what this means"}
],
tools=tools
)
# Process tool calls
for content in message.content:
if content.type == "text":
print(content.text)
elif content.type == "tool_use":
print(f"Calling tool: {content.name}")
print(f"Parameters: {content.input}")
# Simulate executing the tool
if content.name == "calculate":
result = eval(content.input["expression"])
tool_result = str(result)
elif content.name == "search_web":
tool_result = f"Results for '{content.input['query']}'..."
# Send the result back to the model
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{"role": "user", "content": "Calculate (15 + 25) * 2 and search for what this means"},
message,
{
"role": "user",
"content": None,
"type": "tool_result",
"tool_use_id": content.id,
"content": tool_result
}
],
tools=tools
)
فراخوانی استریمی ابزارها¶
with client.messages.stream(
model="claude-opus-5",
max_tokens=4096,
messages=[
{"role": "user", "content": "Create a file named hello.py that prints 'Hello, World!'"}
],
tools=[
{
"name": "write_file",
"description": "Write content to a file",
"input_schema": {
"type": "object",
"properties": {
"filename": {"type": "string"},
"content": {"type": "string"}
},
"required": ["filename", "content"]
}
}
]
) as stream:
for event in stream:
if event.type == "content_block_delta":
if event.delta.type == "text_delta":
print(event.delta.text, end="", flush=True)
elif event.delta.type == "tool_use_delta":
print(f"\n[Tool Call] {event.delta.name}")
کش prompt¶
کش prompt میتواند هزینههای مکالمات طولانی را بهطور قابلتوجهی کاهش دهد:
# System prompt (will be cached)
system_prompt = """You are a professional code review assistant.
Your responsibilities:
1. Check code security
2. Identify performance issues
3. Verify code standards
4. Provide improvement suggestions
"""
# Use cache_control to mark cacheable content
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
system=[
{
"type": "text",
"text": system_prompt,
"cache_control": {"type": "ephemeral"}
}
],
messages=[
{"role": "user", "content": "Review @src/auth/login.ts"}
]
)
نمونه ساخت Agent¶
from anthropic import Anthropic
from typing import List
class CodeReviewAgent:
def __init__(self, api_key: str):
self.client = Anthropic(
base_url="https://api.qcode.cc/api",
api_key=api_key
)
self.system_prompt = """You are a professional code review assistant.
Focus on: security, performance, readability, best practices.
Output for each review: issue list, severity, fix suggestions."""
def review(self, code_snippet: str) -> str:
message = self.client.messages.create(
model="claude-opus-5",
max_tokens=4096,
system=self.system_prompt,
messages=[
{"role": "user", "content": f"Review this code:\n\n{code_snippet}"}
]
)
return message.content[0].text
# Usage
agent = CodeReviewAgent("cr_your_api_key")
result = agent.review("SELECT * FROM users WHERE id = " + user_id)
پیکربندی QCode.cc برای Client SDK¶
import os
# Method 1: Environment variable
os.environ["ANTHROPIC_BASE_URL"] = "https://api.qcode.cc/api"
os.environ["ANTHROPIC_AUTH_TOKEN"] = "cr_your_key"
client = Anthropic() # Auto-reads environment variables
# Method 2: Asia node (recommended for mainland China)
client = Anthropic(
base_url="https://api.qcode.cc/api",
api_key="cr_your_key"
)
گامهای بعدی¶
- مرجع API - مستندات کامل پارامترهای API
- راهنمای انتخاب مدل - مدل مناسب را انتخاب کنید
- سرورهای MCP - سرویسهای خارجی را برای گسترش قابلیتها متصل کنید
با QCode شروع کنید
یک کلید API برای Claude Code، Codex و بیشتر — بر اساس توکن، قیمت هر مدل در qcode.cc/models