Claude Agent SDK: Python و TypeScript

ساخت عامل‌ها با Claude Agent SDK در Python و TypeScript: نام بسته‌های رسمی، query()، ClaudeSDKClient و اجرا از طریق QCode (2026).

به‌روزرسانی 2026-11-13

به کلید 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"
)

گام‌های بعدی

با QCode شروع کنید

یک کلید API برای Claude Code، Codex و بیشتر — بر اساس توکن، قیمت هر مدل در qcode.cc/models

سازمانی ←