Pydantic AI

# Python이 AI를 하는 방법

에이전트, 실시간 음성, 이미지 생성, 임베딩. 모든 모델, 모든 인터페이스, 처음부터 끝까지 타입이 지정됩니다.

Pydantic AI는 Python AI SDK입니다. 타입이 지정되고 확장 가능한 에이전트 루프로, 모든 모델을 문자열 하나로 교체할 수 있습니다. 동일한 에이전트가 필요한 모든 곳에서 실행됩니다: 웹 프론트엔드 뒤에서, 터미널에서, 음성 통화에서, 내구성 있는 백그라운드 큐에서, GitHub Actions에서, 또는 그냥 `run()`을 호출하는 평범한 객체로서. 이미지 생성과 임베딩도 같은 박스에 들어 있습니다.

Pydantic AI Harness는 복잡하고 장시간 실행되는 작업에 에이전트가 필요한 모든 것을 갖추고 있으며, capability로 끼워 넣을 수 있습니다. 메모리, 가드레일, 서브 에이전트부터 계획, 컨텍스트 관리, 영속성에 이르기까지, 완전한 코딩 에이전트까지 포함합니다.

Pydantic Evals는 에이전트의 최종 출력과 도구 호출 궤적을 데이터셋이나 실제 프로덕션 트래픽에서 평가하며, Pydantic Graph는 하나의 에이전트 루프로 충분하지 않을 때 타입이 지정된 제어 흐름을 제공합니다. 둘 다 별도의 오픈소스 패키지이며, 모델 가격을 최신으로 유지하는 genai-prices와 모델이 작성한 코드를 실행하는 샌드박스 Python 인터프리터인 Monty도 마찬가지입니다.

Pydantic Logfire는 LLM 호출뿐 아니라 앱 전체를 보는 AI 엔지니어링 플랫폼이며, Pydantic AI Gateway는 실시간 비용 모니터링과 예산 제어를 갖춘 모든 모델을 위한 하나의 키입니다. 우리의 계측은 순수 OpenTelemetry이므로 이미 운영 중인 어떤 백엔드든 작동합니다.

전체 문서는 pydantic.dev/docs/ai 에서 확인하세요.

## 무엇을 만들고 계신가요?
간단한 타입 지정 데이터 추출부터 복잡하고 장시간 실행되는 멀티 에이전트 협업까지, Pydantic AI와 Pydantic AI Harness가 지원합니다.

### 코딩 에이전트
터미널에서의 완전한 코딩 에이전트: 워크스페이스 루트 기반 파일 접근, 허용 목록 기반 셸, 저장소 파악, 계획, 그리고 긴 세션에서도 살아남는 컨텍스트 관리. 여기에 웹 검색과 두 번째 의견을 주는 어드바이저가 함께 끼워져 있습니다:

```python
uv add pydantic-ai pydantic-ai-harness
from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
from pydantic_ai_harness import Advisor, Coder

agent = Agent(
'anthropic:claude-fable-5-1',
capabilities=[
Coder(), # files, shell, repo context, sub-agents, context management
WebSearch(), # look up docs and error messages on the web
Advisor('openai:gpt-6.1-sol'), # a second opinion from another model when stuck
],
)
agent.to_cli_sync()
```

Coder는 블랙박스가 아닌 일반적인 결합형 capability입니다. 통째로 사용하거나, 그것이 묶고 있는 블록들을 직접 사용할 수 있으며, 둘은 동등합니다:

```python
capabilities=[
FileSystem('.'), Shell(cwd='.'), RepoContext(), SubAgents(...),
ClearToolResults(), ToolOutputLimits(), RepairToolArguments(),
]
```

파일을 실행하면 터미널에서 에이전트와 대화하게 됩니다. 코드를 작성하기 전에 시험해 보려면, 내보낸 `coder_agent`를 `clai`(Pydantic AI CLI)로 `uvx`를 통해 실행하세요:

```bash
uvx --with pydantic-ai-harness clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-fable-5-1
```

이것을 빌드하기 → Coder, Harness에서

GitHub에서 실행하기 → GitHub Agentic Workflows, 이슈, 풀 리퀘스트 또는 스케줄에 따라

### 데이터 추출
에이전트에 출력 타입과 도구를 주면, 모든 실행이 검증되고 타입이 지정된 채로 돌아옵니다:

```python
uv add pydantic-ai
from typing import Literal

from pydantic import BaseModel, Field

from pydantic_ai import Agent, RunContext

class Sentiment(BaseModel):
label: Literal['positive', 'negative', 'neutral']
score: float = Field(ge=-1, le=1)

agent = Agent('openai:gpt-6.1-sol', output_type=Sentiment)

@agent.tool
def recent_reviews(ctx: RunContext, product: str) -> list[str]:
"""Fetch recent review snippets for a product."""
return ['The new release fixed everything I complained about!']

result = agent.run_sync('How are people feeling about the Extract app?')
print(result.output)
#> label='positive' score=0.9
```

`@agent.tool` 함수는 의존성을 담고 있는 `RunContext`를 받습니다. 나머지 시그니처와 docstring은 도구 스키마가 되고, 인자는 코드가 실행되기 전에 검증되며, 실행은 반드시 `Sentiment`를 반환하도록 보장되므로 IDE, 타입 체커, LLM 모두 반환 타입에 동의합니다.

이것을 빌드하기 → Agents, Function Tools, 그리고 Structured Output

### 내구성 있는 워크플로
`TemporalDurability`를 붙이면 동일한 에이전트가 Temporal 워크플로 안에서 내구성 있는 실행으로 동작합니다. 모든 모델 및 도구 호출이 내구성 있는 액티비티가 되므로, 백그라운드 큐를 처리하는 실행이 재시작, 실패, 긴 대기를 견뎌냅니다:

```python
uv add "pydantic-ai[temporal]"
from temporalio import workflow

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebFetch, WebSearch
from pydantic_ai.durable_exec.temporal import PydanticAIWorkflow, TemporalDurability

agent = Agent(
'openai:gpt-6.1-sol',
instructions='Research the topic and write a structured brief.',
name='researcher',
capabilities=[WebSearch(), WebFetch(), TemporalDurability()],
)

@workflow.defn
class ResearchWorkflow(PydanticAIWorkflow):
__pydantic_ai_agents__ = [agent]

@workflow.run
async def run(self, topic: str) -> str:
result = await agent.run(f'Write a brief on: {topic}')
return result.output
```

DBOS와 Prefect도 같은 방식으로 붙으며, 자사 및 공동 유지 관리됩니다. 그 외에 Restate, AWS Lambda, Airflow, Absurd, pgtask 통합도 있습니다.

실행을 저장, 재개, 분기하는 데 엔진이 필요하지 않습니다. Pydantic AI Harness의 `StepPersistence`는 체크포인터처럼 정착된 모든 단계를 선택한 저장소에 스냅샷합니다(Persistence 참조). 엔진은 단계 도중에 충돌한 실행을 복구하기 위한 것입니다.

이것을 빌드하기 → Durable Execution

### 실시간 음성
동일한 에이전트를 도구와 capability를 포함한 라이브 음성 세션에 올리세요:

```python
uv add "pydantic-ai[openai-realtime]"
import asyncio

from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP

agent = Agent(
instructions='You are a helpful voice assistant.',
capabilities=[MCP('https://internal.example.com/mcp')], # capabilities work in voice too
)

@agent.tool_plain
def order_status(order_id: str) -> str:
"""Look up the status of an order."""
return f'Order {order_id}: shipped, arriving Thursday.'

async with agent.realtime('openai:gpt-realtime-2.1').session() as session:
microphone = asyncio.create_task(session.send_audio(microphone_chunks())) # your microphone → the model
speaker = asyncio.create_task(play_audio(session.stream_audio())) # model audio → your speaker
async for part in session.stream_transcripts():
print(f'{part.speaker}: {part.transcript}')
```

모델은 계속 말하면서 대화 중간에 도구를 호출하며, 모든 세션이 계측됩니다. 음성은 OpenAI Realtime, Gemini Live, Azure, xAI Grok Voice에서의 또 다른 프론트엔드일 뿐입니다.

이것을 빌드하기 → Realtime Voice

### 이미지 생성
에이전트 실행 없이 전용 이미지 모델로 이미지를 생성하세요:

```python
uv add pydantic-ai
from pathlib import Path

from pydantic_ai import ImageGenerator

generator = ImageGenerator('openai:gpt-image-2.5-flare')
result = generator.generate_sync('A minimalist logo for a coffee shop called Extract.')
Path('logo.png').write_bytes(result.image.data)
```

이 독립형 이미지 API는 애플리케이션이 결정할 때를 위한 것입니다. 에이전트 실행이 결정할 때는 타입이 지정된 이미지 출력을 위한 `output_type=BinaryImage`를 사용한 프로바이더 네이티브 생성과, 자체적으로 이미지를 생성하지 않는 모델을 위한 폴백을 갖춘 `ImageGeneration` capability가 있습니다.

이것을 빌드하기 → Image Generation

### Logfire에서 첫 실행 확인하기

팁: 이 에이전트들 중 어느 것이든 실행되기 전에 두 줄을 추가하면, 모든 모델 호출과 도구 호출이 Pydantic Logfire에 나타납니다. Logfire는 신용카드가 필요 없는 무료 티어가 있으며, GitHub 계정만으로 가입할 수 있습니다. 먼저 `uvx logfire auth`와 `uvx logfire projects new`를 한 번 실행하거나, 코딩 에이전트에게 Logfire 설정 스킬을 가리켜 대신 하게 하세요. 자세한 내용은 Logfire 가이드에 있으며, 어떤 OpenTelemetry 백엔드든 대신 사용할 수 있습니다.

```python
import logfire

logfire.configure()
logfire.instrument_pydantic_ai()
```

## Pydantic AI를 선택하는 이유

- **어떤 모델이든, 하나의 Python API.** 거의 모든 모델과 프로바이더(OpenAI, Anthropic, Google, Bedrock, Azure AI Foundry, Groq, Mistral, xAI, Ollama 등 수십 개)를 문자열 하나로 교체하거나 Pydantic AI Gateway를 통해 교체할 수 있습니다. 모든 모델을 위한 하나의 키로, 페일오버와 비용 모니터링이 내장되어 있습니다. 어떤 핵심 기능도 한 벤더에 묶여 있지 않습니다.

- **처음부터 끝까지 타입 지정.** 구조화된 출력, 타입이 지정된 의존성 주입, 타입이 지정된 도구: IDE, 타입 체커, 코딩 에이전트 모두가 에이전트가 무엇을 반환하는지 알며, 전체 오류 클래스를 런타임에서 작성 시점으로 옮깁니다. 평범한 제어 흐름으로 충분하지 않을 때, Pydantic Graph는 그래프 기반 워크플로에 동일한 타입 지정을 가져옵니다.

- **느낌이 아닌 측정.** OpenTelemetry 네이티브 계측은 어떤 OTel 백엔드와도 작동합니다. 한 줄로 Pydantic Logfire가 켜져 실시간 디버깅, 트레이싱, genai-prices 기반 비용 추적을 제공합니다. Pydantic Evals는 코드 내 데이터셋이나, 온라인 평가를 통해 실제 프로덕션 트래픽 샘플에 대해 최종 출력과 도구 호출 궤적을 평가합니다.

- **조합 가능한 배터리.** 하나의 프리미티브인 capability는 도구, 지시문, 훅, 모델 설정을 재사용 가능한 단위로 묶습니다. 코어는 MCP와 웹 검색 같은 기본 요소를 제공하고, Harness는 나머지 전부를 제공하며, Coder와 Researcher 같은 완전한 에이전트는 단지 조합된 capability일 뿐입니다. 결합된 방식 그대로 분해됩니다. 또는 YAML/JSON 에이전트 스펙으로 코드를 완전히 건너뛸 수 있습니다.

- **모든 인터페이스.** 하나의 에이전트 정의가 CLI, 내장 웹 채팅, 또는 실시간 음성(OpenAI Realtime, Gemini Live, Azure, xAI Grok Voice)으로 실행됩니다. UI 이벤트 스트림(AG-UI, Vercel AI)이 이를 자체 프론트엔드나 다른 무엇이든 연결합니다. ACP는 이를 에디터 에이전트로 제공하며, GitHub Agentic Workflows는 이슈, 풀 리퀘스트 또는 스케줄에 따라 헤드리스로 실행합니다.

- **내구성 있는 실행.** 여덟 개 엔진에서의 내구성 있는 실행: Temporal, DBOS, Prefect, Restate, AWS Lambda, Airflow, Absurd, pgtask. 처음 다섯 개는 벤더 팀과 공동 유지 관리됩니다. 에이전트는 재시작을 견디고 이미 운영 중인 엔진에서 며칠 동안 실행되며, 휴먼 인 더 루프 승인이 내장되어 있습니다.

- **다른 프레임워크에서 오셨나요?** 비교 문서는 Pydantic AI가 LangChain, Google ADK, Claude Agent SDK 및 일곱 개 더와 어떻게 다른지 보여주며, 마이그레이션 스킬을 통해 코딩 에이전트가 기존 애플리케이션을 이식하게 할 수 있습니다.

- **Pydantic 팀이 만들었습니다.** Pydantic Validation은 OpenAI SDK, Anthropic SDK, Google ADK, LangChain, 그리고 AI 생태계 대부분의 검증 계층입니다(FastAPI가 기반으로 삼은 토대이기도 합니다). Pydantic AI는 그 동일한 느낌을 에이전트에 가져옵니다.

## 종합하기: 은행 지원 에이전트
여러 기능이 함께 작동하는 것을 보여주는 타입이 지정된 지원 에이전트: 의존성 주입, 함수 도구, 구조화된 출력, 고객 컨텍스트를 묶는 재사용 가능한 capability, 그리고 대화가 필요로 할 때만 모델이 로드하는 온디맨드 capability:

```python
from dataclasses import dataclass

from pydantic import BaseModel, Field

from pydantic_ai import Agent, Capability, RunContext

from bank_database import DatabaseConn

@dataclass
class SupportDependencies: # inject any client: DB pools, HTTP APIs, user info
customer_id: int
db: DatabaseConn

class SupportOutput(BaseModel):
support_advice: str = Field(description='Advice returned to the customer')
block_card: bool = Field(description="Whether to block the customer's card")
risk: int = Field(description='Risk level of query', ge=0, le=10)

customer_context = Capability[SupportDependencies]( # a reusable unit of tools + instructions
id='customer-context',
description="Who the customer is and what's on their account.",
)

@customer_context.instructions
async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str:
customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id)
return f"The customer's name is {customer_name!r}"

@customer_context.tool # signatur…