串接外部 API 當工具：認證、重試與冪等

Agent 呼叫外部 API 的失敗模式，跟一般程式一樣，只是頻率更高——模型會用你沒想過的參數組合，而且失敗後傾向重試。

認證絕不能交給模型

API 金鑰、使用者 token 一律由伺服器端注入，不要放進工具參數。否則金鑰會出現在訊息串裡，而訊息串可能被記錄、被摘要、甚至被回顯給使用者。

def dispatch(name, args, ctx):
    if name == 'search_orders':
        # token 來自伺服器端的使用者情境，不從 args 取
        return orders_api.search(**args, auth=ctx.user_token)

重試要有節制

import time

def call_with_retry(fn, tries=3, base=0.5):
    for i in range(tries):
        try:
            return fn()
        except (Timeout, ServerError) as e:
            if i == tries - 1: raise
            time.sleep(base * (2 ** i))   # 指數退避
        except ClientError:
            raise                          # 4xx 不重試，重試也不會成功

寫入操作必須冪等

Agent 可能因為逾時而重複呼叫同一個建立操作，導致重複下單。做法是由呼叫端產生冪等鍵（idempotency key），同一個任務步驟固定用同一個鍵。

key = f'{trace_id}:{step}'
orders_api.create(payload, idempotency_key=key)

把限流轉成模型看得懂的訊息

遇到 429 時，不要直接把原始錯誤丟給模型。回傳「查詢過於頻繁，請等待 3 秒後再試，或改用一次查詢多筆的方式」，模型才知道要改策略而不是繼續猛打。