Build Your First AI Agent in Python (Step by Step)
三句話摘要
使用開源框架 Agentspan 在 Python 中從零建立具備崩潰恢復能力的 AI Agent。 Agent 能否在生產環境中可靠運作，關鍵在於把狀態交給 server 管理，並確保所有工具都是冪等的——崩潰只是一次可恢復的中斷，而非從頭再來。 工具定義的細節直接影響 AI 是否呼叫它。 函式名稱、參數型別提示、回傳型別、docstring 是 AI 判斷「何時該呼叫此工具」的依據，缺少 docstring 或名稱不具語意，AI 可能完全忽略該工具。
重點整理
重點- 1
工具定義的細節直接影響 AI 是否呼叫它。 函式名稱、參數型別提示、回傳型別、docstring 是 AI 判斷「何時該呼叫此工具」的依據，缺少 docstring 或名稱不具語意，AI 可能完全忽略該工具。
- 2
Agent 的執行狀態由 server 持有，而非 Python 程序。 Python 只是 client，真正的 agent runtime 跑在 Agentspan server 上，因此 Python 程序崩潰、重啟，甚至換機器，agent 都能從斷點繼續。
- 3
崩潰恢復的關鍵是 execution ID 加上冪等工具。 用 `runtime.start()` 取得 execution ID，崩潰後以該 ID 呼叫 `runtime.resume()` 續跑；工具必須設計為冪等——若目標檔案已有對應內容就跳過寫入，避免重試時產生重複資料。
- 4
Agentspan dashboard 提供完整的視覺化 debug 工具。 每次執行都被記錄為一個 execution，可點進去看節點流程圖、每個 tool call 的 input/output，大幅降低 agent 除錯成本。
實用技巧與重點
乾貨- Python 最低版本：3.10
- JDK 推薦版本：25（LTS），21 亦可
- 套件管理器：uv
- 框架名稱：Agentspan（開源免費）
- 健康檢查指令：`uv run agentspan doctor`
- 啟動 server 指令：`uv run agentspan server start`（首次約 30 秒）
- 執行 agent 指令：`uv run main.py`（約 10 秒）
- 支援 AI 供應商：OpenAI、Anthropic Claude、本地 Ollama
- 模型格式：`provider/model-name`，範例使用 `openai/gpt-4.1-mini`
- 工具定義：Python 函式 + `@tool` 裝飾器
- Agent 三要素：`name`、`model`（字串）、`tools`（列表）
- 崩潰恢復流程：`runtime.start()` → 取得 `execution_id` → 崩潰後 `runtime.resume(execution_id)`
- 工具冪等設計：寫入前檢查目標檔案是否已含對應內容，有則跳過
- 示範案例 1：WeatherBot（單工具，串行）
- 示範案例 2：TestBot（為 price_calculator 模組的 4 個函式並行生成測試，輸出至 `test_price_calculator.py`）
- 並行 tool call：4 個函式的測試生成同時執行
結論
結論“Agent 能否在生產環境中可靠運作，關鍵在於把狀態交給 server 管理，並確保所有工具都是冪等的——崩潰只是一次可恢復的中斷，而非從頭再來。”
完整解析
詳細現代 AI Agent 的開發門檻看似很高，但這支教學影片用一個完整的實作流程證明，只要掌握正確的框架與概念，任何有基礎 Python 經驗的開發者都能在一個小時內跑起第一個 agent。講者 David 選用開源框架 Agentspan 作為基礎，前置作業僅需安裝 Python 3.10 以上、JDK（推薦最新 LTS 版本 25）以及 Python 套件管理器 uv，接著 `uv add agentspan` 即可完成依賴安裝。Agentspan 本身支援 OpenAI、Anthropic Claude 及本地 Ollama 等多種 AI 供應商，只需設定對應的環境變數（如 `OPENAI_API_KEY`）即可切換。
建立 agent 的流程被拆成三個步驟：定義工具（tool）、定義 agent、撰寫執行程式碼。工具本質上就是一個普通的 Python 函式，加上 `@tool` 裝飾器後便暴露給 AI 使用。這裡有一個初學者常踩的坑：函式名稱、參數的型別提示（type hints）與 docstring 並非可選的文件，而是 AI 判斷何時呼叫這個工具的核心線索。若名稱語意模糊或缺少 docstring，AI 在面對相關問題時可能完全不會觸發該工具。Agent 本身只需三個必填欄位：名稱、模型字串（格式為 `provider/model-name`，影片示範用 `openai/gpt-4.1-mini`）以及工具清單。透過 `AgentRuntime` 連接 Agentspan server 後，呼叫 `runtime.run()` 傳入 prompt 即可啟動。第一個示範是問紐約天氣的 WeatherBot，執行後可在 Agentspan 的 web dashboard 看到完整的執行節點圖，並能點進任何 tool call 查看確切的輸入參數與輸出結果。
第二個示範是 TestBot，目標是為一個包含四個函式的 `price_calculator` 模組自動生成單元測試。此次 agent 會對每個函式並行呼叫 `save_tests` 工具，四個 tool call 同時執行，效率大幅提升，dashboard 也清楚呈現了並行執行的視覺化流程。
更核心的主題是 agent 的崩潰恢復能力。由於 Agentspan 的設計理念是「agent 狀態由 server 持有，Python 程序只是 client」，這讓崩潰恢復成為可能。講者示範在 agent 執行到一半時強制終止 Python 程序，接著從 dashboard 取得該次執行的 execution ID，填入程式碼後重新執行，agent 便從斷點繼續，不會重頭跑。這個機制有一個重要前提：工具必須設計為冪等（idempotent）——即多次執行結果相同。示範中的 `save_tests` 工具在寫入前會先檢查目標檔案是否已含對應測試，若已存在則跳過，確保重試時不會產生重複內容。最終四個函式的測試全數出現在輸出檔案中，且 dashboard 顯示這些 tool call 屬於同一個 execution ID，印證了跨越崩潰的狀態延續。
關鍵時刻
Pipeline v2帶時間戳的重點，會在逐字稿層級分析上線後產生。目前請先透過原始影片觀看。
事實查核
Pipeline v2說法查證是下一次管線升級的一部分。KeyFrame 只會顯示它真正能驗證的內容。
