Edge Contract：邊的合約

這是整門課最重要的一課。

前面學了節點和邊的基礎。現在要講一個多數 Graph Engineering 文章跳過的重點：邊的合約比節點的設計更重要。

為什麼？因為節點可以隨時換——今天用 Claude，明天換 Gemini，後天用本地模型。但邊不能隨便換。改一條邊的合約，上下游全要跟著動。

邊的合約回答四個問題。

1. Schema：傳什麼格式

從 A 到 B 的資料必須有明確的結構。不定義清楚，B 拿到的東西可能不是它預期的形狀。

邊：商品分析 Agent → 上架審核 Gate

schema:
  title: string（商品名，≤ 50 字）
  description: string（商品描述，≤ 500 字）
  price: number（建議售價）
  category: "服飾" | "美妝" | "食品" | "3C"
  risk_flags: string[]（可能的違規項目）

定義 schema 的好處：下游節點可以直接處理結構化資料，不用再 parse 自然語言輸出。

2. Context Budget：傳多少

LLM 有 context window 限制。如果上游產出了一萬字的分析報告，全部塞給下游，context window 可能爆掉，至少成本會暴增。

Context budget 就是「這條邊允許傳多少 token」。

邊：客戶對話歷史 Memory → 回覆生成 Agent

budget: ≤ 2,000 tokens
策略: 只傳最近 5 輪對話 + 客戶基本資料摘要

常見陷阱：不設 budget，什麼都丟過去。結果一個月後回頭看帳單才發現問題。

3. Error Contract：錯了怎麼辦

節點會失敗。LLM 可能回了垃圾、API 可能超時、Tool 可能查不到資料。Error contract 定義：這條邊的上游出錯時，該怎麼做。

三種常見策略：

Retry（重試）：再跑一次。適合暫時性錯誤（API 超時、rate limit）。

on_error: retry 2 次，間隔 5 秒

Fallback（備案）：上游失敗就走另一條路。

on_error: fallback → 人工客服 Gate

Cut（截斷）：上游失敗就停止下游，不要讓錯誤繼續傳播。

on_error: cut downstream, 通知管理員

4. Timeout：等多久

LLM 呼叫可能卡住。Gate 節點等人審核可能等好幾天。沒有 timeout，整張圖就會停擺。

邊：商品描述生成 Agent → 審核 Gate
agent_timeout: 30s（超時就 retry）
gate_timeout: 48h（超時就自動 approve，標記為「未審核」）

不同節點類型有不同的 timeout 量級：Agent 是秒級、Tool 是毫秒級、Gate 可能是小時或天級。

一條完整的 Edge Contract

把四個要素組在一起：

邊：促銷文案生成 Agent → 法務檢查 Tool

schema:
  draft: string（文案全文）
  metadata: { word_count: int, promo_type: string }

budget: ≤ 4,000 tokens

timeout: 30s

on_error:
  retry: 2 次
  fallback: → 人工撰寫 Gate

這就是一條邊的完整說明書。寫過微服務 API 文件的人會覺得很熟悉——概念一樣，只是你的服務現在是 LLM。

AI 協作：學了這個，跟 AI 怎麼配合？

Edge contract 是你跟 AI 協作時最值得花時間定義的東西。定義越清楚，AI 設計出的工作流越穩定。

你的人類優勢：

• 決定 error 策略——retry、fallback、還是 cut，取決於你對業務影響的判斷
• 設定 timeout——等多久算太久，只有了解業務脈絡的你能定

可以這樣跟 AI 說：

我的工作流有一條邊：AI 客服回覆 → 品質審查。幫我寫這條邊的 Edge Contract，包含 schema（回覆要帶哪些欄位）、context budget（token 上限）、error contract（失敗怎麼處理）、timeout（等多久）。