🐍03. Function Tools와 Built-in Tools

좋은 에이전트는 말을 잘하는 모델보다, 필요한 순간에 정확한 도구를 부르는 구조에서 나옵니다. PydanticAI는 @agent.tool로 함수 도구를 등록하고, 내장/공통 도구를 조합해 확장할 수 있습니다.

AI 활용 안내: 이 문서는 생성형 AI를 활용해 작성했으며, Pydantic AI 공식 문서를 1차 출처로 검토해 정리했습니다.

공식문서 흐름 점검 (개요 보완)

• 흐름: Function Tool 등록(@agent.tool/agent 인자) → Tool Schema/Output 이해 → Built-in Tool 선택 기준(지원 provider/설정) → Common Tool 확장.
• 이번 편에서 빠지면 안 되는 포인트:
  • 도구 등록 방식 2가지(Decorator vs Agent argument)를 비교한다.
  • Tool schema/docstring이 호출 정확도에 미치는 영향을 명시한다.
  • Built-in 도구는 provider 지원 범위를 먼저 확인하도록 안내한다.
• 공식 문서 체크 링크:
  • https://ai.pydantic.dev/tools/index.md
  • https://ai.pydantic.dev/builtin-tools/index.md
  • https://ai.pydantic.dev/common-tools/index.md

도구 설계의 기본 원칙

• Tool 하나는 역할 하나만 맡긴다
• 인자는 좁고 명확하게 선언한다
• docstring으로 도구 설명을 정확히 남긴다

공식 문서:

• Function Tools: https://ai.pydantic.dev/tools/
• Built-in Tools: https://ai.pydantic.dev/builtin-tools/

flowchart LR
  A[사용자 질문] --> B[모델 판단]
  B --> C{도구 필요?}
  C -->|예| D[Tool 호출]
  D --> E[검증된 결과 반환]
  E --> F[최종 답변]
  C -->|아니오| F

미니 사례 A: 검색 도구 하나에 모든 역할을 몰아넣은 경우

검색, 요약, 필터링을 한 도구에 넣었더니 호출 인자가 비대해지고 실패 원인 파악이 어려워졌습니다. search_raw와 summarize_hits로 분리하자 디버깅이 빨라졌습니다.

미니 사례 B: docstring이 모호해 호출 품질이 떨어진 경우

“데이터 조회” 같은 추상 설명은 모델이 잘못된 인자를 넣기 쉬웠습니다. docstring에 파라미터 의미를 구체화하니 재시도 횟수가 줄었습니다.

실무 적용 순서

1. 현재 업무에서 자동화 가치가 큰 동작 2개 선정
2. 각 동작을 독립 Tool 함수로 분리
3. 각 도구의 실패 조건/예외 메시지 정의
4. 샘플 질문 5개로 호출 로그 확인

성공 판정:

• 도구별 실패 원인을 구분할 수 있다
• 불필요한 다기능 도구가 사라졌다
• 호출 로그만 봐도 문제 위치를 찾을 수 있다

다음 글

• 🐍04. 메시지 히스토리·Retry·에러 복원
• 🐍02. Agent 타입안전: deps와 output 설계
• 🐍 PydanticAI 허브