Pydantic AI Agent 基礎與系統提示

在 Pydantic AI 的世界裡，Agent（代理人）是整個框架中最核心的元件。Agent 負責封裝與語言模型 (LLM) 互動的邏輯，包含使用哪個模型、遵循哪些系統指令、可以使用哪些工具，以及期望產出什麼樣格式的結果。

這篇文章將帶你深入了解如何建立與配置 Agent，以及如何設計系統提示 (System Prompts) 來引導代理人的行為。

建立 Agent 實例

建立一個 Agent 非常直覺，你只需要實例化 pydantic_ai.Agent 類別即可。在最簡單的情況下，你甚至只需要指定要使用的模型。

from pydantic_ai import Agent

# 建立一個基礎 Agent，指定使用 OpenAI 的 GPT-4o 模型
agent = Agent('openai:gpt-4o')

除了模型字串之外，你可以在建立 Agent 時傳入更多設定參數，例如：

  • model：指定要使用的模型（字串格式或模型實例）。
  • system_prompt：給予模型的靜態系統指令，用來定義代理人的角色與行為邊界。
  • deps_type：定義依賴注入 (Dependencies) 的資料型別（後續章節會詳細介紹）。
  • result_type：定義期望模型回傳的結構化資料型別（後續章節會詳細介紹）。

系統提示 (System Prompts)

系統提示是控制 AI 行為最重要的方式之一。它告訴 AI 它是誰、它應該做什麼、不該做什麼，以及回覆時應該採用的語氣和格式。

在 Pydantic AI 中，設定系統提示有兩種主要方式：靜態宣告與動態生成。

1. 靜態宣告系統提示

靜態提示指的是在建立 Agent 實例時就固定下來的指令。如果你的 Agent 的角色非常固定，不會隨著使用者的不同或環境變化而改變，使用靜態提示是最簡單的做法。

你可以透過 system_prompt 參數傳入字串或字串列表（多個指令會被組合成一個完整的系統提示）。

from pydantic_ai import Agent

# 使用字串列表來組織複雜的系統提示，使其更具可讀性
agent = Agent(
    'gemini-1.5-flash',
    system_prompt=(
        '你是一位專業的 Python 開發者，擅長撰寫乾淨、有效率的程式碼。',
        '當被問到程式設計問題時，請先解釋核心概念，再提供程式碼範例。',
        '請使用繁體中文（台灣用語）進行回覆。'
    )
)

2. 動態生成系統提示

在實務上，我們經常需要根據當下的上下文（Context）、使用者的偏好設定或是資料庫中的狀態來調整系統提示。Pydantic AI 提供了 @agent.system_prompt 裝飾器，讓你可以宣告一個函數來動態產生系統提示。

這個動態產生的函數可以接收依賴項 (Dependencies) 作為參數，藉此獲取外部資料。

from pydantic_ai import Agent, RunContext

# 建立一個 Agent，依賴的型別設定為 str (這裡假設傳入使用者的名字)
agent = Agent('openai:gpt-4o', deps_type=str)

# 使用裝飾器標記這是一個動態產生系統提示的函數
@agent.system_prompt
def add_user_name_to_prompt(ctx: RunContext[str]) -> str:
    # 透過 ctx.deps 取得在執行時傳入的依賴資料 (即使用者名稱)
    return f"這是一位名叫 {ctx.deps} 的使用者提出的問題。請在回覆時稱呼對方的名字，並保持禮貌。"

# 在執行時，透過 deps 參數將具體的值注入到上下文
result = agent.run_sync('請問 HTTP 狀態碼 404 是什麼意思？', deps='小明')
print(result.data)

透過動態系統提示，Agent 變得更加靈活且具備上下文感知能力。

執行 Agent

當 Agent 配置完成後，你可以使用以下三種方法來執行它並取得結果：

  1. run_sync()：同步執行。這會阻塞當前的程式執行序，直到取得完整的模型回應為止。適用於簡單的腳本或不支援非同步的環境。
  2. run()：非同步執行 (Asynchronous)。回傳一個 Coroutine，適用於 FastAPI 或 asyncio 等非同步框架，不會阻塞執行序。
  3. run_stream()：串流執行。回傳一個非同步的生成器 (Async Generator)，適用於需要逐步顯示模型回應內容（如打字機效果）的場景。
import asyncio
from pydantic_ai import Agent

agent = Agent('gemini-1.5-flash')

async def main():
    # 使用非同步的方式執行 Agent
    result = await agent.run('請寫一首關於寫程式的短詩。')
    print(result.data)

# 執行非同步主程式
asyncio.run(main())

掌握了 Agent 的建立與系統提示設定後，你已經跨出了使用 Pydantic AI 的第一步。接下來，我們將進一步探討如何切換不同的底層模型。