ADK Go 入門 07 - Agent Instruction 設計技巧

Instruction 是 Agent 行為的核心，決定它的角色、能力邊界與決策邏輯。寫得好的 Instruction 能讓 Agent 表現穩定；寫得模糊的 Instruction 會讓 Agent 行為飄移、工具呼叫錯誤。

Instruction vs GlobalInstruction

欄位	作用範圍	適合放什麼
`Instruction`	此 Agent 本次對話	角色定義、工具使用規則、決策邏輯
`GlobalInstruction`	此 Agent 所有回應	語言強制、語氣規定、全域輸出格式

常見用法：GlobalInstruction 統一語言，Instruction 定義業務邏輯。

llmagent.Config{
    GlobalInstruction: "You must always respond in Traditional Chinese (繁體中文).",
    Instruction:       "你是一個專責處理商品查詢的助理。只回答商品相關問題...",
}

有效 Instruction 的結構

好的 Instruction 通常包含：

1. 角色定義

1	你是一個專責處理訂單管理的助理。

2. 能力說明（有什麼工具可用）

你可以使用以下工具：
- get_order：根據訂單編號查詢訂單
- create_order：建立新訂單
- list_orders：列出客戶的所有訂單

3. 決策規則

1 2	當使用者提供訂單編號時，先呼叫 get_order 確認訂單存在，再回應。若訂單不存在，告知使用者並詢問是否需要重新確認。

4. 邊界聲明

1	只處理訂單相關問題。其他問題請告知：「這個問題不在我的服務範圍內。」

多 Agent 系統中的 Instruction 寫法

在多 Agent 架構中，根 Agent 的 Instruction 需要明確列出子 Agent 的職責，讓 LLM 知道何時移交：

你是負責路由的總助理。根據使用者的問題，移交給適合的子 Agent：

- product_agent：所有商品查詢、新增、修改、刪除問題
- order_agent：所有訂單建立、查詢、修改問題

判斷不確定時，優先詢問使用者意圖，再決定移交對象。

⚠️ Description 欄位也很重要：ADK 的 transfer_to_agent 機制部分依賴各 Agent 的 Description 來輔助路由判斷，確保每個 Agent 的 Description 精準描述其職責。

常見錯誤寫法

⚠️ 過於模糊的角色定義

// 不好：沒有說明能做什麼、不能做什麼
Instruction: "你是一個助理，幫助使用者解決問題。"

// 好：明確職責與工具
Instruction: "你是訂單管理助理，只處理訂單查詢與建立，使用 get_order 和 create_order 工具。"

⚠️ 工具使用規則不清

// 不好：沒說何時用工具
Instruction: "你有 search_product 工具可以使用。"

// 好：明確觸發條件
Instruction: "當使用者詢問商品時，一律先呼叫 search_product 確認商品存在，再回應。"

⚠️ Instruction 太長導致遺忘：超過一定長度，LLM 容易忽略後段規則。重要規則放前面，非必要內容刪除。