함수 도구(Tools) 연결하기

에이전트가 답변만 하는 게 아니라 실제로 계산하거나 외부 시스템을 건드리게 하려면 함수 도구를 연결해야 해요. Pydantic AI에서는 함수에 데코레이터만 붙이면 LLM이 그 함수를 호출할 수 있는 도구가 돼요.

출처: https://ai.pydantic.dev/tools/

기본 아이디어는 간단해요. 그냥 파이썬 함수 하나를 정의하고 @agent.tool만 붙이면, LLM이 답변을 만들면서 필요할 때 그 함수를 호출해서 결과를 받아와요. 도구의 파라미터는 Pydantic이 자동으로 검증하므로, 잘못된 타입이 들어가는 일을 컴파일 타입 수준에서 막을 수 있죠.

함수 도구의 시그니처에 RunContext를 첫 인자로 넣으면 에이전트를 실행할 때 주입한 의존성에도 접근할 수 있어요. 예를 들어 사용자별 설정을 의존성으로 넣어두면, 도구 안에서 그 값을 꺼내 쓰는 식이에요.

from pydantic_ai import Agent, RunContext

agent = Agent('openai:gpt-5.2', deps_type=dict)

@agent.tool
def get_weather(ctx: RunContext[dict], city: str) -> str:
    api_key = ctx.deps['weather_api_key']
    # 이제 city 와 api_key 로 날씨 API 를 호출할 수 있어요
    return f'weather in {city}: sunny'

여기서 ctx.deps가 실행 시점에 주입된 의존성이고, city는 LLM이 스스로 채워 넣는 인자예요. LLM은 도구의 docstring과 시그니처를 보고 어떤 값을 넘겨야 할지 판단하니까, 도구 이름과 설명을 명확히 쓰는 게 중요해요.

도구는 재사용 가능한 번들(Capabilities)로 묶을 수도 있어요. 자주 쓰는 도구 모음을 하나의 capability로 정의해 두면 여러 에이전트에 같은 설정으로 얹을 수 있어요.