#crewai#pydantic#structured-output#python

CrewAI 結構化輸出：用 Pydantic 讓資料不再漂移

2 min read

如果你有遇過「同一個 Task 這次回 markdown、下次回散文」，你不是一個人。
解法很直接：用 Pydantic 定義輸出格式。

為什麼要結構化輸出？

  • 下游 Task 讀得到固定欄位
  • 不用每次寫脆弱的字串解析
  • 失敗時可以更早發現（欄位不符直接報錯）

這就像 API 契約，有規格才有穩定協作。

建立輸出模型

from pydantic import BaseModel, Field
 
class Finding(BaseModel):
    title: str = Field(description="Finding title")
    summary: str = Field(description="Brief explanation")
    source: str = Field(description="Reference URL")
 
class ResearchReport(BaseModel):
    topic: str = Field(description="Topic name")
    findings: list[Finding] = Field(description="Key findings list")
    conclusion: str = Field(description="Final conclusion")

在 Task 使用 output_pydantic

from crewai import Task
 
research_task = Task(
    description="Research AI observability tools in 2026.",
    expected_output="Structured research result.",
    output_pydantic=ResearchReport,
)

跑完後你可以用穩定欄位存取資料，而不是靠字串猜測。

建議搭配寫法

  • 在 expected_output 仍清楚描述內容品質
  • 指定欄位語意（summary 要多長、source 要什麼格式）
  • 下游任務只依賴欄位，不依賴敘述語氣

新手常見誤區

  1. 以為有 Pydantic 就不用寫 expected_output
  2. 模型欄位太少，導致資訊不足
  3. 欄位太多太細，模型反而容易漏填

⚠️ 建議先從 3-5 個關鍵欄位開始，夠用再擴。

下一步

你已經能讓單一 Crew 穩定輸出，接著來看多 Crew 協作。
👉 Flow 入門