# Claude Agent SDK: Python و TypeScript

> **آخرین بازبینی**: 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

```bash
pip install claude-agent-sdk
```

### TypeScript

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

نسخه SDK از نسخه Claude Code همراه آن پیروی می‌کند: در مثال رسمی، SDK v0.3.191 نسخه Claude Code v2.1.191 را همراه دارد (بررسی‌شده در 2026-10-20).

## شروع سریع با query()

### Python

```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

```ts
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 متغیرها را روی محیط فرایند ارث‌بری‌شده ادغام می‌کند:

```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` حفظ شوند:

```ts
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](https://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

```bash
pip install anthropic
```

#### TypeScript SDK

```bash
npm install @anthropic-ai/sdk
```

### فراخوانی ساده پیام

```python
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)
```

### پاسخ استریمی

```python
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)
```

### استفاده از ابزار

استفاده از ابزار قابلیت اصلی عامل‌ها است و به مدل اجازه می‌دهد ابزارهای خارجی را فراخوانی کند.

#### تعریف ابزارها

```python
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
        )
```

### فراخوانی استریمی ابزارها

```python
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 می‌تواند هزینه‌های مکالمات طولانی را به‌طور قابل‌توجهی کاهش دهد:

```python
# 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

```python
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

```python
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](/docs/getting-started/endpoints-and-api-paths) - مستندات کامل پارامترهای API
- [راهنمای انتخاب مدل](/docs/usage/model-selection) - مدل مناسب را انتخاب کنید
- [سرورهای MCP](/docs/advanced/mcp) - سرویس‌های خارجی را برای گسترش قابلیت‌ها متصل کنید