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 الإصدار 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"
)
الخطوات التالية¶
- مرجع API - الوثائق الكاملة لمعاملات API
- دليل اختيار النموذج - اختر النموذج المناسب
- خوادم MCP - اربط الخدمات الخارجية لتوسيع الإمكانات
ابدأ مع QCode
مفتاح API واحد لـ Claude Code وCodex وغيرها — تُحسب حسب التوكن، وأسعار كل نموذج على qcode.cc/models