Pydantic AI Harness 進階能力擴充

在建構 AI 代理人 (Agent) 的過程中，隨著應用場景的複雜度提升，單純的問答與基本工具呼叫往往無法滿足實務需求。你可能會需要讓 Agent 管理對話記憶、存取檔案系統，或是以更有效率的方式同時執行多個工具。

Pydantic AI Harness 是 Pydantic 官方提供的一個擴充能力庫 (Capability Library)。你可以把它想像成是 Agent 的「外掛電池 (Batteries for your agent)」。它將許多進階的功能模組化，讓開發者可以根據需求，選擇性地將這些能力賦予給 Agent，而不需要從頭造輪子。

為什麼需要 Harness 擴充庫？

Pydantic AI 核心套件的設計哲學是保持輕量與穩定，但 AI 領域的技術迭代非常迅速。Harness 作為一個「孵化器 (Incubation Space)」，允許新功能在這裡快速迭代與實驗，當這些擴充能力發展成熟且被廣泛使用後，未來就有機會被整合進 Pydantic AI 的核心套件中。

目前 Harness 提供了如記憶體管理、安全護欄 (Guardrails)、多代理人協作等功能。其中最具革命性且最受矚目的核心能力，非 Code Mode (程式碼模式) 莫屬。

認識 Code Mode (程式碼模式)

在傳統的 Agent 開發中，模型呼叫工具 (Tool Calling) 是一個來回往返的過程。假設你有一個取得天氣的工具，且使用者要求查詢 10 個城市的天氣，Agent 必須向大語言模型發起 10 次以上的 API 請求。這種「一次呼叫一個工具」的模式不僅速度極慢、非常耗費 Token 成本，還容易因為對話上下文 (Context) 過長而導致模型產生幻覺。

Code Mode 解決了這個痛點。

它透過一個安全執行的沙盒環境 (Monty Sandbox)，將你寫好的所有工具包裝成單一的 run_code 工具。當大語言模型遇到需要大量呼叫工具的情境時，它不再傻傻地一次呼叫一個，而是直接寫出一段包含迴圈、條件判斷、甚至非同步 (asyncio.gather) 的 Python 程式碼，並在沙盒中一次執行完畢。這樣一來，原本需要來回 10 次的 API 請求，現在只需要 1 次就能搞定。

安裝方式

若要使用 Harness 與 Code Mode 功能，你需要透過套件管理工具安裝：

uv add "pydantic-ai-harness[code-mode]"

Code Mode 實作範例

以下範例展示了如何將 Code Mode 能力賦予給 Agent，並讓它能自動組合多個工具來解決問題。

import asyncio
from pydantic_ai import Agent
from pydantic_ai_harness import CodeMode

# 1. 建立 Agent，並在 capabilities 中啟用 CodeMode
agent = Agent(
    'anthropic:claude-3-5-sonnet-latest', # 建議使用具備良好 coding 能力的模型
    capabilities=[CodeMode()]
)

# 2. 定義普通工具 (不需要特別為 Code Mode 修改)
@agent.tool_plain
def get_weather(city: str) -> dict:
    """取得指定城市目前的氣象資訊。"""
    # 這裡模擬呼叫外部天氣 API
    return {'city': city, 'temp_f': 72, 'condition': 'sunny'}

@agent.tool_plain
def convert_temp(fahrenheit: float) -> float:
    """將華氏溫度轉換為攝氏溫度。"""
    return round((fahrenheit - 32) * 5 / 9, 1)

# 3. 執行提問
question = "請問巴黎和東京今天的天氣如何？請用攝氏溫度告訴我。"
result = agent.run_sync(question)

print(result.output)

在上述範例中，當 Agent 收到問題時，模型在背後實際上會生成類似下方的 Python 程式碼來一次解決所有問題：

# 模型在背後自動生成的程式碼，透過 Code Mode 在沙盒中執行：
paris, tokyo = await asyncio.gather(
    get_weather(city='Paris'),
    get_weather(city='Tokyo'),
)

paris_c = await convert_temp(fahrenheit=paris['temp_f'])
tokyo_c = await convert_temp(fahrenheit=tokyo['temp_f'])

{'paris': paris_c, 'tokyo': tokyo_c}

透過 Code Mode，Agent 可以自主決定如何最有效率地運用你提供的工具。它利用了 asyncio.gather 並行取得兩個城市的天氣，再分別轉換溫度。這種將「工具編排邏輯」交還給大語言模型自行撰寫程式碼來執行的機制，大幅度提升了複雜任務的執行效率與系統穩定度。