claude-code-sdk

Claude Code SDK Integration

Overview

Claude Code SDK (claude-code-sdk) 是 Anthropic 官方提供的 Python 套件，用於在應用程式中整合 Claude AI Agent 功能。它支援 OAuth 認證（透過 claude login）和 API Key 認證，讓開發者可以利用 Claude Max/Pro 訂閱或 API 計費方案。這個 SDK 是建立 AI-powered 應用程式的關鍵工具，特別適合需要程式碼生成、檔案操作、或多輪對話的場景。

Key Concepts

認證方式

Description: Claude Code SDK 支援兩種認證方式 Key Features:

• OAuth 認證: 使用 claude login 後存儲在 ~/.claude/ 的憑證
• API Key 認證: 透過 ANTHROPIC_API_KEY 環境變數

Use Cases:

• OAuth：個人開發、有 Max/Pro 訂閱的用戶
• API Key：生產環境、需要計量計費的服務

SDK 核心 API

Description: query() 函數是主要的非同步介面 Key Features:

• 非同步迭代器回傳訊息
• 支援 streaming 和完整回應
• 可配置工具權限和執行限制

Use Cases: 程式碼生成、檔案操作、研究任務、唯讀分析

工具類型 (ToolType)

Description: SDK 支援多種內建工具 Key Features:

• READ, WRITE, EDIT - 檔案操作
• BASH - 終端命令執行
• GLOB, GREP - 檔案搜尋
• WEB_FETCH - 網頁抓取

Best Practices

1. 雙重認證檢查
   • 同時支援 OAuth 和 API Key
   • 優先使用 OAuth（免費使用 Max/Pro 配額）
   • API Key 作為後備方案

def check_auth_status() -> dict:
    status = {
        'api_key_set': bool(os.environ.get('ANTHROPIC_API_KEY')),
        'oauth_logged_in': False,
    }

    # 檢查 OAuth 登入狀態
    claude_dir = os.path.expanduser('~/.claude')
    if os.path.exists(claude_dir):
        auth_files = ['credentials.json', 'settings.json', '.credentials.json']
        for auth_file in auth_files:
            if os.path.exists(os.path.join(claude_dir, auth_file)):
                status['oauth_logged_in'] = True
                break

    # 只需要其中一種認證
    status['auth_available'] = status['api_key_set'] or status['oauth_logged_in']
    return status

1. 增加 Buffer Size
   • 預設 buffer 太小，處理大型回應會出錯
   • 建議增加到 50MB

try:
    from claude_code_sdk._internal.transport import subprocess_cli
    subprocess_cli._MAX_BUFFER_SIZE = 50 * 1024 * 1024  # 50MB
except Exception as e:
    print(f"Failed to patch SDK buffer size: {e}")

1. 使用 Singleton Pattern
   • 避免重複初始化
   • 共享狀態和配置

_claude_service: Optional['ClaudeCodeService'] = None

def get_claude_code() -> 'ClaudeCodeService':
    global _claude_service
    if _claude_service is None:
        _claude_service = ClaudeCodeService()
    return _claude_service