Claude Agent SDK：Session 歷史記錄、MCP 控制與 Thinking 設定

Claude Agent SDK for Python 在 v0.1.36 至 v0.1.48 版本中推出了大量新功能。本文涵蓋重點：session 歷史查詢、執行時期 MCP 伺服器管理、型別化 task 訊息、thinking 設定，以及數個重要的 bug 修復。

所有程式碼範例皆假設已安裝 claude_agent_sdk v0.1.48 或更新版本。

---

Session 歷史記錄 (v0.1.46)

兩個新的頂層函式讓你可以讀取過去的 session 資料，無需直接存取原始的 JSONL transcript 檔案。兩者皆為同步的檔案系統操作，不需要執行中的 Claude 程序。

list_sessions()

回傳依最後修改時間排序的 SDKSessionInfo 物件清單。每個項目包含 session ID、顯示摘要、檔案大小、選填的自訂標題、第一個 prompt、git branch 和工作目錄。

from claude_agent_sdk import list_sessions

# All sessions for a specific project
sessions = list_sessions(directory="/path/to/project")

for s in sessions:
    print(f"{s.session_id}  {s.summary}  ({s.file_size} bytes)")

# All sessions across every project
all_sessions = list_sessions()

# Limit results and skip git worktree scanning
recent = list_sessions(
    directory="/path/to/project",
    limit=10,
    include_worktrees=False,
)

get_session_messages()

回傳某個 session 的完整訊息清單，以 SessionMessage 物件呈現。每則訊息帶有 type（“user” 或 “assistant”）、uuid、session_id，以及原始 Anthropic API message dict。

from claude_agent_sdk import get_session_messages

messages = get_session_messages(
    "550e8400-e29b-41d4-a716-446655440000",
    directory="/path/to/project",
)

for msg in messages:
    role = msg.type
    content = msg.message.get("content", "")
    print(f"[{role}] {content[:80]}...")

# Paginate through a long session
page = get_session_messages(
    "550e8400-e29b-41d4-a716-446655440000",
    limit=20,
    offset=40,
)

應用場景：建置管理儀表板、稽核日誌、session 重播介面，或彙整跨 session token 使用量的分析管線。

---

MCP 執行時期控制 (v0.1.46)

SDK 現在支援在 session 執行期間新增和移除 MCP 伺服器。ClaudeSDKClient 上的兩個新方法 — add_mcp_server() 和 remove_mcp_server() — 讓你無需重新啟動對話即可變更可用的工具集。

現有的 toggle_mcp_server() 和 reconnect_mcp_server() 方法作為補充，可啟用/停用或重新連線已設定的伺服器。

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    permission_mode="bypassPermissions",
)

async with ClaudeSDKClient(options) as client:
    await client.query("Analyze project structure")

    # Check which MCP servers are connected
    status = await client.get_mcp_status()
    for server in status["mcpServers"]:
        print(f"{server['name']}: {server['status']}")

    # Temporarily disable a server
    await client.toggle_mcp_server("heavy-analytics", enabled=False)
    await client.query("Quick task without analytics tools")

    # Re-enable it
    await client.toggle_mcp_server("heavy-analytics", enabled=True)

    # Reconnect a failed server
    for server in status["mcpServers"]:
        if server["status"] == "failed":
            await client.reconnect_mcp_server(server["name"])

McpServerStatus TypedDict 提供型別化的欄位存取：name、status（"connected"、"pending"、"failed"、"needs-auth"、"disabled" 之一）、選填的 error、config、scope、serverInfo 和 tools。

應用場景：自適應工具可用性。一個程式撰寫 agent 可以只在任務涉及資料庫工作時載入資料庫 MCP 伺服器，切換到前端任務時再移除 — 保持工具清單的精簡，減少 prompt 雜訊。

---

型別化 Task 訊息 (v0.1.46)

過去所有 task 生命週期事件都以通用的 SystemMessage 物件抵達，迫使你手動檢查 subtype 和 data 欄位。三個新的訊息子類別提供了結構化存取：

類別	Subtype	關鍵欄位
TaskStartedMessage	task_started	task_id, description, session_id, task_type
TaskProgressMessage	task_progress	task_id, description, usage, last_tool_name
TaskNotificationMessage	task_notification	task_id, status, summary, output_file

三者皆繼承自 SystemMessage，因此現有的 isinstance(msg, SystemMessage) 檢查仍然匹配。

from claude_agent_sdk import (
    ClaudeSDKClient,
    TaskStartedMessage,
    TaskProgressMessage,
    TaskNotificationMessage,
)

async with ClaudeSDKClient(options) as client:
    await client.query("Run the full test suite")

    async for msg in client.receive_messages():
        match msg:
            case TaskStartedMessage():
                print(f"Task {msg.task_id} started: {msg.description}")

            case TaskProgressMessage():
                tokens = msg.usage.input_tokens + msg.usage.output_tokens
                print(f"  Progress: {tokens} tokens, last tool: {msg.last_tool_name}")

            case TaskNotificationMessage():
                print(f"Task {msg.task_id} {msg.status}: {msg.summary}")
                if msg.status == "failed":
                    print(f"  Output: {msg.output_file}")

TaskNotificationStatus 是一個 Literal["completed", "failed", "stopped"] — 可用於完備的 match 檢查。

應用場景：建置即時顯示 task 狀態與 token 數量的進度介面，或對 task 完成/失敗事件做出反應的編排器。

---

ResultMessage stop_reason (v0.1.46)

ResultMessage 新增了 stop_reason 欄位（選填字串），告訴你對話回合結束的原因。搭配既有的 is_error、num_turns 和 total_cost_usd 欄位，你可以完整了解查詢終止的方式與原因。

from claude_agent_sdk import ResultMessage

async for msg in client.receive_response():
    if isinstance(msg, ResultMessage):
        print(f"Stopped: {msg.stop_reason}")
        print(f"Turns: {msg.num_turns}, Cost: ${msg.total_cost_usd:.4f}")
        print(f"Error: {msg.is_error}")

---

Thinking 設定 (v0.1.36)

Extended thinking 現在有了正式的設定系統。ClaudeAgentOptions 上的 thinking 欄位取代了已棄用的 max_thinking_tokens，接受三種設定形式：

from claude_agent_sdk import (
    ClaudeAgentOptions,
    ThinkingConfigAdaptive,
    ThinkingConfigEnabled,
    ThinkingConfigDisabled,
    query,
)

# Adaptive: let the model decide when and how much to think
options_adaptive = ClaudeAgentOptions(
    model="claude-opus-4-6",
    thinking=ThinkingConfigAdaptive(type="adaptive"),
)

# Enabled with a specific token budget
options_budgeted = ClaudeAgentOptions(
    model="claude-opus-4-6",
    thinking=ThinkingConfigEnabled(type="enabled", budget_tokens=10000),
)

# Disabled entirely
options_fast = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    thinking=ThinkingConfigDisabled(type="disabled"),
)

Effort 控制

effort 欄位提供了一種更簡單的方式來控制思考深度，無需指定確切的 token 預算：

# Quick, low-effort response
options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    effort="low",
)

# Maximum reasoning depth
options = ClaudeAgentOptions(
    model="claude-opus-4-6",
    effort="max",
)

有效值："low"、"medium"、"high"、"max"。effort 選項與 thinking 彼此獨立 — 你可以只用其中一個，也可以同時使用。

---

Hook 增強 (v0.1.46)

工具生命週期 hook 的輸入現在包含 agent_id 和 agent_type 欄位。這對於多 agent 設定至關重要，因為多個 sub-agent 平行執行時，它們的工具生命週期 hook 會在同一控制通道上交錯出現。

這些欄位出現在 PreToolUseHookInput、PostToolUseHookInput 和 PostToolUseFailureHookInput 上：

• agent_id — 當 hook 從 Task 衍生的 sub-agent 內部觸發時存在。這是在多個 agent 並行執行時，將工具呼叫歸屬到特定 sub-agent 的唯一可靠方式。
• agent_type — agent 類型名稱（例如 “general-purpose”、“code-reviewer”）。在 sub-agent 內部與 agent_id 一起出現，或在以 --agent 啟動的 session 主執行緒上出現。

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher="Edit",
                hooks=[HookCallback(callback=my_hook)],
            )
        ]
    }
)

async def my_hook(input_data):
    agent = input_data.get("agent_id", "main")
    agent_type = input_data.get("agent_type", "unknown")
    tool = input_data["tool_name"]
    print(f"[{agent_type}:{agent}] using {tool}")
    return {"decision": "approve"}

---

Bug 修復

這些版本中有三個值得注意的修復：

細粒度工具串流 (v0.1.48) — include_partial_messages=True 沒有傳遞 input_json_delta 事件，因為 CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING 環境變數未在子程序中設定。此回歸影響了 v0.1.36 至 v0.1.47 版本中未啟用伺服器端功能旗標的使用者。

字串 prompt MCP 初始化 (v0.1.46) — 傳入純字串 prompt 會在 MCP 伺服器初始化完成前關閉 stdin，導致 MCP 伺服器無法註冊。此問題已修復。

未知訊息類型處理 (v0.1.40) — 無法辨識的 CLI 訊息類型（例如 rate_limit_event）會拋出 MessageParseError 而導致 session 崩潰。未知類型現在會被靜默跳過，使 SDK 能向前相容未來的 CLI 訊息新增。

---

升級路徑

這些變更皆為增量式。v0.1.36 至 v0.1.48 之間沒有引入破壞性變更。唯一的棄用項目是 max_thinking_tokens，改為使用 thinking 欄位 — 舊欄位仍然可用，但同時設定兩者時 thinking 優先。

pip install --upgrade claude-agent-sdk

這些版本中附帶的 Claude CLI 從 v2.1.42 更新至 v2.1.71。如果你透過 cli_path 固定特定的 CLI 版本，請確保至少為 v2.1.69 以獲得本文描述的完整功能集。