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 الإصدار v2.1.191 من Claude Code (تم التحقق في 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: تنص الوثائق الرسمية على أنه لا يجوز لمطوّري الطرف الثالث تقديم تسجيل الدخول إلى claude.ai للمنتجات المبنية على SDK (تم التحقق في 2026-10-20). تحتسب QCode التكلفة لكل token، مع أسعار لكل نموذج مدرجة في 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"}
    ]
)

مثال على بناء وكيل

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

المؤسسات ←