測驗：MLflow GenAI 教學 – 追蹤 Claude Code
共 5 題，點選答案後會立即顯示結果
1. 使用 MLflow CLI 追蹤模式時，如何在終端啟用 Claude Code 對話追蹤？
2. 在 Python SDK 中使用 MLflow 追蹤 Claude Agent SDK 時，必須使用哪種類別才能被追蹤？
3. CLI 追蹤模式與 SDK 追蹤模式的最低 MLflow 版本需求分別為何？
4. 執行 mlflow autolog claude 後，MLflow 會在哪裡寫入追蹤設定？
5. 在 Python 程式中使用 SDK 追蹤時，mlflow.anthropic.autolog() 應該在什麼時機呼叫？
在 AI 代理開發中，追蹤每一步操作是確保系統可靠的關鍵。本篇將介紹如何使用 MLflow 追蹤 Claude Code 的互動，包括命令列工具（CLI）與 Python SDK 兩種模式。無論你是用互動式終端操作 Claude，還是在 Python 應用中整合 Claude Agent SDK，都能透過 MLflow 完整記錄代理行為。
環境需求
在開始之前，請確保環境符合以下要求：
| 元件 | 最低版本 | 用途 |
|---|---|---|
| MLflow | 3.4+（CLI）/ 3.5+（SDK） | 追蹤框架 |
| Claude Code CLI | 最新版 | 互動式對話追蹤 |
| Claude Agent SDK | 0.1.0+ | Python 程式整合 |
| Python | 3.10+ | 執行環境 |
安裝必要套件：
# 安裝 MLflow
pip install mlflow>=3.5.0
# 安裝 Claude Agent SDK
pip install claude-agent-sdk>=0.1.0
Code language: PHP (php)CLI 追蹤模式
如果你習慣在終端使用 claude 指令與 Claude Code 互動，CLI 追蹤模式讓你無需修改任何程式碼就能自動追蹤對話。
啟用追蹤
# 在當前目錄啟用追蹤
mlflow autolog claude
# 在指定專案目錄啟用
mlflow autolog claude ~/my-project
# 指定實驗名稱
mlflow autolog claude -n "My AI Project"
# 指定實驗 ID
mlflow autolog claude -e 123456789
# 使用本地檔案追蹤
mlflow autolog claude -u file://./custom-mlruns
Code language: PHP (php)檢查追蹤狀態
mlflow autolog claude --status
這個指令會顯示當前目錄的追蹤設定狀態。
停用追蹤
mlflow autolog claude --disable
CLI 追蹤的運作原理
當你執行 mlflow autolog claude 時，MLflow 會在專案目錄的 .claude/settings.json 中寫入設定檔，並建立必要的 hooks。之後每次你在該目錄執行 claude 指令，對話內容就會自動記錄到 MLflow。
追蹤內容
CLI 模式會自動捕捉：
- User prompts：你輸入的提示詞
- Assistant responses：Claude 的回應內容
- Tool usage：工具呼叫記錄（檔案操作、程式執行、網頁搜尋等）
- Timing：對話時間與延遲
- Session metadata：工作目錄、使用者資訊
SDK 追蹤模式
當你在 Python 應用中使用 Claude Agent SDK 時，可以透過 mlflow.anthropic.autolog() 啟用程式化追蹤。
基本設定
import mlflow.anthropic
# 啟用自動追蹤
mlflow.anthropic.autolog()
# 設定實驗（選用）
mlflow.set_experiment("my_claude_app")
Code language: CSS (css)完整範例
import asyncio
import mlflow
import mlflow.anthropic
from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock
# 啟用自動追蹤（必須在建立 ClaudeSDKClient 之前）
mlflow.anthropic.autolog()
# 設定追蹤位置與實驗
mlflow.set_tracking_uri("file://./mlruns")
mlflow.set_experiment("claude_agent_demo")
async def main():
async with ClaudeSDKClient() as client:
# 發送查詢
await client.query("請列出目前目錄的檔案結構")
# 接收回應
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Claude: {block.text}")
if __name__ == "__main__":
asyncio.run(main())
Code language: PHP (php)重要限制：僅支援 ClaudeSDKClient
MLflow 的追蹤功能只支援使用 ClaudeSDKClient 的呼叫。直接呼叫 query() 函式不會被追蹤。
from claude_agent_sdk import query, ClaudeSDKClient
# 這樣不會被追蹤
result = await query("Hello") # 不支援！
# 必須使用 ClaudeSDKClient
async with ClaudeSDKClient() as client:
await client.query("Hello") # 會被追蹤
async for msg in client.receive_response():
print(msg)
Code language: PHP (php)這是因為 query() 是一個簡化的文字生成 API，不支援工具呼叫，而 ClaudeSDKClient 才是完整的代理 API。
停用 SDK 追蹤
# 停用自動追蹤
mlflow.anthropic.autolog(disable=True)
Code language: PHP (php)CLI 與 SDK 模式的差異
| 特性 | CLI 模式 | SDK 模式 |
|---|---|---|
| 適用場景 | 互動式終端操作 | Python 應用程式 |
| 設定方式 | 命令列設定一次 | 程式碼中呼叫 autolog |
| 程式碼修改 | 不需要 | 需要加入 autolog 呼叫 |
| 支援工具追蹤 | 是 | 是 |
| 非同步支援 | N/A | 原生支援 |
| 最低 MLflow 版本 | 3.4 | 3.5 |
選擇建議
- 使用 CLI 模式：當你在終端與 Claude Code 互動，進行探索性開發或快速原型時
- 使用 SDK 模式：當你在 Python 應用中整合 Claude Agent SDK，建構自動化系統或 API 服務時
檢視追蹤結果
啟動 MLflow UI 檢視追蹤內容：
mlflow ui --port 5000
開啟瀏覽器訪問 http://localhost:5000，在 Traces 分頁可以看到：
- Span 樹狀結構：每個對話的巢狀呼叫結構
- 輸入輸出：每個步驟的輸入提示詞與輸出回應
- 工具呼叫：Claude 使用的工具名稱、參數與結果
- 時間資訊：每個操作的延遲時間
故障排除
CLI 追蹤問題
- 檢查設定檔是否存在
- 檢查追蹤日誌
- 驗證追蹤狀態
SDK 追蹤問題
- 確認 autolog 呼叫順序
mlflow.anthropic.autolog() 必須在建立 ClaudeSDKClient 之前呼叫。
- 確認使用 ClaudeSDKClient
直接使用 query() 不會被追蹤，必須使用 ClaudeSDKClient。
- 檢查追蹤 URI 設定
- 確認實驗設定
實戰：追蹤帶工具呼叫的代理
以下範例展示如何追蹤一個使用自訂工具的 Claude 代理：
import asyncio
import mlflow
import mlflow.anthropic
from claude_agent_sdk import (
ClaudeSDKClient,
ClaudeAgentOptions,
AssistantMessage,
TextBlock,
tool,
create_sdk_mcp_server,
)
# 啟用追蹤
mlflow.anthropic.autolog()
mlflow.set_experiment("tool_demo")
# 定義自訂工具
@tool("get_weather", "Get weather for a city", {"city": str})
async def get_weather(args):
city = args["city"]
# 模擬天氣查詢
return {
"content": [
{"type": "text", "text": f"{city} 目前天氣：晴天，25 度"}
]
}
# 建立 MCP 伺服器
server = create_sdk_mcp_server(
name="weather-tools",
version="1.0.0",
tools=[get_weather]
)
# 設定代理選項
options = ClaudeAgentOptions(
mcp_servers={"weather": server},
allowed_tools=["mcp__weather__get_weather"]
)
async def main():
async with ClaudeSDKClient(options=options) as client:
await client.query("台北現在天氣如何？")
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text)
if __name__ == "__main__":
asyncio.run(main())
Code language: PHP (php)執行後，在 MLflow UI 中可以看到完整的追蹤記錄，包括：
- 使用者輸入的提示詞
- Claude 決定呼叫
get_weather工具 - 工具的輸入參數（
{"city": "台北"}） - 工具的回傳結果
- Claude 的最終回應
重點回顧
- CLI 追蹤：使用
mlflow autolog claude設定，適合互動式終端操作 - SDK 追蹤：使用
mlflow.anthropic.autolog()啟用，適合 Python 應用 - 限制：SDK 追蹤僅支援
ClaudeSDKClient，不支援直接呼叫query() - 追蹤內容：prompts、responses、tool calls、duration
- 故障排除：檢查
.claude/settings.json、確認 autolog 呼叫順序
下一篇我們將學習如何使用 MLflow 的評估功能，為你的 Claude 代理建立自動化品質檢測。
延伸閱讀
- MLflow Tracing Claude Code 官方文件
- MLflow Autolog Claude Agent SDK 介紹
- Claude Agent SDK Python 文件
- MLflow CLI 命令參考
進階測驗：MLflow GenAI 教學 – 追蹤 Claude Code
測驗目標：驗證你是否能在實際情境中應用所學。
共 5 題，包含情境題與錯誤診斷題。
共 5 題，包含情境題與錯誤診斷題。
1. 你正在開發一個 Python 自動化腳本，需要追蹤 Claude Agent 的所有工具呼叫。你已經安裝了 MLflow 3.5，下一步應該怎麼做？ 情境題
2. 同事的追蹤程式碼沒有記錄任何內容到 MLflow，請問下面程式碼最可能的問題是什麼？ 錯誤診斷
import asyncio
from claude_agent_sdk import query
result = asyncio.run(query(“Hello, Claude!”))
3. 你是團隊的 DevOps 工程師，需要在現有的終端 Claude Code 工作流程中加入追蹤，但不想修改任何程式碼。最適合的做法是什麼？ 情境題
4. 你的 SDK 追蹤程式執行後沒有錯誤，但在 MLflow UI 看不到任何 trace。檢查下面的程式碼，問題出在哪裡？ 錯誤診斷
import asyncio
import mlflow.anthropic
from claude_agent_sdk import ClaudeSDKClient
async def main():
async with ClaudeSDKClient() as client:
mlflow.anthropic.autolog() # 在這裡啟用
await client.query(“列出檔案”)
async for msg in client.receive_response():
print(msg)
asyncio.run(main())