PydanticAI 튜토리얼 - AI agent 쉽게 구현해보기
PydanticAI는 Pydantic의 강력한 타입 검증 능력을 활용한 AI agent 구축 라이브러리입니다. 이 포스팅에서는 PydanticAI를 사용하여 어떻게 agent를 구현할 수 있을지 코드 예시와 함께 자세히 알아봅니다.
최근 AI 분야는 단순히 모델이 이미 학습한 지식에 의존하는 것이 아닌, AI 스스로 필요한 도구들을 사용하여 원하는 정보를 얻고, 심지어 목적을 달성하기 위해 다른 AI 모델들을 활용하는 AI 에이전트(agent) 개발로 관심이 옮겨가고 있습니다. AI agent는 어떻게 구현할 수 있을까요? LangGraph와 같은 라이브러리는 복잡한 워크플로우 관리에 특화된 라이브러리로서 보다 자유도 높은 AI agent 어플리케이션을 구현할 수 있게 하며, CrewAI 같은 프레임워크를 활용하면 조금 더 손쉽게 원하는 작업을 수행할 수 있습니다.
이번 포스팅에서는 데이터 타입 검증을 위한 강력한 라이브러리인 Pydantic 기반의 AI agent 개발 프레임워크인 PydanticAI에 대해 알아보도록 하겠습니다. AI agent 사이의 의사소통을 위해서는 잘 구조화된 입력 및 출력 형식이 필요한데, Pydantic의 간결하고 빠른 타입 검증 시스템을 활용하여 효율적인 개발이 가능해집니다. 그럼, 이제 PydanticAI 사용법을 알아봅시다!
설치
PydanticAI는 pip을 통해 간단히 설치할 수 있습니다.
pip install pydantic-aiuv package manager를 사용하시는 분들은, 아래와 같이 설치할 수 있습니다.
uv add pydantic-aiPydanticAI 주요 개념 - Agent
Agent 클래스는 PydanticAI에서 가장 기본이 되는 클래스이며, 개념적으로 하나의 agent는 아래 컴포넌트를 포함하는 컨테이너라고 보면 됩니다. 각각의 컴포넌트에 대해 하나씩 알아보고, 어떻게 agent를 정의하여 사용할 수 있는지 알아볼까요?
- 시스템 프롬프트 (System prompt)
- 의존성 (Dependencies)
- 구조화된 결과 형식 (Structured result type)
- 도구 (Function tool)
- LLM 모델 및 모델 설정 (LLM model / settings)
시스템 프롬프트(System prompt) 정의 방법 2가지
시스템 프롬프트는 LLM 모델 초기화 시, 모델의 기본적인 행동 양식을 정의하는 프롬프트입니다. 예를 들어, 가장 일반적인 채팅 모델의 system prompt는 "You are a helpful assistant."로 정의해두곤 합니다.
- 정적 시스템 프롬프트(Static system prompt): 시스템 프롬프트 전체가 모델 실행 전에 정의될 수 있는 상황에 사용합니다.
- 동적 시스템 프롬프트(Dynamic system prompt): 정적 시스템 프롬프트와는 달리, 시스템 프롬프트에 "런타임에 정해지는" 요소를 사용하고 싶을 때 동적 시스템 프롬프트를 사용합니다. 예를 들어, 오늘 날짜나 실행하는 사용자 정보를 시스템 프롬프트에 끼워넣고 싶을 때 사용합니다.
정적 시스템 프롬프트 예시
정적 시스템 프롬프트는 아래 예시와 같이, Agent 초기화 시 system_prompt 파라미터를 통해 정의 가능합니다.
from pydantic_ai import Agent
agent = Agent(
"openai:gpt-4o-mini",
system_prompt="You are a helpful assistant",
)
result = agent.run_sync("Where does 'hello world' come from?")
print(result.data)
# 'Hello, World!' originated from the 1972 programming language tutorial in
# the book "The C Programming Language" by Brian Kernighan and Dennis Ritchie.
동적 시스템 프롬프트 예시
시스템 프롬프트 내에 런타임 시 결정되는 요소를 끼워 넣고 싶을 때는, 아래와 같이 (1) 별도의 함수를 두어 원하는 시스템 프롬프트를 리턴하게 하고, (2) 이 함수를 @agent.system_prompt 로 감싸면 됩니다. 예를 들어, 현재 시각을 시스템 프롬프트에 추가하기 위해서는 아래와 같이 하면 됩니다.
from pydantic_ai import Agent
from datetime import datetime
agent = Agent(
"openai:gpt-4o-mini",
)
@agent.system_prompt
def system_prompt():
return f"You are a helpful assistant. The current date and time is {datetime.now()}"
result = agent.run_sync("What is the current date and time?")
print(result.data)
# The current date and time is January 29, 2025, 20:19:10.162546.
의존성(Dependencies)
PydanticAI 프레임워크에서 의존성이란, "Agent 실행 전반에 걸쳐 공유되어 사용될 수 있는 리소스 혹은 컨텍스트"라고 이해하시면 이해가 수월하실 겁니다. 이 의존성 내에는 문자열, 숫자 혹은 임의의 파이썬 오브젝트 등, 어떤 데이터라도 포함될 수 있습니다. 다만, PydanticAI의 철학인 type-safety를 따르기 위해 의존성의 데이터 형식은 미리 정의되어야 합니다. (데이터 형식 정의에는 python dataclass를 사용하면 됩니다.)
예를 들어, 시스템 프롬프트에 현재 사용자의 정보를 추가하고 싶다면
- 먼저
MyDependency와 같이 의존성 데이터 형식을dataclass로 정의하고, Agent초기화 시 데이터 형식deps_type인자로 해당 형식을 넘겨주고,- 해당 의존성을 포함하는
RunContext를 인자로 받는 system prompt를 정의하고, Agent실행 시 (run_sync), 사용자 정보가 포함된 의존성 객체를 넘겨주는 식으로
에이전트 실행 사이클 상에 RunContext 를 통해 자연스러운 의존성 주입이 가능합니다. 아래 예시를 통해 살펴보시죠!
from pydantic_ai import Agent, RunContext
from dataclasses import dataclass
@dataclass
class MyDependency:
name: str
age: int
agent = Agent(
"openai:gpt-4o-mini",
deps_type=MyDependency, # define dependency type
)
@agent.system_prompt
def system_prompt(ctx: RunContext[MyDependency]):
return f"""
You are a helpful assistant for user {ctx.deps.name} who is {ctx.deps.age} years old.
"""
# pass dependency
result = agent.run_sync("Who am I?", deps=MyDependency(name="Bongnam Kim", age=30))
print(result.data)
# You are Bongnam Kim, a 30-year-old individual.
# If you’d like to share more information about yourself, feel free to let me know!
구조화된 결과 형식 (Structured result type)
Pydantic의 데이터 타입 검증을 활용하여 agent의 실행 결과를 원하는 데이터 형식으로 강제하는 것도 가능합니다. Agent 초기화 시 result_type 인자로 데이터 형식을 지정해주면 되는데, 아래의 예시로 손쉽게 확인해볼 수 있습니다.
from pydantic import BaseModel
from pydantic_ai import Agent, RunContext
# define result type
class Area(BaseModel):
area: int
unit: str
# bind two tools
def get_circle_area(radius: float) -> float:
return radius * radius * 3.14
def get_square_area(side: float) -> float:
return side * side
agent = Agent(
"openai:gpt-4o-mini",
result_type=Area, # force result type to be `Area`
system_prompt=("You are a helpful assistant. Always give your answer with the name of the user."),
tools=[get_circle_area, get_square_area],
)
result = agent.run_sync("What is the area of a circle with a radius of 10cm?")
print(result.data.area) # 314
print(result.data.unit) # cm²
result = agent.run_sync("What is the area of a square with a side of 10cm?")
print(result.data.area) # 100
print(result.data.unit) # cm²
원의 넓이와 정사각형의 넓이를 구하는 도구를 쥐어 주고, 결과 타입을 넓이(area)와 단위(unit)으로 구성된 Area 타입으로 강제한 뒤, agent를 실행하자 필요한 도구를 실행하여 알맞게 Area 타입의 오브젝트를 반환하고 있음을 알 수 있습니다.
도구 (Function tools)
지금까지 살펴본 예시의 agent들은 단순한 단일 LLM 요청에 지나지 않았습니다. 하지만 agentic workflow의 진가는 바로 agent가 자체적인 판단에 의해서 필요한 도구들을 사용하여 원하는 기반 정보를 수집하고, 결론을 도출할 수 있다는 것에 있습니다.
이를 위해서 agent에게 필요한 도구들을 쥐어줄 필요가 있습니다(tool binding). PydanticAI에서는 tool binding을 다음의 3가지 방법으로 할 수 있습니다. 각각의 방법의 예시를 보며 알아가보도록 합시다.
@agent.tool데코레이터를 사용하는 방식: 도구 실행이 Dependency와 같은 agent 실행의 context 정보(RunContext)에 접근할 필요가 있을 때 사용합니다.@agent.tool_plain데코레이터를 사용하는 방식: 도구 실행이RunContext에 의존하지 않아도 될 때 사용합니다.tools인자에Tool오브젝트나 함수의 리스트를 넘겨주는 방식: 개별Agent인스턴스 데코레이터에 의존하지 않으므로, 도구 함수의 재사용성이 높아지는 방식입니다.
@agent.tool 데코레이터를 사용하여 tool binding
이 예시는 get_user_name 이라는 도구를 사용하여, 현재 dependency에 저장되어 있는 사용자 이름을 답변과 함께 반환하도록 하는 예시입니다. 아래에 주목해서 코드를 이해해주세요.
str타입의 dependency를 정의하고,run_sync에서 "Bongnam Kim"이라는 형태로 dependency 값을 넘겨주고 있습니다. 이 값을get_user_name함수 내에서ctx.deps로 접근하고 있습니다.- 정적 시스템 프롬프트(static system prompt)로 답변에 항상 사용자의 이름을 포함시키도록 했습니다.
get_user_name함수를@agent.tool데코레이터로 감싸 tool binding 해준 모습입니다.
from pydantic_ai import Agent, RunContext
agent = Agent(
"openai:gpt-4o-mini",
deps_type=str,
system_prompt=("You are a helpful assistant. Answer with the name of the user."),
)
@agent.tool # binds this tool to the object `agent`
def get_user_name(ctx: RunContext[str]) -> str:
"""Get the user's name."""
return ctx.deps
result = agent.run_sync("Hi!", deps="Bongnam Kim")
print(result.data)
# Hello, Bongnam Kim! How can I assist you today?
그 결과, 답변에 Bongnam Kim 이라는 사용자의 이름이 잘 추가된 것을 확인할 수 있습니다.
여기서 궁금해지는 것은, 과연 agent가 get_user_name 이라는 도구를 실제로 실행하여 "Bongnam Kim" 이라는 사용자 이름을 얻어냈는지입니다. 모델의 도구 실행 흐름을 확인해볼 수 있을까요? 가능합니다! result.all_messages() 함수는 ModelRequest 및 ModelResponse로 이루어진 리스트를 반환하는데, 이 리스트는 agent가 어떤 판단을 하여 어떤 도구를 실행했고, 각 도구는 어떤 값을 반환했는지 로그를 담고 있습니다.
[ModelRequest(parts=[SystemPromptPart(content='You are a helpful assistant. '
'Answer with the name of the '
'user.',
dynamic_ref=None,
part_kind='system-prompt'),
UserPromptPart(content='Hi!',
timestamp=datetime.datetime(2025, 1, 29, 12, 19, 34, 232313, tzinfo=datetime.timezone.utc),
part_kind='user-prompt')],
kind='request'),
ModelResponse(parts=[ToolCallPart(tool_name='get_user_name',
args=ArgsJson(args_json='{}'),
tool_call_id='call_WUJCzFb9xoExxDmP0RTYCvmk',
part_kind='tool-call')],
model_name='gpt-4o-mini',
timestamp=datetime.datetime(2025, 1, 29, 12, 19, 34, tzinfo=datetime.timezone.utc),
kind='response'),
ModelRequest(parts=[ToolReturnPart(tool_name='get_user_name',
content='Bongnam Kim',
tool_call_id='call_WUJCzFb9xoExxDmP0RTYCvmk',
timestamp=datetime.datetime(2025, 1, 29, 12, 19, 35, 41514, tzinfo=datetime.timezone.utc),
part_kind='tool-return')],
kind='request'),
ModelResponse(parts=[TextPart(content='Hello, Bongnam Kim! How can I assist '
'you today?',
part_kind='text')],
model_name='gpt-4o-mini',
timestamp=datetime.datetime(2025, 1, 29, 12, 19, 35, tzinfo=datetime.timezone.utc),
kind='response')]위의 로그를 확인해보면, 두 번째 element ModelResponse(parts=[ToolCallPart(tool_name='get_user_name', args=ArgsJson(Args_json='{}'), ... 를 확인할 수 있습니다. 실제로 get_user_name 도구를 실행하고 있다는 걸 알 수 있습니다!
@agent.tool_plain 데코레이터를 사용하여 tool binding
많은 경우 도구 실행에는 RunContext가 필요하지 않습니다. 예를 들어, 아래와 같이 간단한 곱셈을 도와 주는 도구를 agent에 쥐어줬다고 해 봅시다. 이 경우는 딱히 도구가 의존성을 들여다볼 필요가 없지요. 이 경우에는 @agent.tool_plain 데코레이터를 사용하면 됩니다.
from pydantic_ai import Agent
agent = Agent(
"openai:gpt-4o-mini",
system_prompt=("You are a helpful assistant."),
)
@agent.tool_plain
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
result = agent.run_sync("What is 1234 + 5678?")
print(result.data)
# 1234 + 5678 equals 6912.
도구 실행과 관련된 로그를 살펴보면 아래와 같습니다. add 도구를 사용하되, 인자로 a=1234, b=5678 을 넘겨주고 있네요.
ModelResponse(parts=[ToolCallPart(tool_name='add',
args=ArgsJson(args_json='{"a":1234,"b":5678}'),
tool_call_id='call_FyI5w9Y33lY4l9kVrTZC0fsM',
part_kind='tool-call')],
model_name='gpt-4o-mini',
timestamp=datetime.datetime(2025, 1, 29, 12, 31, 48, tzinfo=datetime.timezone.utc),
kind='response'),tools 인자에 Tool 오브젝트나 함수의 리스트를 넘겨주어 tool binding
위의 데코레이터 기반 방법들은 특정 도구가 특정 agent만을 위해 구현되고 사용될 때 효과적입니다. 하지만 많은 경우, 재사용성 관점에서 도구(함수) 구현체는 하나로 유지하고, 여러 agent에서 해당 도구를 가져와 사용하고 싶을 텐데요, 이를 위해 PydanticAI 에서는 데코레이터에 의존하지 않고, 단순히 Agent 초기화 단계에서 tools=[tool1, tool2] 형태로 tool binding을 가능하게 해 두었습니다.
참고로, RunContext에 의존하는 도구를 구현하기 위해서는 도구 함수의 첫 번째 인자가 RunContext[XXX] 타입이어야 함에 주의하세요.
from pydantic_ai import Agent, RunContext
# tool without RunContext
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
# tool with RunContext
def get_user_name(ctx: RunContext[str]) -> str:
"""Get the user's name."""
return ctx.deps
agent = Agent(
"openai:gpt-4o-mini",
deps_type=str,
system_prompt=("You are a helpful assistant. Always give your answer with the name of the user."),
tools=[add, get_user_name],
)
result = agent.run_sync("What is 1234 + 5678?", deps="Bongnam Kim")
print(result.data)
# The result of 1234 + 5678 is 6912, Bongnam Kim.
LLM 모델 및 모델 설정 (LLM model / settings)
PydanticAI는 기본적으로 LLM 모델 타입에 의존하지 않는 model-agnostic 프레임워크입니다. 다시 말해 다양한 LLM 모델을 바꿔끼워가며 agent를 구성할 수 있다는 겁니다. PydanticAI가 지원하는 model provider는 아래와 같습니다.
- OpenAI
- Anthropic
- Gemini (Generative Language API / Vertex API)
- Ollama
- Groq
- Mistral
세팅
PydanticAI 설치 시 pip install pydantic-ai 혹은 uv add pydantic-ai 를 사용했다면, 기본적으로 모든 model provider를 활용할 수 있는 준비가 된 것입니다.
혹시 딱 필요한 만큼의 패키지만 설치하기 위해 pip install pydantic-ai-slim, uv add pydantic-ai-slim 을 사용하셨다면, 각각의 model provider를 사용하기 위해서 pip install pydantic-ai-slim[openai], pip install pydantic-ai-slim[anthropic] 등의 개별 설치가 필요합니다. 설치를 위한 보다 자세한 내용은 PydanticAI 공식 문서를 참고해주세요.
PydanticAI에서 OpenAI 모델 사용하기
- 환경 변수 설정:
export OPENAI_API_KEY='your-api-key' - 사용 예시
from pydantic_ai import Agent
agent = Agent('openai:gpt-4o')PydanticAI에서 DeepSeek V3 사용하기
- 환경 변수 설정:
export DEEPSEEK_API_KEY='your-api-key' - 사용 예시
import os
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
model = OpenAIModel(
'deepseek-chat',
base_url='https://api.deepseek.com',
api_key=os.getenv('DEEPSEEK_API_KEY'),
)
agent = Agent(model)PydanticAI에서 Ollama 모델 사용하기
- 동일 머신에서 Ollama 서버가 구동되고 있는 경우
from pydantic_ai import Agent
agent = Agent('ollama:llama3.2')- Remote Ollama 서버를 사용하고자 하는 경우
from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.ollama import OllamaModel
ollama_model = OllamaModel(
model_name='llama3.2',
base_url='http://192.168.1.74:11434/v1', # remote url
)
agent = Agent(model=ollama_model)기타 옵션
UsageLimits를 사용한 사용량 제한- Agent를 이용한 어플리케이션 구현 시 주의해야 할 점은, agent가 얼마나 많은 API 요청을 할 지 미리 알 수 없다는 점입니다. API 요청 수가 많아지면 과도하게 많은 비용이 발생할 수도 있으므로, 미리 사용량에 제한을 걸어두는 편이 안전합니다.
- PydanticAI 에서는
Agent실행 시usage_limits인자로UsageLimits오브젝트를 넘겨주어 사용량을 제한할 수 있습니다. UsageLimits오브젝트 생성 시request_limit,request_tokens_limit,response_tokens_limit,total_tokens_limit인자를 통해 사용량 항목 별 최대치를 정의할 수 있습니다.- 예를 들어 응답 토큰 수를 10개 미만으로 제한하고 싶다면, 아래와 같이 하면 됩니다. 응답 토큰 수를 초과했다는 에러가 발생하고, 실행이 즉시 종료됩니다.
from pydantic_ai import Agent, RunContext
from pydantic_ai.usage import UsageLimits
agent = Agent(
"openai:gpt-4o-mini",
system_prompt=("You are a helpful assistant."),
)
# tool without RunContext
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
# tool with RunContext
def get_user_name(ctx: RunContext[str]) -> str:
"""Get the user's name."""
return ctx.deps
agent = Agent(
"openai:gpt-4o-mini",
deps_type=str,
system_prompt=("You are a helpful assistant. Always give your answer with the name of the user."),
tools=[add, get_user_name],
)
result = agent.run_sync(
"What is 1234 + 5678?",
deps="Bongnam Kim",
usage_limits=UsageLimits(response_tokens_limit=10)
)
print(result.data)model_settings를 활용한 LLM 모델 실행 파라미터 조절temperature,timeout등 Agent의 근간이 되는 LLM의 실행 파라미터를 조절하고 싶을 수 있습니다. 이 경우, 실행 시model_settings인자를 활용하면 됩니다.
from pydantic_ai import Agent
agent = Agent(
"openai:gpt-4o-mini",
system_prompt=("You are a helpful assistant"),
)
result = agent.run_sync(
"What is the capital of France?",
model_settings={'temperature': 0.0}
)
print(result.data) # The capital of France is Paris.예제: 웹 검색을 활용한 응답
LLM 모델은 기본적으로 모델이 학습된 시점까지의 정보만을 제공할 수 있습니다. 즉, 모델이 학습된 이후에 만들어진 최신 정보에 관해서는 대답해줄 수 없다는 것이죠. 하지만 Agent에게 웹 검색 도구를 쥐어준다면 어떨까요? 최신 정보를 검색한 다음, 해당 검색 결과를 바탕으로 응답을 구성하여 우리에게 보다 나은 응답을 제공할 수 있겠죠! 여기서는 agent에게 duckduckgo 기반의 간단한 웹 검색 도구를 쥐어준 다음, 2025년의 공휴일에는 어떤 것들이 있는지 물어보도록 하겠습니다.
from pydantic_ai import Agent
from duckduckgo_search import DDGS
# simple web search tool using duckduckgo_search
# this may be replaced with Tavily, Perplexity or else
def duckduckgo_search(query: str) -> str:
"""Search the web for the given query."""
with DDGS() as ddgs:
return ddgs.text(query)
agent = Agent(
"openai:gpt-4o-mini",
system_prompt=("You are a helpful assistant."),
tools=[duckduckgo_search],
)
result = agent.run_sync(
"List all the Korean national holidays in 2025."
)
print(result.data)
# Here are the Korean national holidays for 2025:
# 1. **New Year's Day** - January 1, 2025 (Wednesday)
# 2. **Seollal (Lunar New Year)** - January 28, 2025 (Tuesday) to January 30, 2025 (Thursday)
# 3. **Independence Movement Day** - March 1, 2025 (Saturday)
# 4. **Buddha's Birthday** - May 15, 2025 (Thursday)
# 5. **Memorial Day** - June 6, 2025 (Friday)
# 6. **National Liberation Day** - August 15, 2025 (Friday)
# 7. **Chuseok (Korean Harvest Festival)** - September 29, 2025 (Monday) to October 1, 2025 (Wednesday)
# 8. **National Foundation Day** - October 3, 2025 (Friday)
# 9. **Hangeul Day (Korean Alphabet Day)** - October 9, 2025 (Thursday)
# 10. **Christmas Day** - December 25, 2025 (Thursday)
# Please note that some holidays may be adjusted based on the lunar calendar, and there may be substitute holidays if the date falls on a weekend.
# For more detailed information, you can check resources like [Public Holidays Korea](https://publicholidays.co.kr/2025-dates/)
# or the [Korean Calendar site](https://timeanddate.com/holidays/south-korea/2025).
모델이 duckduckgo_search 도구를 어떻게 활용했는지 슬쩍 확인해보면 이렇습니다.
ModelResponse(parts=[ToolCallPart(tool_name='duckduckgo_search',
args=ArgsJson(args_json='{"query":"Korean national holidays 2025'"}'),
tool_call_id='call_VjYGMZzYh5JGSQ2BMR6W7a6f',
part_kind='tool-call')],
model_name='gpt-4o-mini',
timestamp=datetime.datetime(2025, 1, 29, 14, 1, 5, tzinfo=datetime.timezone.utc),
kind='response'),duckduckgo_search('Korean national holidays 2025') 를 사용하여 검색을 시도하고 있음을 알 수 있겠네요.
마치며
이번 포스팅에서는 PydanticAI 라이브러리의 기본 철학과 개념들을 둘러보았습니다. Agent 초기화 시 정적 혹은 동적 시스템 프롬프트를 어떻게 제공하는지, 에이전트 실행 컨텍스트와 의존성을 어떻게 넘겨주는지, 도구를 어떻게 쥐어주는지 정리해 보며 어떻게 agentic framework을 구현할 수 있을지 감이 오셨을까요? PydanticAI에서 제공하는 Agent - RunContext - Tool 사이의 관계에 조금만 익숙해진다면, 다양한 Agentic workflow를 자유롭게 구현해볼 수 있을 것 같습니다. 저도 이 개념들을 바탕으로 마음껏 구현을 시작해 봐야겠습니다! 😊
