#crewai#pydantic#structured-output#python

CrewAI 구조화 출력: Pydantic으로 데이터 흔들림 막기

3 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 형식)
  • 후속 Task는 문체가 아니라 필드에 의존

초보가 자주 하는 실수

  1. Pydantic이 있으면 expected_output이 필요 없다고 생각함
  2. 필드가 너무 적어서 정보가 부족함
  3. 필드가 너무 많고 세밀해서 누락이 늘어남

⚠️ 먼저 핵심 3~5개 필드로 시작하고, 필요할 때 확장하세요.

다음 단계

단일 Crew 출력 안정화가 됐으니, 다음은 멀티 Crew 조율입니다.
👉 Flow 입문