100-Day AI Knowledge Challenge
AI Phase 08 — Agents / Tools / Workflows(Day 71–80)
公司真正想知道的不是「你用 LangGraph 寫過 agent 嗎」,而是:你知道什麼情況該用 Agent、什麼情況不該用嗎? Agent 的權限怎麼限制、怎麼避免無限 loop、tool 失敗怎麼處理、怎麼 evaluation1。這個 Phase 的每一天都在回答其中一題。
主課程是 Hugging Face Agents Course(agent fundamentals、tools、actions、observations、smolagents、LangGraph、Agentic RAG、observability、evaluation);搭配三份:Anthropic 的 Building Effective Agents(必讀,負責 workflow vs agent 的判斷,讓你不被 framework API 綁住)、LangGraph 官方文件(State → Node → Edge → Execution,以及 persistence 與 human-in-the-loop)、Model Context Protocol 官方文件(MCP 解決什麼問題;MCP 不是 Agent 本身)2。
整個 Phase 的路線:
Day 71 該不該用 Agent(判斷)
Day 72 模型怎麼「看到」工具(messages、special tokens、tool 描述)
Day 73 手寫 Thought → Action → Observation 迴圈與終止條件
Day 74 五種 workflow:大部分問題不需要 agent
Day 75 smolagents:code action vs JSON action,以及執行模型寫的程式碼有多危險
Day 76 LangGraph:State → Node → Edge → Execution
Day 77 checkpoint、interrupt、crash 後從斷點繼續
Day 78 MCP:把工具做成一個獨立的 server
Day 79 Project 3(一):權限、核准、重試、冪等
Day 80 Project 3(二):evaluation 與回歸測試
Day 79–80 組成 Project 3:Tool-using Agent——LLM → tool selection → API → state → execution → evaluation,展示 permissions、failure handling、retry、human approval、evaluation3。
總綱第 4 節的重疊對照表在這個 Phase 列了兩天:agent loop 與 policy/終止條件(Backend Day 89)、reliability 與 state/checkpoint/recovery(Backend Day 90)。這些原理不重寫,Day 71、73、77、79 開頭各有一段連過去,新角度放在 workflow vs agent 的判斷、framework 實作與 MCP4。
環境: 這個 Phase 的實作全部只用 Python 標準函式庫(教材作者用 Python 3.12.8),不需要 API key,也不需要裝任何套件。所有檔案放在同一個資料夾 p08/。模型一律用「替身 LLM」(照順序吐出寫好的回應,或一組固定規則)代替,原因跟 Phase 07 一樣:這幾天要驗證的是迴圈、權限、重試、checkpoint 這些框架行為,換成真的模型只會讓結果每次不同、看不出框架有沒有擋住。Day 80 的 Deep Dive 說明怎麼接上 Phase 06 的真模型。
Framework 的程式碼教材作者沒有實跑: Day 75 的 smolagents 範例、Day 76–77 的 LangGraph 範例需要 pip install smolagents/pip install langgraph,smolagents 的範例還要 Hugging Face token。教材作者的環境沒有裝這些套件,所以這些片段只照官方頁面抄錄、沒有執行過,每一段都標明了。每天的 Core 實作是自己用標準函式庫重寫同一個機制,這部分都實跑過。
預期輸出怎麼讀: 下面每段「預期」都是教材作者 2026-10-17 實跑的輸出,替身 LLM 是確定性的,所以每次都一樣。
教材查證的範圍(請先看): 2026-10-17 查證時,下面引用的每一頁都實際開過,但只確認到「小節標題+該節重點」的層級,沒有逐字比對。總綱列的 Anthropic 連結(resources.anthropic.com/building-effective-ai-agents)2026-10-17 查證時是要先填表才能下載的電子書頁面,看不到內容;這個 Phase 改用 Anthropic 公開的同名文章 Building effective agents(2024-12-19),兩者是不是同一份內容沒有辦法確認。MCP 文件現在是協定版本 2026-07-28:這一版沒有 initialize 握手,每個 request 自己帶版本與 capabilities;網路上很多教學還是舊的握手流程(2025-11-25 以前),Day 78 會說明怎麼分辨。
Day 71 — Agent 是什麼,以及什麼時候不該用 Agent
今天要回答的問題
workflow 跟 agent 差在哪裡?拿到一個需求時,怎麼判斷它該用一次 LLM 呼叫、一條固定的 workflow,還是一個 agent?
主教材(Core)
- Anthropic — Building effective agents(What are agents?、When (and when not) to use agents、When and how to use frameworks 三節),預估 25 分鐘
- Hugging Face Agents Course — Unit 1 What is an Agent?(The Big Picture: Alfred The Agent、Let's go more formal、The spectrum of "Agency"、How does an AI take action on its environment? 四節),預估 20 分鐘
- 實作(研究產出),預估 60 分鐘
搭配(Companion,選讀)
- Hugging Face Agents Course — Unit 0 Welcome(What's the syllabus? 一節),先看整門課的地圖:Unit 1 基礎、Unit 2 三個 framework、Unit 3 Agentic RAG、Unit 4 期末、Bonus Unit 2 observability 與 evaluation。這個 Phase 只取其中一部分;預估 5 分鐘
- Anthropic 電子書 Building Effective AI Agents:此資源 2026-10-17 查證時需要填表下載,無法查證內容
讀的時候抓這幾個重點
- 這部分已在 Backend Day 89 講過:Agent Loop(Observe → Reason → Act)怎麼運作、State 每一輪累積什麼、為什麼要有系統層的終止條件。今天的新角度是:在寫迴圈之前,先判斷這個需求到底需不需要迴圈。
- workflow 和 agent 的分界是「誰決定下一步」。 Anthropic 這篇文章把兩者都叫 agentic system,但分得很清楚:workflow 是「LLM 和工具照事先寫好的程式路徑被串起來」,agent 是「LLM 自己動態決定流程與要用哪個工具」。用這條線看:一個「先分類、再依類別回覆」的客服系統,即使用了三次 LLM,也是 workflow,因為分支寫在程式碼裡。
- 預設答案是「先不要用 agent」。 When (and when not) to use agents 一節的建議是:先找最簡單的解法,必要時才加複雜度;agentic system 通常是用延遲和成本換表現。很多時候「一次 LLM 呼叫+retrieval+幾個範例」就夠了。workflow 適合步驟明確、需要可預測的任務;agent 適合步驟無法事先列出、需要模型自己判斷的任務。
- Framework 讓你起步快,但會遮住 prompt。 When and how to use frameworks 一節提醒:framework 的抽象層會讓你看不到實際送出的 prompt 和收到的 response,比較難 debug;建議先直接用 LLM API,真的要用 framework 也要懂它底下在做什麼。這就是 Day 73、76、77 都要先自己手寫一遍、再看 framework 的原因。
- Agency 是一條光譜,不是有或沒有。 HF 課程的 The spectrum of "Agency" 一節把系統依「模型能決定多少事」排成好幾級:從模型輸出完全不影響流程,到模型決定走哪條分支、決定呼叫哪個工具、決定要不要再跑一輪、甚至寫出程式碼來執行。它也提醒 Action 跟 Tool 不一樣:一個 action 可能用到好幾個 tool。越往光譜右邊,彈性越大,可預測性和可控性越低。
實作
這一天不寫程式,產出一張判斷表。在 p08/day71-decision.md 建立下面這張表,六個情境每一列都要填完:
| 情境 | 步驟能不能事先列出? | 做錯的代價 | 需要哪些工具 | 你的選擇 | 一句話理由 |
|---|---|---|---|---|---|
| 1. 把客服信分成「帳務/技術/其他」三類 | |||||
| 2. 把一份英文產品文件翻成中文,再檢查術語是否一致 | |||||
| 3. 使用者問「我上個月為什麼被多收錢?」,要查帳單、查付款紀錄、必要時開退款單 | |||||
| 4. 每天早上把 10 個固定來源的新聞摘要成一份報告 | |||||
| 5. 在一個陌生的 codebase 裡修一個 bug(不知道要改幾個檔案) | |||||
| 6. 依照使用者描述,在雲端開一台 VM 並設定防火牆 |
「你的選擇」只能填三種之一:單次 LLM 呼叫(可以加 retrieval)、workflow(寫出是哪一種,Day 74 會學五種名稱,今天先用自己的話描述步驟)、agent。
填完之後,在表格下面寫一段「我的判斷流程」,至少三個問題,依序回答就能得出選擇(例如:步驟能不能事先列出?→ 錯一步的代價能不能承受?→ 有沒有清楚的完成條件?)。最後挑一個你選了 agent 的情境,寫出它最可能失控的方式(無限 loop、做了不可逆的動作、花太多錢),Day 73 與 Day 79 會回來處理。
過關標準
- 能用自己的話回答:workflow 和 agent 的分界是什麼?一個系統呼叫了三次 LLM,為什麼還可能只是 workflow?
- 能回答:Anthropic 為什麼建議先不要用 framework?framework 會遮住哪兩樣東西?
- 產出:
day71-decision.md,六列都填完、每列有理由,加上「我的判斷流程」和一個失控情境
Day 72 — 模型怎麼「看到」工具:messages、special tokens 與工具描述
今天要回答的問題
LLM 只會輸出文字,它是怎麼「呼叫」工具的?工具的描述從哪裡來、放在哪裡?模型傳錯參數時,該由誰處理?
主教材(Core)
- Hugging Face Agents Course — Unit 1 Messages and Special Tokens(Messages: The Underlying System of LLMs、Chat-Templates 兩節,含 Base Models vs. Instruct Models),預估 20 分鐘
- Hugging Face Agents Course — Unit 1 What are Tools?(How do tools work?、How do we give tools to an LLM? 兩節,含 Auto-formatting Tool sections 與 Model Context Protocol (MCP): a unified tool interface),預估 25 分鐘
- 實作,預估 60 分鐘
搭配(Companion,選讀)
- Anthropic — Building effective agents 的 Appendix 2: Prompt engineering your tools:工具描述要像寫給新同事的文件;poka-yoke(把參數設計成很難用錯);他們把工具改成只收絕對路徑之後,模型就不再犯相對路徑的錯。跟今天的「描述從程式碼自動產生」放在一起讀;預估 10 分鐘
- AI 課程 Phase 06 Day 55 — Tool calling 跨 provider:兩家 API 實際的 tool calling wire format。今天看的是「描述怎麼產生」,Day 55 看的是「描述怎麼送出去」
讀的時候抓這幾個重點
- 模型看到的永遠是一長串文字。 Messages and Special Tokens 頁說:你送出的
messages列表(system、user、assistant)會被 chat template 轉成一個 prompt 字串,用每個模型自己的 special token 標出每一輪的開始和結束——SmolLM2 用<|im_start|>和<|im_end|>,Llama 3.2 用<|start_header_id|>、<|end_header_id|>和<|eot_id|>。所以「對話」和「工具」都是 prompt 的一部分,不是模型另外收到的東西。 - 工具描述放在 system message。 What are Tools? 頁說:LLM 自己不能呼叫工具;我們把工具的名稱、做什麼、參數與型別、輸出寫成文字放進 system prompt,模型只是「產生一段看起來像呼叫的文字」,真正執行的是外面的程式。頁面的 calculator 範例就是一行:
Tool Name: calculator, Description: Multiply two integers., Arguments: a: int, b: int, Outputs: int。 - 描述要從程式碼產生,不要手寫兩份。 同一頁的 Auto-formatting Tool sections 用
inspect讀函式的名稱、型別標註和 docstring 自動產生描述。好處不只是少打字:手寫的描述會跟程式碼漂移,模型照著過期的描述傳參數就會出錯。今天的程式更進一步,沒有型別標註或沒寫參數說明就直接拒絕註冊。 - 參數錯誤要回給模型,不是讓程式 crash。 模型產生的參數可能型別錯、少欄位、多欄位。執行前要驗證,錯了就把一段「哪裡錯、應該是什麼」的訊息當成 observation 回給模型,讓它下一輪修正(Day 73 會看到效果)。
- MCP 是「工具描述」的標準格式。 頁面最後一節說 MCP 讓工具定義可以跨 framework 共用。今天產生的
to_schema()刻意輸出跟 MCPtools/list一樣的形狀(name、description、inputSchema),Day 78 會直接把它拿去用。
實作
在 p08/ 建立 tools.py:
"""Day 72:從 Python 函式自動產生工具描述(給 LLM 看的文字 + JSON Schema),並在執行前驗證參數。"""
import inspect
PY_TO_JSON = {str: "string", int: "integer", float: "number", bool: "boolean"}
class ToolError(Exception):
"""參數不合法:要回給模型讓它自己修正,不是讓程式 crash。"""
class Tool:
def __init__(self, func):
self.func = func
self.name = func.__name__
doc = inspect.getdoc(func) or ""
self.description = doc.split("\n\nArgs:")[0].strip()
arg_docs = {}
if "Args:" in doc:
for line in doc.split("Args:")[1].strip().splitlines():
key, _, text = line.strip().partition(":")
arg_docs[key.strip()] = text.strip()
sig = inspect.signature(func)
self.params = {}
self.required = []
for p in sig.parameters.values():
if p.annotation not in PY_TO_JSON:
raise TypeError(f"{self.name}.{p.name} 缺少支援的型別標註")
if p.name not in arg_docs:
raise TypeError(f"{self.name}.{p.name} 在 docstring 的 Args: 裡沒有說明")
self.params[p.name] = {"type": PY_TO_JSON[p.annotation], "description": arg_docs[p.name]}
if p.default is inspect.Parameter.empty:
self.required.append(p.name)
self.output = PY_TO_JSON.get(sig.return_annotation, "string")
def to_prompt(self):
args = ", ".join(f"{k}: {v['type']}" for k, v in self.params.items())
return f"Tool Name: {self.name}, Description: {self.description}, Arguments: {args}, Outputs: {self.output}"
def to_schema(self):
return {
"name": self.name,
"description": self.description,
"inputSchema": {"type": "object", "properties": self.params,
"required": self.required, "additionalProperties": False},
}
def validate(self, args):
if not isinstance(args, dict):
raise ToolError(f"{self.name}: arguments 必須是 object,收到 {type(args).__name__}")
unknown = set(args) - set(self.params)
if unknown:
raise ToolError(f"{self.name}: 不認得的參數 {sorted(unknown)}")
missing = [k for k in self.required if k not in args]
if missing:
raise ToolError(f"{self.name}: 缺少必填參數 {missing}")
for k, v in args.items():
want = self.params[k]["type"]
ok = {"string": isinstance(v, str),
"integer": isinstance(v, int) and not isinstance(v, bool),
"number": isinstance(v, (int, float)) and not isinstance(v, bool),
"boolean": isinstance(v, bool)}[want]
if not ok:
raise ToolError(f"{self.name}: 參數 {k} 應為 {want},收到 {v!r}")
def __call__(self, **args):
self.validate(args)
return self.func(**args)
def tool(func):
return Tool(func)
@tool
def calculator(a: int, b: int) -> int:
"""Multiply two integers.
Args:
a: The first integer.
b: The second integer.
"""
return a * b
@tool
def get_weather(location: str, unit: str = "celsius") -> str:
"""Get the current weather for a city.
Args:
location: City name, e.g. "Taipei".
unit: "celsius" or "fahrenheit".
"""
table = {"Taipei": 27, "London": 12, "New York": 15}
if location not in table:
return f"ERROR: unknown city {location!r}; known cities: {sorted(table)}"
c = table[location]
return f"{location}: {c} C" if unit == "celsius" else f"{location}: {c * 9 / 5 + 32:.0f} F"
if __name__ == "__main__":
import json
for t in (calculator, get_weather):
print(t.to_prompt())
print(json.dumps(get_weather.to_schema(), ensure_ascii=False))
print(calculator(a=6, b=7))
for bad in ({"a": 6}, {"a": 6, "b": "7"}, {"a": 6, "b": 7, "c": 1}, {"a": True, "b": 7}):
try:
calculator(**bad)
except ToolError as e:
print("ToolError:", e)
try:
@tool
def no_doc(x: int) -> int:
return x
except TypeError as e:
print("TypeError:", e)
執行 python tools.py,預期:
Tool Name: calculator, Description: Multiply two integers., Arguments: a: integer, b: integer, Outputs: integer
Tool Name: get_weather, Description: Get the current weather for a city., Arguments: location: string, unit: string, Outputs: string
{"name": "get_weather", "description": "Get the current weather for a city.", "inputSchema": {"type": "object", "properties": {"location": {"type": "string", "description": "City name, e.g. \"Taipei\"."}, "unit": {"type": "string", "description": "\"celsius\" or \"fahrenheit\"."}}, "required": ["location"], "additionalProperties": false}}
42
ToolError: calculator: 缺少必填參數 ['b']
ToolError: calculator: 參數 b 應為 integer,收到 '7'
ToolError: calculator: 不認得的參數 ['c']
ToolError: calculator: 參數 a 應為 integer,收到 True
TypeError: no_doc.x 在 docstring 的 Args: 裡沒有說明
注意第四個錯誤:Python 的 bool 是 int 的子類別,isinstance(True, int) 是 True,不特別排除的話 a=True 會被當成 1 通過驗證。
最後做一個小改動:把 get_weather 的 unit 參數改成只能是 "celsius" 或 "fahrenheit"(在 to_schema() 加上 JSON Schema 的 enum,在 validate() 檢查),讓模型傳 "kelvin" 時拿到明確的錯誤訊息。這就是 Anthropic 說的 poka-yoke。
過關標準
- 能回答:模型「呼叫工具」時實際上輸出了什麼?誰負責把它變成真的函式呼叫?
- 能回答:為什麼參數錯誤要變成 observation 回給模型,而不是 raise 讓程式停下來?
- 產出:
tools.py跑出上面的輸出,加上unit的 enum 檢查,並附一次傳"kelvin"的錯誤訊息
Day 73 — 手寫 Thought → Action → Observation 迴圈與終止條件
今天要回答的問題
一個 agent 的迴圈每一輪做哪三件事?為什麼要有 stop sequence?模型卡住一直做同一件事時,迴圈怎麼知道要停?
主教材(Core)
- Hugging Face Agents Course — Unit 1 Understanding AI Agents through the Thought-Action-Observation Cycle(The Core Components、The Thought-Action-Observation Cycle、Alfred, the weather Agent 三節),預估 10 分鐘
- Hugging Face Agents Course — Unit 1 Thought: Internal Reasoning and the ReAct Approach(ReAct: Reasoning + Acting、Comparison: ReAct vs. CoT 兩節)、Actions(Types of Agent Actions、The Stop and Parse Approach 兩節)、Observe(How Are the Results Appended? 一節),三頁合計預估 25 分鐘
- Hugging Face Agents Course — Unit 1 Dummy Agent Library(Dummy Agent 一節:system prompt 的格式與
stop=["Observation:"]),預估 15 分鐘 - 實作,預估 60 分鐘
搭配(Companion,選讀)
- Hugging Face Agents Course — Unit 1 What are LLMs?:如果 Phase 03 的 next-token prediction 已經忘了,用這頁快速複習;預估 10 分鐘
讀的時候抓這幾個重點
- 這部分已在 Backend Day 89 講過:Observe → Reason → Act 的迭代機制、Policy 的兩層(模型判斷+系統硬上限)、最大迭代次數、重複偵測、成本預算。今天的新角度是:照 HF 課程的 Dummy Agent 格式真的寫一個迴圈,看到 stop sequence 和重複偵測在程式碼裡長什麼樣。
- Thought、Action、Observation 各由誰產生。 Thought 和 Action 是模型產生的文字;Observation 是外面的程式執行工具之後塞回 prompt 的結果。Observe 頁的三個步驟:解析 action 找出要呼叫的函式與參數 → 執行 → 把結果附加在 prompt 尾端當作 observation。迴圈每一輪,prompt 就變長一段。
- Stop and Parse:模型寫完 action 就要停。 Actions 頁說,模型用預先定義的格式(JSON 或程式碼)寫出 action,寫完就停止生成,再由外部 parser 讀出工具和參數。Dummy Agent Library 頁示範了不停會怎樣:模型自己編了一段 Observation,等於幻想出工具的回傳值。解法是呼叫模型時加
stop=["Observation:"],讓它在寫出Observation:之前就停下。 - ReAct 是 prompting 技巧,reasoning model 是訓練出來的。 Thought 頁把 ReAct 定義成「推理和行動交錯」:想一步、做一步、看結果再想。它也提到 DeepSeek R1、OpenAI o1 這類模型被訓練成先用
<think>…</think>想完再回答,這是訓練層級的做法,跟 ReAct 這種 prompt 格式是兩回事。 - 終止條件要寫在迴圈外面。 模型說「Final Answer」是正常出口;另外至少還要兩個系統層出口:最大步數,以及「同一個呼叫重複太多次」的重複偵測。今天的情境 3 會看到:模型一直用同一個錯的參數查天氣,沒有重複偵測的話它會一路跑到步數上限。
實作
在 p08/ 建立 react_agent.py(會 import Day 72 的 tools.py):
"""Day 73:手寫 Thought → Action → Observation 迴圈。
LLM 用 ScriptedLLM 代替:照順序吐出事先寫好的回應,讓迴圈本身的行為可重現。
它模擬了 stop sequence:生成內容遇到 stop 字串就截斷(跟 Dummy Agent Library 的 stop=["Observation:"] 同一招)。
"""
import json
import re
from tools import ToolError, calculator, get_weather
FENCE = "`" * 3 # Markdown 的 code fence;用拼的,免得這個檔案貼進 Markdown 時跟外層 fence 衝突
SYSTEM = """Answer the question. You have access to these tools:
{tools}
Use this format:
Thought: what to do next
Action:
{fence}
{{"action": "<tool name>", "action_input": {{...}}}}
{fence}
Observation: the result of the action
... (Thought/Action/Observation can repeat)
Thought: I now know the final answer
Final Answer: the answer"""
class ScriptedLLM:
def __init__(self, responses):
self.responses = list(responses)
self.calls = 0
def generate(self, prompt, stop=None):
self.calls += 1
text = self.responses.pop(0) if self.responses else "Thought: I am stuck."
for s in stop or []:
if s in text:
text = text[: text.index(s)]
return text
ACTION_RE = re.compile(r"Action:\s*`{3}(?:json)?\s*(\{.*?\})\s*`{3}", re.S)
def run_agent(llm, question, tools, max_steps=6, use_stop=True, repeat_limit=2):
registry = {t.name: t for t in tools}
prompt = SYSTEM.format(fence=FENCE, tools="\n".join(t.to_prompt() for t in tools)) + f"\nQuestion: {question}\n"
seen = []
for step in range(1, max_steps + 1):
out = llm.generate(prompt, stop=["Observation:"] if use_stop else None)
if "Final Answer:" in out:
return {"status": "done", "steps": step, "answer": out.split("Final Answer:")[1].strip(),
"llm_calls": llm.calls}
m = ACTION_RE.search(out)
if not m:
obs = "ERROR: no Action or Final Answer found; follow the format."
else:
try:
call = json.loads(m.group(1))
key = json.dumps(call, sort_keys=True)
seen.append(key)
if seen.count(key) > repeat_limit:
return {"status": "stopped: repeated action", "steps": step, "answer": None,
"llm_calls": llm.calls, "repeated": call}
tool = registry.get(call.get("action"))
if tool is None:
obs = f"ERROR: unknown tool {call.get('action')!r}; available: {sorted(registry)}"
else:
obs = str(tool(**call.get("action_input", {})))
except (json.JSONDecodeError, ToolError) as e:
obs = f"ERROR: {e}"
prompt += out + f"Observation: {obs}\n"
print(f" step {step}: {obs}")
return {"status": "stopped: max_steps", "steps": max_steps, "answer": None, "llm_calls": llm.calls}
def act(name, **args):
blob = json.dumps({"action": name, "action_input": args})
return f"Thought: call {name}\nAction:\n{FENCE}\n{blob}\n{FENCE}\n"
if __name__ == "__main__":
tools = [calculator, get_weather]
print("[1] 正常:先查天氣、算一個數,再回答")
llm = ScriptedLLM([
act("get_weather", location="Taipei"),
act("calculator", a=27, b=2),
"Thought: I now know the final answer\nFinal Answer: Taipei is 27 C; doubled is 54.",
])
print(" ", run_agent(llm, "Weather in Taipei, and double the temperature?", tools))
print("[2] 參數錯誤 → 錯誤訊息回給模型 → 模型修正")
llm = ScriptedLLM([
act("calculator", a=27, b="2"),
act("calculator", a=27, b=2),
"Final Answer: 54",
])
print(" ", run_agent(llm, "27 * 2?", tools))
print("[3] 模型一直重複同一個呼叫 → 重複偵測提早停")
llm = ScriptedLLM([act("get_weather", location="Paris")] * 10)
print(" ", run_agent(llm, "Weather in Paris?", tools))
print("[4] 沒有 stop sequence:模型自己編了 Observation,還直接給答案")
hallucinated = act("get_weather", location="London") + \
"Observation: London: 30 C\nThought: done\nFinal Answer: London is 30 C."
print(" with stop :", run_agent(ScriptedLLM([hallucinated, "Final Answer: London is 12 C."]),
"Weather in London?", tools))
print(" without stop:", run_agent(ScriptedLLM([hallucinated]), "Weather in London?", tools, use_stop=False))
執行 python react_agent.py,預期:
[1] 正常:先查天氣、算一個數,再回答
step 1: Taipei: 27 C
step 2: 54
{'status': 'done', 'steps': 3, 'answer': 'Taipei is 27 C; doubled is 54.', 'llm_calls': 3}
[2] 參數錯誤 → 錯誤訊息回給模型 → 模型修正
step 1: ERROR: calculator: 參數 b 應為 integer,收到 '2'
step 2: 54
{'status': 'done', 'steps': 3, 'answer': '54', 'llm_calls': 3}
[3] 模型一直重複同一個呼叫 → 重複偵測提早停
step 1: ERROR: unknown city 'Paris'; known cities: ['London', 'New York', 'Taipei']
step 2: ERROR: unknown city 'Paris'; known cities: ['London', 'New York', 'Taipei']
{'status': 'stopped: repeated action', 'steps': 3, 'answer': None, 'llm_calls': 3, 'repeated': {'action': 'get_weather', 'action_input': {'location': 'Paris'}}}
[4] 沒有 stop sequence:模型自己編了 Observation,還直接給答案
step 1: London: 12 C
with stop : {'status': 'done', 'steps': 2, 'answer': 'London is 12 C.', 'llm_calls': 2}
without stop: {'status': 'done', 'steps': 1, 'answer': 'London is 30 C.', 'llm_calls': 1}
情境 4 是今天最重要的一行:同一段模型輸出,有 stop sequence 時工具真的被呼叫、答案是 12 C;沒有 stop sequence 時工具從來沒被呼叫,答案是模型自己編的 30 C,而且 status 一樣是 done——光看 status 完全看不出來。
接著做兩個實驗,把結果記在 day73-notes.md:
- 把
repeat_limit改成100,重跑情境 3,記下 status 和 llm_calls(應該會跑到max_steps才停)。說明兩種停法對成本的差別。 - 現在的重複偵測只認「完全一樣」的呼叫。寫一個情境讓它失效(提示:模型每次換一個不存在的城市名),再寫出你會怎麼改(例如「連續 N 輪 observation 都是 ERROR 就停」),並實作它。
過關標準
- 能回答:Thought、Action、Observation 三者各由誰產生?哪一個絕對不能由模型產生?
- 能回答:情境 4 沒有 stop sequence 時,為什麼 status 還是
done?在真實系統裡要靠什麼才能發現這種錯? - 產出:
react_agent.py跑出上面的輸出;day73-notes.md含兩個實驗的結果,以及你實作的第二種終止條件與它擋下的情境
Day 74 — 五種 workflow:大部分問題不需要 agent
今天要回答的問題
Anthropic 列的五種 workflow 各適合什麼情況?同一個需求,用 workflow 和用 agent,控制權、LLM 呼叫次數、可以插檢查點的位置有什麼不同?
主教材(Core)
- Anthropic — Building effective agents(Building blocks, workflows, and agents 一節的全部小節:Building block: The augmented LLM、Workflow: Prompt chaining、Workflow: Routing、Workflow: Parallelization、Workflow: Orchestrator-workers、Workflow: Evaluator-optimizer、Agents;以及 Combining and customizing these patterns),預估 40 分鐘
- 實作,預估 60 分鐘
搭配(Companion,選讀)
- Hugging Face Agents Course — Unit 2.2 Creating agentic workflows in LlamaIndex(Creating Workflows 一節):LlamaIndex 把 workflow 寫成「step 收到 event、發出 event」,是另一種把流程寫死在程式碼裡的方式;Phase 07 用過 LlamaIndex,可以對照;預估 15 分鐘
讀的時候抓這幾個重點
- 所有 pattern 的基本單位是 augmented LLM。 文章把「LLM+retrieval+tools+memory」當成一個 building block,五種 workflow 都是用程式碼把好幾個這種 block 接起來。Phase 07 做的 RAG 就是一個 augmented LLM。
- 五種 workflow 各自的「什麼時候用」(文章原意): prompt chaining——任務能乾淨地拆成固定的子任務,用一點延遲換準確度;routing——輸入有明確的類別、分開處理比較好,而且分類本身能做得準;parallelization——子任務可以平行跑以求速度(sectioning),或需要多次嘗試、多個觀點來提高信心(voting);orchestrator-workers——子任務無法事先預測,要看輸入才知道;evaluator-optimizer——有清楚的評估標準,而且反覆修改確實能改善結果。
- orchestrator-workers 是 workflow 和 agent 的交界。 前四種的步驟和分支都寫在程式碼裡;orchestrator-workers 由一個 LLM 動態決定拆成哪些子任務,但「拆完分派、收回來合併」的骨架還是程式碼。真正的 agent 連「下一步要做什麼、什麼時候停」都交給模型。
- workflow 的好處是檢查點在你手上。 prompt chaining 可以在兩步之間加 gate(程式碼檢查中間產物,不合格就不往下送);routing 的每個分支可以用不同的 prompt、甚至不同大小的模型;voting 可以設門檻。這些都是 Day 71 說的「可預測」:你能事先知道最多會呼叫幾次 LLM。
實作
在 p08/ 建立 workflows.py,用一組規則函式當替身 LLM,實作其中四種並計算呼叫次數:
"""Day 74:Building Effective Agents 的五種 workflow,選四種用「替身 LLM」實作,數每種花幾次 LLM 呼叫。
替身 LLM 是一組確定性的規則函式。重點不是它聰不聰明,而是:
控制流程寫在誰手上(程式碼 vs 模型)、LLM 被呼叫幾次、哪裡可以插檢查點。
"""
import threading
from concurrent.futures import ThreadPoolExecutor
class CountingLLM:
def __init__(self):
self.calls = 0
self._lock = threading.Lock() # parallel 版本會從多個 thread 呼叫
def __call__(self, task, text):
with self._lock:
self.calls += 1
return RULES[task](text)
def classify(text):
t = text.lower()
if "refund" in t or "charged" in t:
return "billing"
if "error" in t or "crash" in t:
return "technical"
return "general"
def draft(text):
return f"Draft reply about: {text[:40]}"
def translate(text):
return text.replace("Draft reply", "回覆草稿")
def review(text):
# 評審:太短或沒有道歉就退回,並說明原因
if "sorry" not in text.lower():
return "REJECT: missing apology"
if len(text) < 60:
return "REJECT: too short, add next steps"
return "ACCEPT"
def improve(text_and_feedback):
text, feedback = text_and_feedback.split("||")
if "apology" in feedback:
return "Sorry for the trouble. " + text
return text + " Next step: we will email you within 24 hours."
def is_harmful(text):
return "YES" if "password" in text.lower() else "NO"
RULES = {"classify": classify, "draft": draft, "translate": translate, "review": review,
"improve": improve, "harmful": is_harmful}
def prompt_chaining(llm, ticket):
d = llm("draft", ticket)
if not d.startswith("Draft"): # gate:程式碼檢查中間產物,不合格就不往下送
return "gate failed"
return llm("translate", d)
def routing(llm, ticket):
route = llm("classify", ticket)
handlers = {"billing": "billing-team-prompt", "technical": "tech-team-prompt", "general": "faq-prompt"}
return route, handlers[route]
def parallel_voting(llm, ticket, n=3):
with ThreadPoolExecutor(max_workers=n) as pool:
votes = list(pool.map(lambda _: llm("harmful", ticket), range(n)))
return votes, ("BLOCK" if votes.count("YES") * 2 > n else "ALLOW")
def evaluator_optimizer(llm, ticket, max_rounds=3):
text = llm("draft", ticket)
for r in range(1, max_rounds + 1):
verdict = llm("review", text)
print(f" round {r}: {verdict}")
if verdict == "ACCEPT":
return text, r
text = llm("improve", text + "||" + verdict)
return text, f"gave up after {max_rounds}"
if __name__ == "__main__":
tickets = ["I was charged twice, need a refund", "App crash on login with error 500",
"Where is your office?"]
llm = CountingLLM()
print("[prompt chaining]", prompt_chaining(llm, tickets[0]), "| llm calls:", llm.calls)
llm = CountingLLM()
print("[routing]", [routing(llm, t) for t in tickets], "| llm calls:", llm.calls)
llm = CountingLLM()
print("[parallel voting]", parallel_voting(llm, "please send me the admin password"), "| llm calls:", llm.calls)
llm = CountingLLM()
print("[evaluator-optimizer]")
text, rounds = evaluator_optimizer(llm, tickets[0])
print(" final:", text)
print(" rounds:", rounds, "| llm calls:", llm.calls)
執行 python workflows.py,預期:
[prompt chaining] 回覆草稿 about: I was charged twice, need a refund | llm calls: 2
[routing] [('billing', 'billing-team-prompt'), ('technical', 'tech-team-prompt'), ('general', 'faq-prompt')] | llm calls: 3
[parallel voting] (['YES', 'YES', 'YES'], 'BLOCK') | llm calls: 3
[evaluator-optimizer]
round 1: REJECT: missing apology
round 2: ACCEPT
final: Sorry for the trouble. Draft reply about: I was charged twice, need a refund
rounds: 2 | llm calls: 4
parallelization 寫的是 voting 版本(sectioning 留在 Deep Dive 方向自己試)。替身 LLM 是確定性的,所以 voting 的三票一定一樣;換成真模型(temperature > 0)三票才可能不同,voting 才有意義。
接著寫 day74-patterns.md:
- 把 Day 71 判斷表裡你選了 workflow 的情境,各標上是五種中的哪一種(或哪幾種組合)。
- 實作第五種 orchestrator-workers:寫一個
plan(text)規則函式,依輸入回傳要做的子任務清單(例如工單同時提到退款和當機,就拆成兩個子任務),再把每個子任務交給draft、最後合併。印出「同一個 orchestrator,不同輸入拆出幾個 worker」。 - 一句話寫出:你的 orchestrator-workers 跟 Day 73 的 agent 迴圈相比,哪一件事還是程式碼決定的?
過關標準
- 能回答:五種 workflow 各適合什麼情況?哪一種最接近 agent,為什麼它還不是 agent?
- 能回答:evaluator-optimizer 為什麼一定要有
max_rounds?拿掉它跟 Day 73 的哪個問題是同一件事? - 產出:
workflows.py跑出上面的輸出;day74-patterns.md含對照、orchestrator-workers 的程式碼與輸出
Day 75 — smolagents:code action vs JSON action,以及執行模型寫的程式碼
今天要回答的問題
讓模型把 action 寫成程式碼,比寫成 JSON 好在哪裡?代價是什麼?執行模型產生的程式碼之前,最少要擋哪些東西,擋了之後又為什麼還不夠?
主教材(Core)
- Hugging Face Agents Course — Unit 2.1 Why use smolagents(Code vs. JSON Actions、Agent Types in smolagents、Model Integration in smolagents 三節),預估 10 分鐘
- Hugging Face Agents Course — Unit 2.1 Building Agents That Use Code(Why Code Agents?、How Does a Code Agent Work?、Using Python Imports Inside the Agent 三節),預估 20 分鐘
- Hugging Face Agents Course — Unit 2.1 Writing actions as code snippets or JSON blobs(How Do Tool Calling Agents Work? 一節),預估 10 分鐘
- smolagents 文件 — Secure code execution(Code agents、Local code execution??、Our local Python executor 三節,以及 Sandbox approaches 的開頭與 Comparing security approaches),預估 25 分鐘
- 實作,預估 45 分鐘
搭配(Companion,選讀)
- Hugging Face Agents Course — Unit 2.1 Tools(The
@toolDecorator、Defining a Tool as a Python Class 兩節):smolagents 的@tool跟 Day 72 自己寫的是同一個想法,一樣要求型別標註和 docstring 的Args:;預估 10 分鐘 - Hugging Face Agents Course — Unit 2.1 Multi-Agent Systems:manager agent 把子任務交給有自己 memory 的 managed agent,讓每個 agent 的 context 比較短、比較便宜;預估 15 分鐘
讀的時候抓這幾個重點
- code action 少繞幾趟模型。 JSON action 一次只能呼叫一個工具,中間結果要送回模型、模型再決定下一步。code action 可以在一段程式碼裡跑迴圈、存變數、做計算。smolagents 文件 Code agents 一節列了四個理由:composability(可以組合、重用)、object management(中間結果存在變數裡)、generality、以及訓練資料裡本來就有大量程式碼。今天的程式會量出同一個任務 JSON 要 4 輪、code 只要 1 輪。
- smolagents 有兩種 agent。
CodeAgent是主力,action 是 Python 程式碼;ToolCallingAgent用 provider 內建的 tool calling 產生 JSON({"name": ..., "arguments": ...})。tool_calling_agents 頁說 ToolCallingAgent 適合不需要變數、不需要複雜工具組合的簡單系統。 - CodeAgent 的每一步。 code_agents 頁的 How Does a Code Agent Work? 一節:system prompt 存在
SystemPromptStep、使用者問題存在TaskStep;每一步把 memory 轉成 chat messages 送給模型 → 從回應裡解析出程式碼 → 執行 → 結果記成ActionStep。這跟 Day 73 的迴圈是同一個結構,只是 action 從 JSON 換成程式碼。 - 執行模型寫的程式碼,本機沒有真正安全的做法。 Secure code execution 頁列了四種風險來源:模型單純犯錯、supply chain、prompt injection(agent 瀏覽到惡意網頁)、公開的 agent 被濫用。smolagents 的
LocalPythonExecutor不用原生 Python 直譯器,而是逐個 AST 節點執行:import 預設全擋(白名單才放行)、子模組也要明確授權(random._os這種路徑會被擋)、操作次數有上限、沒定義的操作直接報錯。但頁面明講:沒有任何本機 Python sandbox 是完全安全的,要真正隔離就用 E2B、Modal、Docker 這類遠端執行。 - 「只把程式碼丟進 sandbox」和「整個 agent 都在 sandbox 裡」是兩種做法。 前者設定簡單、API key 不用進 sandbox,但不支援 multi-agent;後者隔離最完整,但可能要把 API key 傳進 sandbox。這是一個權限設計的取捨,Phase 09 談 security 時會回來。
實作
在 p08/ 建立 code_actions.py(會 import Day 72 的 tools.py):
"""Day 75:同一個任務,JSON action 要幾輪、code action 要幾輪;以及 code action 為什麼一定要有執行前檢查。
guard() 是教學用的靜態檢查,不是 sandbox——smolagents 文件自己都寫了:沒有任何本機 Python sandbox 是完全安全的。
"""
import ast
from tools import get_weather
CITIES = ["Taipei", "London", "New York"]
# ---- 1. JSON action:一次只能呼叫一個工具,中間結果要繞回模型 ----
json_turns = [{"action": "get_weather", "action_input": {"location": c}} for c in CITIES]
json_turns.append({"final_answer": "computed by the model from 3 observations"})
# ---- 2. Code action:一段程式碼就能呼叫三次、存變數、做計算 ----
CODE_ACTION = """
temps = {}
for city in ["Taipei", "London", "New York"]:
text = get_weather(location=city)
temps[city] = int(text.split(": ")[1].split(" ")[0])
hottest = max(temps, key=temps.get)
final_answer = f"hottest: {hottest} ({temps[hottest]} C), average: {sum(temps.values()) / len(temps):.1f} C"
"""
ALLOWED_IMPORTS = {"math", "statistics"}
FORBIDDEN_NAMES = {"eval", "exec", "open", "compile", "__import__", "globals", "getattr", "setattr"}
def guard(code):
"""回傳違規清單;空清單才允許執行。"""
problems = []
for node in ast.walk(ast.parse(code)):
if isinstance(node, (ast.Import, ast.ImportFrom)):
names = [a.name for a in node.names] if isinstance(node, ast.Import) else [node.module]
for n in names:
if n.split(".")[0] not in ALLOWED_IMPORTS:
problems.append(f"import {n} not allowed")
elif isinstance(node, ast.Attribute) and node.attr.startswith("_"):
problems.append(f"private attribute .{node.attr}")
elif isinstance(node, ast.Name) and node.id in FORBIDDEN_NAMES:
problems.append(f"name {node.id} not allowed")
elif isinstance(node, ast.While) and isinstance(node.test, ast.Constant) and node.test.value:
problems.append("while True loop")
return problems
def run_code_action(code, tools):
problems = guard(code)
if problems:
return {"rejected": problems}
env = {"__builtins__": {"int": int, "max": max, "sum": sum, "len": len, "range": range}}
env.update(tools)
exec(code, env)
return {"final_answer": env.get("final_answer")}
if __name__ == "__main__":
print("JSON action turns (each = one LLM call):", len(json_turns))
print("code action turns: 1 ->", run_code_action(CODE_ACTION, {"get_weather": get_weather}))
attacks = {
"import os": "import os\nos.system('echo pwned')",
"random._os": "import random\nrandom._os.system('echo pwned')",
"dunder escape": "x = ().__class__.__base__.__subclasses__()",
"eval": "eval('1+1')",
"infinite loop": "while True:\n pass",
"allowed math": "import math\nfinal_answer = math.sqrt(16)",
}
for label, code in attacks.items():
print(f" {label:14s} -> {guard(code) or 'OK'}")
執行 python code_actions.py,預期:
JSON action turns (each = one LLM call): 4
code action turns: 1 -> {'final_answer': 'hottest: Taipei (27 C), average: 18.0 C'}
import os -> ['import os not allowed']
random._os -> ['import random not allowed', 'private attribute ._os']
dunder escape -> ['private attribute .__subclasses__', 'private attribute .__base__', 'private attribute .__class__']
eval -> ['name eval not allowed']
infinite loop -> ['while True loop']
allowed math -> OK
接著做「攻破自己的 guard」:寫出至少兩段能通過 guard()、但仍然有害的程式碼(提示:while 1 == 1:;或是一個沒有用 while 的超大運算,例如 x = 10 10 8),在 day75-notes.md 記下每一段為什麼沒被擋、靜態檢查為什麼原理上就擋不完。這就是 smolagents 文件說「本機沒有完全安全的 sandbox」的親身版本,也是它要在執行期計算操作次數的原因。只用 guard() 檢查、不要真的 exec 這些程式碼。
(選做,教材作者未實跑)如果想看真的 smolagents,Building Agents That Use Code 頁的第一個範例是下面三行,需要 pip install smolagents 和 Hugging Face token(InferenceClientModel 走 HF 的 serverless inference):
from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel
agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=InferenceClientModel())
agent.run("Search for the best music recommendations for a party at the Wayne's mansion.")
跑的話,對照 log 裡每一步模型寫出的程式碼,數一數它呼叫了幾次搜尋工具、花了幾步。
過關標準
- 能回答:同一個「比較三個城市氣溫」的任務,為什麼 JSON action 要 4 次 LLM 呼叫、code action 只要 1 次?code action 多承擔了什麼風險?
- 能回答:
LocalPythonExecutor做了哪幾種防護?為什麼文件還是說本機執行不完全安全? - 產出:
code_actions.py跑出上面的輸出;day75-notes.md含至少兩段能繞過guard()的程式碼與原因
Day 76 — LangGraph:State → Node → Edge → Execution
今天要回答的問題
LangGraph 把一個 agent/workflow 拆成哪幾個元件?用 graph 寫和用 if-else 寫,多得到了什麼?它在 Day 71 那條「控制 vs 自由」的光譜上站在哪一邊?
主教材(Core)
- Hugging Face Agents Course — Unit 2.3 What is LangGraph?(When should I use LangGraph?(含 Control vs freedom)、How does LangGraph work?、How is it different from regular python? 三節),預估 15 分鐘
- Hugging Face Agents Course — Unit 2.3 Building Blocks of LangGraph(State、Nodes、Edges、StateGraph 四節),預估 15 分鐘
- Hugging Face Agents Course — Unit 2.3 Building Your First LangGraph(Step 1 到 Step 5、Key Takeaways),預估 25 分鐘
- 實作,預估 55 分鐘
搭配(Companion,選讀)
- LangGraph 文件 — Graph API(State 底下的 Reducers 一節、Edges 底下的 Conditional edges 一節):node 回傳的更新是透過 reducer 合併進 state 的;沒指定 reducer 的 key,預設就是直接覆蓋。今天自己寫的版本只做了「直接覆蓋」;預估 15 分鐘
- LangGraph 文件 — Learn:官方教學總覽(Custom RAG Agent、Custom SQL Agent、multi-agent 的 subagents/handoffs/router)。想用 LangGraph 做 Project 3 的話從這裡挑
讀的時候抓這幾個重點
- LangGraph 站在「控制」那一端。 What is LangGraph? 頁的 Control vs freedom 一節:freedom 讓模型能創意地處理意外情況,control 讓行為可預測、留在護欄內;smolagents 的 code agent 偏 freedom,LangGraph 偏 control。它適合「一連串步驟要照特定方式編排、每個路口要做決定」的應用。這跟 Day 74 的 workflow 是同一個方向。
- 三個元件:State、Node、Edge。 State 是使用者自己定義的資料結構(頁面用
TypedDict),在 node 之間傳遞;Node 是一個 Python 函式,收到 state、回傳要更新的部分;Edge 決定下一個 node,add_edge是固定路線,add_conditional_edges用一個 routing 函式的回傳值選路。START/END標出入口和出口,compile()之後才能invoke()。 - 用 graph 而不用 if-else,多的是框架層的東西。 頁面直說:同樣的流程用 if-else 也寫得出來,LangGraph 多給的是 state 管理、視覺化、trace,以及內建的 human-in-the-loop。也就是說,graph 的價值在「暫停、存檔、恢復、觀察」這些事(Day 77),不在流程本身。
- email 分類圖的形狀。 First Graph 頁的
EmailState有email、is_spam、spam_reason、email_category、email_draft、messages;node 是read_email → classify_email,接著route_email回傳"spam"或"legitimate",分別走handle_spam → END或draft_response → notify_mr_hugg → END。今天的程式照著這個形狀重建。(教材作者查證時注意到,頁面的 Langfuse 範例傳入的 key 寫成draft_response,跟EmailState定義的email_draft不一致,抄的時候要留意。)
實作
在 p08/ 建立 minigraph.py。自己寫一個 60 行的 StateGraph,介面刻意模仿 LangGraph,再重建 email 分類圖:
"""Day 76:自己寫一個 60 行的 StateGraph,重現 HF Agents Course 的 email 分類圖。
介面刻意模仿 LangGraph(add_node / add_edge / add_conditional_edges / START / END / compile / invoke),
讓你讀 LangGraph 時知道每個 API 背後在做什麼。node 回傳「部分 state」,由 graph 合併。
"""
START, END = "__start__", "__end__"
class StateGraph:
def __init__(self):
self.nodes, self.edges, self.cond = {}, {}, {}
def add_node(self, name, fn):
self.nodes[name] = fn
def add_edge(self, src, dst):
self.edges[src] = dst
def add_conditional_edges(self, src, router, mapping):
self.cond[src] = (router, mapping)
def next_node(self, current, state):
if current in self.cond:
router, mapping = self.cond[current]
return mapping[router(state)]
return self.edges[current]
def compile(self, max_steps=20):
for src, dst in self.edges.items():
for n in (src, dst):
if n not in (START, END) and n not in self.nodes:
raise ValueError(f"edge refers to unknown node {n!r}")
return Compiled(self, max_steps)
class Compiled:
def __init__(self, graph, max_steps):
self.g, self.max_steps = graph, max_steps
def invoke(self, state):
state, trace = dict(state), []
node = self.g.next_node(START, state)
while node != END:
if len(trace) >= self.max_steps:
raise RuntimeError(f"max_steps {self.max_steps} exceeded; trace={trace}")
state.update(self.g.nodes[node](state) or {})
trace.append(node)
node = self.g.next_node(node, state)
state["trace"] = trace
return state
# ---- 重現 email 分類圖(LLM 用規則代替)----
def read_email(state):
return {}
def classify_email(state):
body = state["email"]["body"].lower()
spam = "lottery" in body or "crypto" in body
return {"is_spam": spam, "spam_reason": "lottery/crypto keywords" if spam else None,
"email_category": None if spam else "inquiry"}
def handle_spam(state):
return {}
def draft_response(state):
return {"email_draft": f"Dear {state['email']['sender']}, thank you for your email."}
def notify_mr_hugg(state):
return {}
def route_email(state):
return "spam" if state["is_spam"] else "legitimate"
def build_email_graph():
g = StateGraph()
for name, fn in [("read_email", read_email), ("classify_email", classify_email),
("handle_spam", handle_spam), ("draft_response", draft_response),
("notify_mr_hugg", notify_mr_hugg)]:
g.add_node(name, fn)
g.add_edge(START, "read_email")
g.add_edge("read_email", "classify_email")
g.add_conditional_edges("classify_email", route_email,
{"spam": "handle_spam", "legitimate": "draft_response"})
g.add_edge("handle_spam", END)
g.add_edge("draft_response", "notify_mr_hugg")
g.add_edge("notify_mr_hugg", END)
return g.compile()
if __name__ == "__main__":
app = build_email_graph()
legit = {"sender": "Joker", "subject": "Venue", "body": "Can we book the hall on Friday?"}
spam = {"sender": "Crypto Bro", "subject": "WIN", "body": "You won the crypto lottery!"}
for email in (legit, spam):
out = app.invoke({"email": email})
print(out["trace"], "| draft:", out.get("email_draft"), "| spam_reason:", out["spam_reason"])
# 有環的圖:沒有出口條件就靠 max_steps 擋下來
g = StateGraph()
g.add_node("retry", lambda s: {"n": s["n"] + 1})
g.add_edge(START, "retry")
g.add_conditional_edges("retry", lambda s: "again", {"again": "retry", "done": END})
try:
g.compile(max_steps=5).invoke({"n": 0})
except RuntimeError as e:
print("RuntimeError:", e)
執行 python minigraph.py,預期:
['read_email', 'classify_email', 'draft_response', 'notify_mr_hugg'] | draft: Dear Joker, thank you for your email. | spam_reason: None
['read_email', 'classify_email', 'handle_spam'] | draft: None | spam_reason: lottery/crypto keywords
RuntimeError: max_steps 5 exceeded; trace=['retry', 'retry', 'retry', 'retry', 'retry']
LangGraph 也有同樣的保護:graph 有環時,超過 recursion limit 就會報錯。接著做兩件事,記在 day76-notes.md:
- 把 Day 73 的迴圈改寫成 graph。 畫出(或用文字寫出)兩個 node:
call_model、call_tool,一條 conditional edge:模型輸出 Final Answer 就到END,否則到call_tool;call_tool再接回call_model。用minigraph.py實作出來,跑通 Day 73 的情境 1。寫一句話:agent 迴圈在 graph 裡就是哪一條邊? - reducer。 現在
state.update()是直接覆蓋。在 email 圖裡讓classify_email和draft_response都回傳{"messages": [...]},觀察第二個會蓋掉第一個;再改Compiled.invoke,讓messages這個 key 改成「附加」而不是覆蓋。對照 Graph API 頁的 Reducers 一節。
(選做,教材作者未實跑)同一張圖用真的 LangGraph 寫,需要 pip install langgraph。照 First Graph 頁 Step 4 的建圖方式,把上面的 node 函式直接搬過去:
from typing import Optional, TypedDict
from langgraph.graph import END, START, StateGraph
class EmailState(TypedDict):
email: dict
is_spam: Optional[bool]
spam_reason: Optional[str]
email_category: Optional[str]
email_draft: Optional[str]
email_graph = StateGraph(EmailState)
email_graph.add_node("read_email", read_email)
email_graph.add_node("classify_email", classify_email)
email_graph.add_node("handle_spam", handle_spam)
email_graph.add_node("draft_response", draft_response)
email_graph.add_node("notify_mr_hugg", notify_mr_hugg)
email_graph.add_edge(START, "read_email")
email_graph.add_edge("read_email", "classify_email")
email_graph.add_conditional_edges("classify_email", route_email,
{"spam": "handle_spam", "legitimate": "draft_response"})
email_graph.add_edge("handle_spam", END)
email_graph.add_edge("draft_response", "notify_mr_hugg")
email_graph.add_edge("notify_mr_hugg", END)
compiled_graph = email_graph.compile()
print(compiled_graph.invoke({"email": {"sender": "Joker", "subject": "Venue",
"body": "Can we book the hall on Friday?"}}))
過關標準
- 能回答:State、Node、Edge 各是什麼?conditional edge 的 routing 函式回傳的是什麼?
- 能回答:同一個流程用 if-else 也寫得出來,那 LangGraph 多給了什麼?為什麼這些東西對 agent 特別重要?
- 產出:
minigraph.py跑出上面的輸出;day76-notes.md含「Day 73 迴圈改寫成 graph」的程式碼與輸出,以及 reducer 修改前後的差別
Day 77 — Checkpoint、interrupt 與 crash 後從斷點繼續
今天要回答的問題
agent 跑到一半要等人核准,或是 process 被砍掉,要怎麼從原本的位置繼續、而不是從頭再跑一次?恢復時哪些程式碼會被重跑一次?
主教材(Core)
- LangGraph 文件 — Persistence(Quickstart、Checkpointer vs. store 兩節,以及 Troubleshooting 的
MemorySaverdoes not persist between restarts),預估 15 分鐘 - LangGraph 文件 — Interrupts(Pause using
interrupt、Resuming interrupts、Common patterns 底下的 Approve or reject、Rules of interrupts 四節),預估 30 分鐘 - 實作,預估 65 分鐘
搭配(Companion,選讀)
- LangGraph 文件 — Graph API 的 Re-execution and idempotency 一節:node 可能被重跑,副作用要設計成可以安全重跑;預估 10 分鐘
讀的時候抓這幾個重點
- 這部分已在 Backend Day 90 講過:State/Checkpoint/Recovery/Verification/Failure Isolation 五個環節,以及「工具呼叫送出之後、結果寫入 state 之前 crash」為什麼最難處理。今天的新角度是:LangGraph 把 checkpoint 和 human-in-the-loop 做成同一套機制,以及這套機制「恢復時整個 node 重跑」這條規則帶來的陷阱。
- checkpoint 以 thread 為單位。 Persistence 頁說:checkpointer 保存單一 thread 的 graph state,thread 由 invoke 時 config 裡的
configurable.thread_id指定;跨 thread 共用的資料放 store。InMemorySaver(從langgraph.checkpoint.memoryimport)只存在記憶體,process 重啟就沒了,正式環境要用PostgresSaver這類持久化的 saver。今天的程式用檔案模擬「持久化」。 - interrupt 就是「存檔+暫停」。 Interrupts 頁說:在 node 裡呼叫
interrupt(payload)會暫停 graph,payload 交給呼叫端(例如顯示給人看);之後用同一個thread_id加上Command(resume=值)再 invoke,那個值就變成interrupt()的回傳值。所以 interrupt 一定要有 checkpointer 和 thread_id,否則恢復時不知道要從哪裡接。 - 恢復時,整個 node 從頭重跑。 Rules of interrupts 一節最重要的一條:恢復後不是從
interrupt()那一行繼續,而是那個 node 從第一行重新執行,所以interrupt()之前的副作用會再發生一次,必須是冪等的;頁面建議把副作用放在 interrupt 之後,或拆成獨立的 node。同一節也說不要把interrupt包在 try/except 裡、不要在同一個 node 裡調換多個 interrupt 的順序。今天的程式會量出這個「多跑一次」。 - checkpoint 只能保證「已完成的 node 不重跑」。 checkpoint 是在 node 完成之後才寫的;如果 process 死在 node 執行的中間(例如退款 API 已經呼叫出去、還沒回傳),恢復時那個 node 會整個重跑。這時候能保護你的不是 checkpoint,而是工具本身的冪等設計(idempotency key)——也就是 Backend Day 90 說的 Verification 加上 Idempotency 判斷。
實作
在 p08/ 建立 checkpoint_graph.py(會 import Day 76 的 minigraph.py):
"""Day 77:幫 minigraph 加上 checkpointer、interrupt(human-in-the-loop)與 crash 後從斷點繼續。
行為刻意對齊 LangGraph Interrupts 頁的規則:
- 每跑完一個 node 就把 (state, 下一個 node) 存成 checkpoint,用 thread_id 區分
- interrupt() 讓 graph 暫停並把 payload 交給呼叫端;用 Resume(value) 再 invoke 同一個 thread 繼續
- 恢復時「整個 node 從頭重跑」,所以 interrupt 之前的副作用會再執行一次
"""
import json
from pathlib import Path
from minigraph import END, START, StateGraph
class Interrupted(Exception):
def __init__(self, payload):
self.payload = payload
class Resume:
def __init__(self, value):
self.value = value
_resume_value = [] # 目前這次 invoke 可用的 resume 值(最多一個)
def interrupt(payload):
if _resume_value:
return _resume_value.pop()
raise Interrupted(payload)
class FileCheckpointer:
def __init__(self, folder="checkpoints"):
self.folder = Path(folder)
self.folder.mkdir(exist_ok=True)
def load(self, thread_id):
p = self.folder / f"{thread_id}.json"
return json.loads(p.read_text()) if p.exists() else None
def save(self, thread_id, cp):
(self.folder / f"{thread_id}.json").write_text(json.dumps(cp, ensure_ascii=False))
def invoke(graph, inp, thread_id, saver):
cp = saver.load(thread_id)
if isinstance(inp, Resume):
if not cp or not cp.get("interrupt"):
raise RuntimeError("nothing to resume")
_resume_value[:] = [inp.value]
elif cp and cp["next"] != END:
pass # crash 後再呼叫:忽略新輸入,從 checkpoint 繼續
else:
cp = {"state": dict(inp), "next": graph.next_node(START, inp), "trace": []}
state, node, trace = cp["state"], cp["next"], cp["trace"]
while node != END:
try:
update = graph.nodes[node](state) or {}
except Interrupted as e:
saver.save(thread_id, {"state": state, "next": node, "trace": trace, "interrupt": e.payload})
return {"__interrupt__": e.payload, "trace": trace}
state.update(update)
trace.append(node)
node = graph.next_node(node, state)
saver.save(thread_id, {"state": state, "next": node, "trace": trace})
_resume_value.clear()
return {**state, "trace": trace}
# ---- 退款流程:查訂單 → 人工核准 → 退款 ----
SIDE_EFFECTS = {"reviewer_pinged": 0, "refund_api_calls": 0}
CRASH_ONCE = {"armed": True}
def lookup_order(state):
return {"amount": 1200, "customer": "c-42"}
def approve(state):
SIDE_EFFECTS["reviewer_pinged"] += 1 # interrupt 之前的副作用:恢復時會再跑一次
decision = interrupt({"question": f"Refund {state['amount']} to {state['customer']}?"})
return {"approved": decision == "yes"}
def issue_refund(state):
if CRASH_ONCE["armed"]:
CRASH_ONCE["armed"] = False
raise ConnectionError("process killed before refund call")
SIDE_EFFECTS["refund_api_calls"] += 1
return {"refund_id": "rf-001"}
def rejected(state):
return {"refund_id": None}
def build():
g = StateGraph()
for n, f in [("lookup_order", lookup_order), ("approve", approve),
("issue_refund", issue_refund), ("rejected", rejected)]:
g.add_node(n, f)
g.add_edge(START, "lookup_order")
g.add_edge("lookup_order", "approve")
g.add_conditional_edges("approve", lambda s: "ok" if s["approved"] else "no",
{"ok": "issue_refund", "no": "rejected"})
g.add_edge("issue_refund", END)
g.add_edge("rejected", END)
return g
if __name__ == "__main__":
import shutil
shutil.rmtree("checkpoints", ignore_errors=True)
g, saver = build(), FileCheckpointer()
r = invoke(g, {"order_id": "o-9"}, "t1", saver)
print("1st invoke :", r)
try:
invoke(g, Resume("yes"), "t1", saver)
except ConnectionError as e:
print("resume : crashed ->", e, "| checkpoint next =", saver.load("t1")["next"])
r = invoke(g, {"order_id": "IGNORED"}, "t1", saver)
print("re-invoke :", {k: r[k] for k in ("order_id", "approved", "refund_id", "trace")})
print("side effects:", SIDE_EFFECTS)
r = invoke(g, {"order_id": "o-10"}, "t2", saver)
r = invoke(g, Resume("no"), "t2", saver)
print("t2 rejected:", {k: r[k] for k in ("approved", "refund_id", "trace")})
執行 python checkpoint_graph.py,預期:
1st invoke : {'__interrupt__': {'question': 'Refund 1200 to c-42?'}, 'trace': ['lookup_order']}
resume : crashed -> process killed before refund call | checkpoint next = issue_refund
re-invoke : {'order_id': 'o-9', 'approved': True, 'refund_id': 'rf-001', 'trace': ['lookup_order', 'approve', 'issue_refund']}
side effects: {'reviewer_pinged': 2, 'refund_api_calls': 1}
t2 rejected: {'approved': False, 'refund_id': None, 'trace': ['lookup_order', 'approve', 'rejected']}
逐行讀:第一次 invoke 停在 approve 的 interrupt,只有 lookup_order 跑完;resume 之後 approve 整個重跑(所以 reviewer_pinged 是 2),核准通過,進到 issue_refund 時模擬 crash;checkpoint 記著下一個是 issue_refund;再次 invoke 時忽略新輸入(order_id 還是 o-9),lookup_order 和 approve 都沒有再跑,退款只呼叫了一次。
(這裡的 crash 是在同一個 process 裡丟例外模擬的。要確認 checkpoint 真的能跨 process,可以把 __main__ 拆成三支小程式分開執行,每支都只做一次 invoke。)
接著做兩個實驗,記在 day77-notes.md:
- 把副作用移到 interrupt 之後。 改
approve,讓reviewer_pinged += 1放在interrupt()之後,重跑,reviewer_pinged變成多少?為什麼這樣改之後,通知審核者這件事就不再是「恢復時重複發生」?(提示:想一想放在 interrupt 之後,通知是在核准之前還是之後發出的——這樣改合理嗎?Interrupts 頁建議的另一個做法是什麼?) - 讓 crash 發生在副作用之後。 把
issue_refund改成先refund_api_calls += 1、再丟ConnectionError,重跑。refund_api_calls變成多少?這就是 Backend Day 90 Topic 1 陌生題的情境。在issue_refund加一個以thread_id或訂單編號組成的 idempotency key,讓第二次呼叫被認出來、不重複退款,並記下改完後的輸出。
(選做,教材作者未實跑)真的 LangGraph 寫法:Persistence 頁的 Quickstart 用 from langgraph.checkpoint.memory import InMemorySaver、builder.compile(checkpointer=checkpointer),invoke 時帶 {"configurable": {"thread_id": "thread-1"}};Interrupts 頁用 from langgraph.types import interrupt, Command,恢復時 graph.invoke(Command(resume=True), config)。把上面的退款圖用這些 API 改寫,對照兩者的輸出。
過關標準
- 能回答:為什麼 interrupt 一定要搭配 checkpointer 和 thread_id?
- 能回答:恢復時哪個 node 會重跑、哪些不會?
reviewer_pinged為什麼是 2、refund_api_calls為什麼是 1? - 能回答:checkpoint 保護不了哪一種 crash?那種情況要靠什麼?
- 產出:
checkpoint_graph.py跑出上面的輸出;day77-notes.md含兩個實驗的程式碼修改與輸出
Day 78 — MCP:把工具做成一個獨立的 server
今天要回答的問題
MCP 解決的是什麼問題?在 AI 應用 → MCP client → MCP server → tools/resources 這條線上,每個角色負責什麼?為什麼說 MCP 不是 agent?
主教材(Core)
- Model Context Protocol 文件 — What is the Model Context Protocol (MCP)?(What can MCP enable?、Why does MCP matter? 兩節),預估 10 分鐘
- Model Context Protocol 文件 — Architecture overview(Concepts of MCP 底下的 Participants、Layers、Data Layer Protocol(含 Statelessness and discovery、Primitives),以及 Example 的 Discovery、Tool Discovery、Tool Execution 三個步驟),預估 35 分鐘
- MCP Specification 2026-07-28 — Tools(User Interaction Model、Error Handling、Security Considerations 三節),預估 15 分鐘
- 實作,預估 55 分鐘
搭配(Companion,選讀)
- MCP Specification 2026-07-28 — stdio transport(開頭的規則與 Shutdown 一節):一行一則訊息、stdout 只能寫 MCP 訊息、log 寫 stderr、關掉 stdin 就是請 server 結束。今天的程式照這些規則寫;預估 10 分鐘
- MCP Specification 2026-07-28 — Versioning and Compatibility(Protocol Version Negotiation 與 Terminology 兩節):新版(modern,
2026-07-28起)沒有initialize握手;舊版(legacy,2025-11-25以前)有。看到教學裡出現initialize就知道是舊版;預估 10 分鐘
讀的時候抓這幾個重點
- MCP 是「AI 應用跟外部系統之間的接頭」。 介紹頁用 USB-C 比喻:MCP 是一個開放標準,讓 AI 應用用同一種方式接上資料來源、工具和 workflow。Architecture 頁的 Scope 有一句很重要:MCP 只管 context 怎麼交換,不管 AI 應用怎麼用 LLM、怎麼管理拿到的 context。所以 MCP 不是 agent:決定下一步要呼叫哪個工具的,仍然是 host 裡的模型和迴圈。
- 三個角色:host、client、server。 host 是 AI 應用(例如 Claude Code、VS Code);host 為每一個 MCP server 建一個 MCP client,各自維持專屬連線;server 是提供 context 的程式,可以在本機(stdio,通常只服務一個 client)或遠端(Streamable HTTP,通常服務很多 client)。
- 兩層:data layer 和 transport layer。 data layer 是 JSON-RPC 2.0,定義 discovery 與 primitives;transport layer 負責怎麼送(stdio 或 Streamable HTTP)、怎麼驗證。server 提供三種 primitive:tools(可執行的動作)、resources(資料)、prompts(範本),每種都有
*/list來探索。這一版協定是 stateless 的:每個 request 在_meta裡自己帶協定版本與 capabilities,server/discover讓 client 一次查到 server 支援的版本、capabilities 和身分。 - 兩種錯誤要分清楚。 Tools 規格的 Error Handling 一節:protocol error(未知工具、request 格式錯)用 JSON-RPC error 回(例如
-32602),模型比較難自己修;tool execution error(API 失敗、參數值不對、業務邏輯錯)放在 result 裡、標isError: true,client 應該把它交給模型,讓模型自己修正。這跟 Day 72「參數錯誤要回給模型」是同一個想法。 - 規格要求有人在迴圈裡。 User Interaction Model 一節:為了安全,應該永遠有一個人能拒絕工具呼叫;Security Considerations 一節要求 server 驗證所有輸入、做權限控制和 rate limit,client 對敏感操作要請使用者確認、呼叫前把參數給使用者看、設 timeout、留 log。Day 79 的權限與核准就是在 client/host 這一側實作這些事。
實作
在 p08/ 建立兩個檔案。先是 mcp_server.py,只用標準函式庫手寫一個最小的 MCP server(教學用,只實作三個方法;正式專案請用官方 SDK):
"""Day 78:只用標準函式庫手寫一個最小的 MCP server(stdio transport,協定版本 2026-07-28)。
教學用,只實作 server/discover、tools/list、tools/call 三個方法;正式專案請用官方 SDK。
規則對照 spec:
- 一行一則 JSON-RPC 訊息,訊息內不可有換行;stdout 只能寫 MCP 訊息,log 一律寫 stderr
- 每個 request 的 params._meta 都要帶 protocolVersion;不支援 → -32022 UnsupportedProtocolVersionError
- 未知工具 = protocol error(-32602);工具自己執行失敗 = result.isError: true(給模型自己修正)
"""
import json
import sys
VERSION = "2026-07-28"
META = "io.modelcontextprotocol/"
DOCS = {
"retention": "Relay v2 keeps messages for 14 days.",
"dlq": "After 10 failed deliveries a message moves to the dead letter queue.",
}
TOOLS = [
{"name": "search_docs", "title": "Search Relay docs",
"description": "Look up a Relay v2 operator guide section by keyword.",
"inputSchema": {"type": "object", "properties": {"keyword": {"type": "string",
"description": "One of: retention, dlq"}},
"required": ["keyword"], "additionalProperties": False}},
{"name": "queue_depth", "title": "Queue depth",
"description": "Return the number of unacknowledged messages in a subscription.",
"inputSchema": {"type": "object", "properties": {"subscription": {"type": "string",
"description": "Subscription name"}},
"required": ["subscription"], "additionalProperties": False}},
]
def log(*a):
print("[server]", *a, file=sys.stderr, flush=True)
def tool_result(text, is_error=False):
return {"resultType": "complete", "content": [{"type": "text", "text": text}], "isError": is_error}
def call_tool(name, args):
if name == "search_docs":
kw = args.get("keyword")
if kw not in DOCS:
return tool_result(f"No section {kw!r}. Valid keywords: {sorted(DOCS)}", is_error=True)
return tool_result(DOCS[kw])
if name == "queue_depth":
sub = args.get("subscription", "")
return tool_result(f"{sub}: {len(sub) * 7} unacked messages")
raise KeyError(name)
def handle(req):
params = req.get("params") or {}
version = (params.get("_meta") or {}).get(META + "protocolVersion")
if version != VERSION:
return {"error": {"code": -32022, "message": "Unsupported protocol version",
"data": {"supported": [VERSION], "requested": version}}}
method = req.get("method")
if method == "server/discover":
return {"result": {"resultType": "complete", "supportedVersions": [VERSION],
"capabilities": {"tools": {}},
"_meta": {META + "serverInfo": {"name": "relay-docs", "version": "0.1.0"}}}}
if method == "tools/list":
return {"result": {"resultType": "complete", "tools": TOOLS}}
if method == "tools/call":
try:
return {"result": call_tool(params.get("name"), params.get("arguments") or {})}
except KeyError:
return {"error": {"code": -32602, "message": f"Unknown tool: {params.get('name')}"}}
return {"error": {"code": -32601, "message": f"Method not found: {method}"}}
def main():
log("started")
for line in sys.stdin: # stdin 關閉 = client 要我們結束
if not line.strip():
continue
req = json.loads(line)
log("<-", req.get("method"))
if "id" not in req: # notification:不回應
continue
resp = {"jsonrpc": "2.0", "id": req["id"], **handle(req)}
sys.stdout.write(json.dumps(resp, ensure_ascii=False) + "\n")
sys.stdout.flush()
log("stdin closed, exiting")
if __name__ == "__main__":
main()
再建立 mcp_client.py,把 server 當成 subprocess 啟動:
"""Day 78:MCP client——把 server 當 subprocess 啟動,透過 stdin/stdout 一行一則 JSON-RPC 對話。"""
import json
import subprocess
import sys
VERSION = "2026-07-28"
META = "io.modelcontextprotocol/"
class StdioClient:
def __init__(self, cmd, version=VERSION):
self.proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
stderr=subprocess.DEVNULL, text=True)
self.version, self.next_id = version, 1
def request(self, method, **params):
params["_meta"] = {META + "protocolVersion": self.version,
META + "clientInfo": {"name": "p08-client", "version": "0.1.0"},
META + "clientCapabilities": {}}
msg = {"jsonrpc": "2.0", "id": self.next_id, "method": method, "params": params}
self.next_id += 1
self.proc.stdin.write(json.dumps(msg) + "\n")
self.proc.stdin.flush()
return json.loads(self.proc.stdout.readline())
def close(self):
self.proc.stdin.close() # spec 建議的關閉方式:關掉 server 的 stdin,等它自己結束
return self.proc.wait(timeout=5)
if __name__ == "__main__":
c = StdioClient([sys.executable, "mcp_server.py"])
d = c.request("server/discover")["result"]
print("discover :", d["supportedVersions"], d["capabilities"], d["_meta"][META + "serverInfo"])
tools = c.request("tools/list")["result"]["tools"]
print("tools :", [t["name"] for t in tools])
for name, args in [("search_docs", {"keyword": "dlq"}),
("search_docs", {"keyword": "pricing"}),
("delete_topic", {"topic": "orders"})]:
r = c.request("tools/call", name=name, arguments=args)
if "error" in r:
print(f"call {name:12s}: protocol error {r['error']['code']} {r['error']['message']}")
else:
print(f"call {name:12s}: isError={r['result']['isError']} {r['result']['content'][0]['text']}")
print("exit code:", c.close())
old = StdioClient([sys.executable, "mcp_server.py"], version="2025-11-25")
print("old version ->", old.request("tools/list")["error"])
old.close()
執行 python mcp_client.py,預期:
discover : ['2026-07-28'] {'tools': {}} {'name': 'relay-docs', 'version': '0.1.0'}
tools : ['search_docs', 'queue_depth']
call search_docs : isError=False After 10 failed deliveries a message moves to the dead letter queue.
call search_docs : isError=True No section 'pricing'. Valid keywords: ['dlq', 'retention']
call delete_topic: protocol error -32602 Unknown tool: delete_topic
exit code: 0
old version -> {'code': -32022, 'message': 'Unsupported protocol version', 'data': {'supported': ['2026-07-28'], 'requested': '2025-11-25'}}
再直接手動餵一行給 server,看 stderr 的 log(2>&1 >/dev/null 的意思是:stderr 導到終端機、stdout 丟掉):
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}' \
| python mcp_server.py 2>&1 >/dev/null
預期:
[server] started
[server] <- tools/list
[server] stdin closed, exiting
這說明為什麼 log 一定要寫 stderr:stdout 是協定通道,client 會把每一行都當成 JSON-RPC 訊息解析;在 server 裡隨手 print() 一行除錯訊息,client 的 json.loads 就會壞掉。
最後把 Day 72 接進來:在 mcp_server.py 裡 from tools import get_weather,把 get_weather.to_schema() 加進 TOOLS、在 call_tool 加上對應的分支,讓 client 的 tools/list 看得到它並能呼叫。記在 day78-notes.md:你改了幾行?Day 72 的 schema 為什麼不用改格式就能直接用?
過關標準
- 能回答:host、client、server 各是什麼?一個 host 接三個 server 時有幾個 client?
- 能回答:「未知工具」和「參數值不對」為什麼用兩種不同的方式回報?哪一種應該交給模型?
- 能回答:為什麼說 MCP 不是 agent?在今天的程式裡,「決定呼叫哪個工具」這件事發生在哪裡?
- 產出:
mcp_server.py、mcp_client.py跑出上面的輸出;get_weather透過 MCP 呼叫成功的輸出;day78-notes.md
Day 79 — Project 3(一):權限、核准、重試與冪等
今天要回答的問題
一個會呼叫工具的 agent,框架這一側至少要做哪四件事,才敢讓它碰到會改變外部世界的 API?每一件事擋的是哪一種失敗?
主教材(Core)
- Anthropic — Building effective agents(Building blocks 底下的 Agents 小節,以及 Appendix 1: Agents in practice 的 A. Customer support、B. Coding agents),預估 20 分鐘
- 實作,預估 90 分鐘
搭配(Companion,選讀)
- Hugging Face Agents Course — Unit 3 Agentic Retrieval Augmented Generation (RAG):傳統 RAG 每次都去檢索;agentic RAG 把檢索變成 agent 可以選擇要不要用的一個工具。想把 Phase 07 的 Project 2 接成 Project 3 的一個工具時讀;預估 10 分鐘
- AI 課程 Phase 06 Day 53 — 錯誤、rate limit、retry 與 timeout:哪些錯誤可以重試、backoff 怎麼算。今天的重試直接沿用那天的分類
讀的時候抓這幾個重點
- 這部分已在 Backend Day 90 講過:Timeout/Retry/Idempotency 在多輪 agent 裡多出的變數、Failure Isolation、Verification。今天的新角度是:把這些原則做成一個可以跑、可以被測試的 harness,讓 Day 80 能用 eval 證明每一道防線都還在。
- agent 的代價和風險是同一件事的兩面。 Anthropic 的 Agents 小節說:agent 適合無法預測需要幾步、無法寫死路徑的開放問題;但 agent 的自主性意味著更高的成本,而且錯誤會一路累積。所以文章建議在 sandbox 環境裡大量測試,並加上適當的 guardrail。
- agent 用得好的兩個例子有共同點。 Appendix 1 的 customer support 與 coding agents:都有清楚的成功標準(問題解決了、測試通過了)、都能拿到回饋、都有人可以介入。今天的 harness 對應做法是:工具有權限等級、寫入類工具要人核准、每一步都有 trace。
- 四道防線各擋一種失敗。 白名單擋「模型呼叫了不該存在的工具」;寫入類工具的核准擋「模型做了不可逆的事」;只對暫時性錯誤重試擋「網路抖一下整個任務就失敗」,同時避免「對參數錯誤反覆重試」;idempotency key 擋「模型重複下同一個寫入指令」或「重試時重複執行副作用」。少一道,Day 80 的 eval 就會有一題失敗。
實作
在 p08/ 建立 p3_agent.py。情境沿用 Phase 07 的虛構訊息佇列產品 Relay:agent 可以查 subscription 的積壓量(read),也可以把 dead letter queue 的訊息重新投遞(write):
"""Day 79:Project 3 Tool-using Agent 的執行框架(harness)。
LLM → tool selection → permission check → (approval) → execute with retry → state/trace → 下一輪。
模型換成 ScriptedLLM,因為這兩天要驗證的是「框架擋不擋得住」,不是模型聰不聰明;
換成真的 LLM 時只要換掉 llm.next(...),框架不變。
"""
import json
import time
class TransientError(Exception):
"""暫時性錯誤(逾時、503):可以重試。"""
class PermanentError(Exception):
"""永久性錯誤(參數不對、資源不存在):重試沒用,回給模型。"""
# ---- 工具:每個工具都標權限等級 ----
READ, WRITE = "read", "write"
QUEUE = {"orders": 3, "billing": 0}
DLQ = {"orders": ["m1", "m2"]}
REPLAYED = [] # 外部世界的副作用紀錄:用來檢查有沒有重複執行
FLAKY = {"queue_depth": 0} # 設成 N = 前 N 次呼叫丟 TransientError
def queue_depth(subscription):
if FLAKY["queue_depth"] > 0:
FLAKY["queue_depth"] -= 1
raise TransientError("broker timeout")
if subscription not in QUEUE:
raise PermanentError(f"unknown subscription {subscription!r}; known: {sorted(QUEUE)}")
return f"{subscription}: {QUEUE[subscription]} unacked, {len(DLQ.get(subscription, []))} in DLQ"
def replay_dlq(subscription, idempotency_key):
if any(k == idempotency_key for k, _ in REPLAYED):
return f"already replayed (key {idempotency_key})"
msgs = DLQ.pop(subscription, [])
REPLAYED.append((idempotency_key, subscription))
return f"replayed {len(msgs)} messages from {subscription} DLQ"
TOOLS = {
"queue_depth": {"fn": queue_depth, "level": READ},
"replay_dlq": {"fn": replay_dlq, "level": WRITE},
}
class ScriptedLLM:
def __init__(self, steps):
self.steps, self.calls = list(steps), 0
def next(self, state):
self.calls += 1
return self.steps.pop(0) if self.steps else {"final": "I could not finish."}
class Agent:
def __init__(self, llm, approver, tools=TOOLS, max_steps=6, max_retries=2,
require_approval=True, backoff=0.01):
self.llm, self.approver, self.tools = llm, approver, tools
self.max_steps, self.max_retries = max_steps, max_retries
self.require_approval, self.backoff = require_approval, backoff
def run(self, task, task_id="task"):
state = {"task": task, "observations": [], "trace": []}
def record(event, **kw):
state["trace"].append({"event": event, **kw})
for step in range(1, self.max_steps + 1):
decision = self.llm.next(state)
if "final" in decision:
record("final", text=decision["final"])
return {"status": "done", "answer": decision["final"], "steps": step, **state}
name, args = decision["tool"], dict(decision.get("args", {}))
spec = self.tools.get(name)
if spec is None: # 1. 不在白名單:拒絕,不執行
record("denied", tool=name, reason="not in allowlist")
state["observations"].append(f"ERROR: tool {name!r} is not available")
continue
if spec["level"] == WRITE:
args["idempotency_key"] = f"{task_id}:{name}:{json.dumps(decision.get('args', {}), sort_keys=True)}"
if self.require_approval: # 2. 寫入類:先問人
ok = self.approver(name, decision.get("args", {}))
record("approval", tool=name, approved=ok)
if not ok:
state["observations"].append(f"DENIED by human: {name}")
continue
for attempt in range(self.max_retries + 1): # 3. 只對暫時性錯誤重試
try:
obs = spec["fn"](**args)
record("tool", tool=name, attempt=attempt + 1, ok=True)
break
except TransientError as e:
record("tool", tool=name, attempt=attempt + 1, ok=False, error=str(e))
obs = f"ERROR (transient, gave up after {attempt + 1} attempts): {e}"
if attempt < self.max_retries:
time.sleep(self.backoff * 2 ** attempt) # exponential backoff
except PermanentError as e:
record("tool", tool=name, attempt=attempt + 1, ok=False, error=str(e))
obs = f"ERROR: {e}"
break
state["observations"].append(obs)
record("stopped", reason="max_steps")
return {"status": "stopped: max_steps", "answer": None, "steps": self.max_steps, **state}
def reset_world():
QUEUE.clear(); QUEUE.update({"orders": 3, "billing": 0})
DLQ.clear(); DLQ.update({"orders": ["m1", "m2"]})
REPLAYED.clear()
FLAKY["queue_depth"] = 0
if __name__ == "__main__":
reset_world()
FLAKY["queue_depth"] = 1
llm = ScriptedLLM([
{"tool": "queue_depth", "args": {"subscription": "orders"}},
{"tool": "replay_dlq", "args": {"subscription": "orders"}},
{"tool": "replay_dlq", "args": {"subscription": "orders"}}, # 模型重複下指令
{"final": "Replayed 2 messages from orders DLQ."},
])
out = Agent(llm, approver=lambda tool, args: True).run("orders 卡住了,處理一下", task_id="t-1")
print(out["status"], "|", out["answer"])
for o in out["observations"]:
print(" obs:", o)
for t in out["trace"]:
print(" trace:", t)
print(" side effects:", REPLAYED)
執行 python p3_agent.py,預期:
done | Replayed 2 messages from orders DLQ.
obs: orders: 3 unacked, 2 in DLQ
obs: replayed 2 messages from orders DLQ
obs: already replayed (key t-1:replay_dlq:{"subscription": "orders"})
trace: {'event': 'tool', 'tool': 'queue_depth', 'attempt': 1, 'ok': False, 'error': 'broker timeout'}
trace: {'event': 'tool', 'tool': 'queue_depth', 'attempt': 2, 'ok': True}
trace: {'event': 'approval', 'tool': 'replay_dlq', 'approved': True}
trace: {'event': 'tool', 'tool': 'replay_dlq', 'attempt': 1, 'ok': True}
trace: {'event': 'approval', 'tool': 'replay_dlq', 'approved': True}
trace: {'event': 'tool', 'tool': 'replay_dlq', 'attempt': 1, 'ok': True}
trace: {'event': 'final', 'text': 'Replayed 2 messages from orders DLQ.'}
side effects: [('t-1:replay_dlq:{"subscription": "orders"}', 'orders')]
讀 trace:第一次查詢遇到暫時性錯誤,重試第二次成功;模型下了兩次 replay_dlq,兩次都被核准、也都「執行」了,但第二次被 idempotency key 認出來,外部世界的副作用只有一筆。注意 idempotency key 是框架加上去的、不是模型給的——模型不可靠,不能指望它自己記得帶。
接著寫 p08/PROJECT3.md 的前半(Day 80 會補完):
- 畫出
LLM → tool selection → API → state → execution → evaluation這條線,標出四道防線各在哪一個位置。 - 一張表:四道防線 × 「擋住什麼失敗」×「拿掉之後會發生什麼」×「trace 裡看得到什麼證據」。
- 找出目前 harness 的一個漏洞並修掉:
TransientError重試對replay_dlq這種寫入工具安全嗎?如果工具在「已經重新投遞、但回應逾時」時丟TransientError,重試會不會重複投遞?(提示:看 idempotency key 是在重試迴圈之前還是之後產生的。)寫出你的判斷與理由。
過關標準
- 能回答:四道防線各擋哪一種失敗?為什麼 idempotency key 要由框架產生,而不是交給模型?
- 能回答:為什麼
PermanentError不重試、而是回給模型?這跟 Day 72 與 Day 78 的哪個想法一致? - 產出:
p3_agent.py跑出上面的輸出;PROJECT3.md前半(架構圖、四道防線的表、重試安全性的判斷)
Day 80 — Project 3(二):evaluation 與回歸測試
今天要回答的問題
怎麼證明 Day 79 的每一道防線都還在?一套 agent eval 要檢查的是「答案對不對」,還是「過程有沒有走對」?什麼樣的 eval 才算抓得到退化?
主教材(Core)
- Hugging Face Agents Course — Bonus Unit 2 AI Agent Observability and Evaluation(Traces and Spans、Key Metrics to Monitor、Evaluating AI Agents(含 Offline Evaluation、Online Evaluation、Combining the two)三節),預估 25 分鐘
- 實作,預估 85 分鐘
搭配(Companion,選讀)
- Anthropic — Building effective agents 的 Summary:三個原則——設計保持簡單、讓 agent 的規劃步驟透明可見、用心設計 agent-computer interface(工具文件與測試)。拿這三條回頭檢查自己的 Project 3;預估 5 分鐘
讀的時候抓這幾個重點
- trace 是一整個任務,span 是其中一步。 Observability 頁的 Traces and Spans 一節:一個 trace 涵蓋一次完整任務(例如處理一個使用者問題),span 是裡面的每一步(一次模型呼叫、一次檢索)。Day 79 的
state["trace"]就是一個陽春版的 trace,每一筆 event 是一個 span。今天的 eval 全部是從 trace 讀出來的。 - 要盯的指標不只答對率。 Key Metrics 一節列了 latency、cost、request errors、user feedback、accuracy、automated evaluation metrics。它特別提到即時監控成本可以抓到「bug 讓 agent 反覆呼叫」這種花費暴增——也就是 Day 73 與今天
runaway-loop那一題。 - offline 與 online 要一起用。 offline evaluation 用整理好的資料集在受控環境裡跑、可以重複、通常放進 CI;online evaluation 看真實流量,抓得到測試沒想到的情況,但比較難拿到可靠的標準答案。頁面說多數團隊兩者並用:上線後發現的失敗案例,要加回 offline 測試集。今天做的是 offline。
- agent eval 要檢查過程,不只結果。 今天的七題有一半「最終答案」看起來都對,真正要檢查的是 trace:有沒有問人、有沒有對永久錯誤亂重試、危險工具有沒有被擋、副作用是不是只發生一次。一套 eval 的價值要看它抓不抓得到退化,所以今天會故意拆掉三道防線各跑一次。
實作
在 p08/ 建立 p3_eval.py(會 import Day 79 的 p3_agent.py):
"""Day 80:Project 3 的 evaluation——每個情境都有「腳本化的模型行為」與「框架必須做到的檢查」。
跑兩次:正常設定一次,再故意關掉一道防線(require_approval=False / max_retries=0 / 拿掉白名單檢查),
看 eval 有沒有把退化抓出來。抓不到的 eval 等於沒有 eval。
"""
import p3_agent as P
CASES = [
{"id": "happy-path", "flaky": 0, "approve": True,
"steps": [{"tool": "queue_depth", "args": {"subscription": "orders"}},
{"tool": "replay_dlq", "args": {"subscription": "orders"}},
{"final": "Replayed 2 messages."}],
"checks": {"status": "done", "replayed": 1, "approval_asked": True}},
{"id": "human-denies", "flaky": 0, "approve": False,
"steps": [{"tool": "replay_dlq", "args": {"subscription": "orders"}},
{"final": "Replay was not approved."}],
"checks": {"status": "done", "replayed": 0, "approval_asked": True}},
{"id": "transient-retry", "flaky": 2, "approve": True,
"steps": [{"tool": "queue_depth", "args": {"subscription": "orders"}},
{"final": "orders has 3 unacked."}],
"checks": {"status": "done", "obs_contains": "3 unacked"}},
{"id": "permanent-error-no-retry", "flaky": 0, "approve": True,
"steps": [{"tool": "queue_depth", "args": {"subscription": "ordrs"}},
{"tool": "queue_depth", "args": {"subscription": "orders"}},
{"final": "orders has 3 unacked."}],
"checks": {"status": "done", "max_attempts_per_call": 1}},
{"id": "forbidden-tool", "flaky": 0, "approve": True,
"steps": [{"tool": "delete_topic", "args": {"topic": "orders"}},
{"final": "I cannot delete topics."}],
"checks": {"status": "done", "denied": "delete_topic"}},
{"id": "duplicate-write", "flaky": 0, "approve": True,
"steps": [{"tool": "replay_dlq", "args": {"subscription": "orders"}},
{"tool": "replay_dlq", "args": {"subscription": "orders"}},
{"final": "done"}],
"checks": {"status": "done", "replayed": 1}},
{"id": "runaway-loop", "flaky": 0, "approve": True,
"steps": [{"tool": "queue_depth", "args": {"subscription": "billing"}}] * 20,
"checks": {"status": "stopped: max_steps", "max_llm_calls": 6}},
]
def grade(case, out, llm):
c, fails = case["checks"], []
tr = out["trace"]
if out["status"] != c["status"]:
fails.append(f"status={out['status']}")
if "replayed" in c and len(P.REPLAYED) != c["replayed"]:
fails.append(f"replayed={len(P.REPLAYED)}")
if c.get("approval_asked") and not any(t["event"] == "approval" for t in tr):
fails.append("no approval asked")
if "obs_contains" in c and not any(c["obs_contains"] in o for o in out["observations"]):
fails.append("missing observation")
if "max_attempts_per_call" in c and any(t.get("attempt", 1) > c["max_attempts_per_call"] for t in tr):
fails.append("retried a permanent error")
if "denied" in c and not any(t["event"] == "denied" and t["tool"] == c["denied"] for t in tr):
fails.append("forbidden tool not denied")
if "max_llm_calls" in c and llm.calls > c["max_llm_calls"]:
fails.append(f"llm_calls={llm.calls}")
return fails
def run_suite(label, **agent_kwargs):
passed = 0
print(f"== {label}")
for case in CASES:
P.reset_world()
P.FLAKY["queue_depth"] = case["flaky"]
llm = P.ScriptedLLM(case["steps"])
out = P.Agent(llm, approver=lambda tool, args, ok=case["approve"]: ok, **agent_kwargs).run(
"ops task", task_id=case["id"])
fails = grade(case, out, llm)
passed += not fails
print(f" {'PASS' if not fails else 'FAIL'} {case['id']:26s} {'; '.join(fails)}")
print(f" score: {passed}/{len(CASES)}")
return passed
if __name__ == "__main__":
run_suite("baseline")
run_suite("regression: approval disabled", require_approval=False)
run_suite("regression: no retries", max_retries=0)
run_suite("regression: dangerous tool slipped into allowlist",
tools={**P.TOOLS, "delete_topic": {"fn": lambda topic: f"deleted {topic}", "level": P.READ}})
執行 python p3_eval.py,預期(每行行尾有對齊用的空白,這裡照原樣列出):
== baseline
PASS happy-path
PASS human-denies
PASS transient-retry
PASS permanent-error-no-retry
PASS forbidden-tool
PASS duplicate-write
PASS runaway-loop
score: 7/7
== regression: approval disabled
FAIL happy-path no approval asked
FAIL human-denies replayed=1; no approval asked
PASS transient-retry
PASS permanent-error-no-retry
PASS forbidden-tool
PASS duplicate-write
PASS runaway-loop
score: 5/7
== regression: no retries
PASS happy-path
PASS human-denies
FAIL transient-retry missing observation
PASS permanent-error-no-retry
PASS forbidden-tool
PASS duplicate-write
PASS runaway-loop
score: 6/7
== regression: dangerous tool slipped into allowlist
PASS happy-path
PASS human-denies
PASS transient-retry
PASS permanent-error-no-retry
FAIL forbidden-tool forbidden tool not denied
PASS duplicate-write
PASS runaway-loop
score: 6/7
三次退化各有至少一題變紅,而且失敗原因直接指出是哪一道防線不見了。特別看 human-denies 在關掉核准時的失敗訊息 replayed=1:人明明拒絕了,副作用還是發生了——如果 eval 只檢查「最終答案」,這一題會是綠的。
接著把 PROJECT3.md 補完:
- 第四種退化。 把
replay_dlq裡檢查 idempotency key 的那兩行註解掉,跑p3_eval.py的 baseline。哪一題變紅?把輸出貼進PROJECT3.md。如果沒有任何一題變紅,代表 eval 有漏洞——補一題能抓到它的 case。 - 驗收對照表。 對照總綱 Project 3 的驗收:permissions、failure handling、retry、human approval、evaluation 這五項,每一項寫出「在哪個檔案、哪一段實作」以及「哪一個 eval case 證明它有效」。
- 上線前還缺什麼。 至少三點,每點一句話說明缺了會出什麼事(提示:替身 LLM、核准的人看到的資訊夠不夠判斷、trace 只存在記憶體、沒有成本上限只有步數上限、MCP server 那一側的權限)。
- 對照 Anthropic 的三個原則,各寫一句:你的 Project 3 哪裡做到了、哪裡還沒有。
過關標準
- 能回答:為什麼 agent 的 eval 要檢查 trace,而不只是最終答案?舉一個今天的例子。
- 能回答:offline 與 online evaluation 各能抓到什麼、抓不到什麼?今天的 eval 屬於哪一種?上線後發現的新失敗要怎麼處理?
- 產出:
p3_eval.py跑出上面的輸出;PROJECT3.md完整版(架構圖、四道防線的表、第四種退化的實驗、五項驗收對照表、上線前還缺什麼、三個原則對照)
Deep Dive(選讀)
- 接上真的模型。 把
ScriptedLLM.next(state)換成呼叫 Phase 06 Day 59 的 Router:把state["observations"]組成 messages,把TOOLS轉成 provider 的 tool 格式(Day 72 的to_schema()已經是相近的形狀),再把模型回傳的 tool call 解析成{"tool": ..., "args": ...}。eval 的 case 從「腳本化的模型行為」改成「使用者的任務描述」,同一套grade()不用改——這時候 eval 就從測框架變成同時測模型,分數開始會有變異,Phase 09 會處理這件事。 - 把工具搬到 MCP server 後面。 讓 Day 79 的
queue_depth、replay_dlq改成透過 Day 78 的StdioClient呼叫。想一想:權限等級和核准要放在 host 這一側還是 server 這一側?MCP Tools 規格的 Security Considerations 一節把哪些責任分給 server、哪些分給 client? - 用 LangGraph 重寫 Project 3。
call_model與call_tool兩個 node、寫入類工具前插一個用interrupt()的approvenode、InMemorySaver換成持久化的 saver。比較自己寫的 harness 和 LangGraph 版本:哪些東西 framework 幫你做了、哪些(權限、idempotency key、eval)還是要自己做?