用 Claude AI Agent 跑自動任務：從零開始的實作教學
做完這篇教學，你會有一個真正能自主執行任務的 Claude Agent——它可以呼叫外部工具、根據結果決定下一步，而不只是回答你一句話就結束。
這不是那種「用 Claude 寫 code」的文章。我要講的是 agent 架構：讓模型自己決定要不要呼叫工具、呼叫哪個、然後把結果餵回去繼續推理。白話講就是，你給它一個目標，它自己想辦法完成，而不是你每一步都在旁邊盯著。
你需要準備這些東西
- Claude API 金鑰：去 console.anthropic.com 申請，新帳號有免費額度可以玩
- Python 3.10+：這篇用 Python，因為 Anthropic 的官方 SDK 最完整
- 基本 Python 知識：你不需要是 senior，但 function、dict、loop 要看得懂
- 一個想自動化的任務：這篇示範「查天氣 + 決定要不要帶傘」，夠簡單又能展示 agent 邏輯
如果你還在評估要用 Claude 還是其他模型跑 agent，先看一下 Claude 各版本模型怎麼選？從 Haiku 到 Opus 的真實差距一次看清，agent 任務大多數情況下 Sonnet 是最划算的選擇。
步驟一：安裝 SDK、設定環境
pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-xxxx"
建議用 .env 管金鑰，不要直接硬寫在 code 裡。
import anthropic
import os
client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
步驟二：定義你的工具（Tools）
Agent 的核心是「工具呼叫（tool use）」。你先告訴 Claude 有哪些工具可以用、每個工具長什麼樣子，Claude 決定要不要呼叫、呼叫哪個、帶什麼參數。
tools = [
{
"name": "get_weather",
"description": "查詢指定城市的當前天氣與降雨機率",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名稱，例如 Taipei"
}
},
"required": ["city"]
}
}
]
這個 schema 遵循 JSON Schema 規範，Claude 讀完之後就知道呼叫這個工具需要傳一個 city 字串進去。
步驟三：實作工具的真實邏輯
工具定義只是讓 Claude「知道」工具存在，實際執行還是你的 Python code 負責。這裡我們用假資料模擬天氣 API：
def get_weather(city: str) -> dict:
# 實際場景換成呼叫 OpenWeatherMap 或任何天氣 API
fake_data = {
"Taipei": {"temp": 31, "rain_probability": 75, "condition": "多雲陣雨"},
"Tokyo": {"temp": 28, "rain_probability": 20, "condition": "晴"},
}
return fake_data.get(city, {"error": "查無此城市"})
def execute_tool(tool_name: str, tool_input: dict):
if tool_name == "get_weather":
return get_weather(tool_input["city"])
return {"error": "未知工具"}
步驟四：建立 Agent Loop
這是整篇最重要的部分。Agent loop 就是：送訊息 → Claude 決定下一步 → 如果要呼叫工具就執行 → 把結果塞回去 → 繼續，直到 Claude 說「我做完了」。
def run_agent(user_message: str):
messages = [{"role": "user", "content": user_message}]
while True:
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=tools,
messages=messages
)
# Claude 說做完了，直接回傳最後文字
if response.stop_reason == "end_turn":
for block in response.content:
if hasattr(block, "text"):
return block.text
# Claude 要呼叫工具
if response.stop_reason == "tool_use":
# 把 Claude 的回應加進 messages
messages.append({"role": "assistant", "content": response.content})
# 執行每一個工具呼叫
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": str(result)
})
# 把工具結果送回給 Claude
messages.append({"role": "user", "content": tool_results})
你可以把它想成一個乒乓球來回：你發球（user message）→ Claude 接（可能要工具）→ 你把工具結果打回去 → Claude 繼續，直到它決定停下。
步驟五：跑起來看結果
result = run_agent("我明天要去台北，請查天氣，告訴我需不需要帶傘")
print(result)
輸出大概會是：「台北目前 31°C、多雲陣雨，降雨機率 75%，強烈建議帶傘，最好穿防水外套。」
Claude 自己決定呼叫 get_weather、自己把結果轉成人話、自己給建議——這就是 agent 跟普通問答的差別。
常見踩坑與怎麼避開
工具結果要轉成字串：tool_result 的 content 欄位必須是字串，直接塞 dict 會報錯。上面的 str(result) 是最簡單的做法，正式場景建議用 json.dumps(result)。
忘記把 assistant 訊息加回 messages：這個是最常見的 bug。每次 Claude 回應，不管有沒有呼叫工具，都要先把這輪的 response.content 加進 messages，才能繼續對話。
沒有設上限的 loop：Claude 偶爾會陷入「一直呼叫工具」的迴圈（尤其任務模糊的時候）。建議加一個計數器，超過 10 輪就強制停止。
token 沒算好：工具結果也吃 token，如果工具回傳的資料量大（例如搜尋結果塞了幾千字），context window 會很快爆掉。這時候要考慮截斷或摘要。順帶一提，如果你在意 API 費用，可以參考每個月到底燒了多少錢在 AI 工具上？主流訂閱費用全比較裡對 Claude API 定價的分析。
進階：串多個工具、讓 Agent 更強
一個工具夠示範概念，但真實場景通常需要多個工具組合。你可以在同一個 tools 陣列裡加更多工具，Claude 會自己判斷哪個步驟該呼叫哪個：
search_web：查即時資訊read_file/write_file：讀寫本地檔案send_email：發信通知query_database：查資料庫
把這些組合起來，你就有了一個能「查資料 → 分析 → 寫報告 → 寄信」的完整 agent pipeline。這也是 OpenAI 在做「萬能 AI Agent」的方向，不過OpenAI 要做「萬能 AI Agent」，但會用和想用是兩回事這篇有講到實際採用的落差，值得參考。
做完之後確認這些
- Agent loop 能正確結束（
stop_reason == "end_turn"） - 工具呼叫的
tool_use_id有正確對應到tool_result - Messages 陣列的 role 順序是 user → assistant → user → assistant（不能連續兩個同 role）
- 有設 loop 上限防止無限迴圈
- 工具結果是字串格式
下一步可以考慮把這個 agent 包成一個 FastAPI endpoint，或者用 LangGraph / LlamaIndex 這類框架來管理更複雜的 agent 狀態。但框架之前，先把這個裸 SDK 版本跑通——你才真正懂 agent 在做什麼。
常見問題
Claude Agent 跟直接呼叫 Claude API 有什麼不同？
直接呼叫 API 是一問一答，你問它答就結束了。Agent 模式是讓 Claude 在一個 loop 裡自主決定要呼叫哪些工具、幾次，直到任務完成才停下，更適合需要多步驟推理或串接外部資料的任務。
跑 Claude Agent 需要訂閱 Claude Pro 嗎？
不需要。Agent 是透過 Anthropic API 呼叫的，跟 Claude.ai 的訂閱是兩件事。你只需要 API 金鑰，按用量付費，新帳號有免費額度可以先試跑。
Agent loop 會不會一直跑停不下來？
有可能。尤其是任務描述模糊、或工具一直回傳錯誤時，Claude 可能陷入重複呼叫的迴圈。建議在 while loop 裡加一個計數器，超過固定輪數（例如 10 次）就強制 break 並回傳當前狀態。
可以用哪個 Claude 模型來跑 agent？
目前推薦 claude-sonnet-4-5，速度和能力的平衡最好，對 tool use 的支援也最穩定。Haiku 便宜但在複雜多步驟任務上容易出錯；Opus 最強但成本高，適合真的需要深度推理的場景。
有沒有現成框架可以不用自己寫 agent loop？
有，LangGraph 和 LlamaIndex 都支援 Claude 並且內建 agent 架構。但建議先用裸 SDK 跑通一次，理解 tool_use 和 messages 的結構，再上框架才不會踩到莫名其妙的 bug 而不知道為什麼。
分享這篇
