Agent 與既有系統整合：把老舊 API 包成可用工具

一、收斂參數

# 原始 API：30 個參數，多數有預設值且與模型無關
# 包裝後：只暴露模型真的需要決定的 3 個
def search_orders(order_no=None, email=None, days=30):
    return legacy.OrderQuery(
        orderNo=order_no, custEmail=email,
        dateFrom=(today - timedelta(days=days)).strftime('%Y%m%d'),
        dateTo=today.strftime('%Y%m%d'),
        pageSize=50, includeVoid='N', channel='ALL',
        sortBy='ORDER_DATE', sortDir='DESC',   # 其餘固定
    )

二、精簡回傳

回傳兩百個欄位會吃掉大量上下文，而且模型要在噪音中找資訊。只保留與任務相關的欄位，並把代碼翻譯成可讀文字。

STATUS_MAP = {'01': '待付款', '02': '已付款', '03': '已出貨',
              '04': '已完成', '09': '已取消'}

def simplify(raw):
    return {
        'order_no': raw['ORDER_NO'],
        'status': STATUS_MAP.get(raw['ORD_STS'], f"未知({raw['ORD_STS']})"),
        'amount': float(raw['TOT_AMT']),
        'ordered_at': fmt_date(raw['ORD_DT']),
        'items': [{'name': i['ITM_NM'], 'qty': int(i['QTY'])}
                  for i in raw.get('ITEM_LIST', [])[:20]],
    }

三、翻譯錯誤

ERROR_MAP = {
  'E0012': ('ORDER_NOT_FOUND', '查無此訂單編號', '請確認編號是否正確，或改用信箱查詢'),
  'E0088': ('DATE_RANGE_TOO_WIDE', '查詢區間超過 90 天', '請把 days 參數縮小到 90 以內'),
  'E9001': ('UPSTREAM_BUSY', '後端系統忙碌', '請於數秒後重試'),
}

def wrap_error(code):
    ec, msg, hint = ERROR_MAP.get(code, ('UNKNOWN', f'未知錯誤 {code}', None))
    return {'ok': False, 'error_code': ec, 'message': msg, 'hint': hint}

包裝層也要處理效能

• 老舊 API 常常很慢，包裝層要設逾時並回傳可理解的訊息。
• 同一次執行內做結果快取。
• 把多次呼叫合併成一次批次查詢（若上游支援）。

把包裝層當成獨立元件維護

包裝層應該有自己的測試、版本與文件，而不是散落在 Agent 程式碼裡。上游 API 改版時，你只需要改一個地方，Agent 的提示與工具描述不受影響。