확장성

확장성 (Extensibility)

Pydantic AI는 확장을 염두에 두고 설계됐어요. Capabilities가 1차 확장 지점인데요. 도구·라이프사이클 훅·지시문·모델 설정을 하나의 재사용 단위로 묶어서 에이전트 간에 공유하고, 라이브러리로 패키징하며, 스펙 파일에서 로드할 수 있게 해 줍니다.

출처: 문서

본문

Capabilities 외에도 Pydantic AI는 특수한 요구를 위한 몇 가지 다른 확장 메커니즘을 제공해요.

Capabilities

Capabilities는 Pydantic AI를 확장하는 권장 방법이에요. 다음 경우에 유용합니다:

  • 팀 — 재사용 가능한 내부 에이전트 컴포넌트(가드레일, 감사 로깅, 인증) 구축
  • 패키지 작성자 — 모델과 에이전트를 가로질러 동작하는 확장 배포
  • 커뮤니티 기여자 — 흔한 문제에 대한 해결책 공유

Capabilities의 사용과 구축은 Capabilities, 가벼운 데코레이터 기반 접근법은 Hooks를 참고하세요.

팁

Capability를 기여하려면 pydantic-ai가 아니라 Pydantic AI Harness에 이슈를 열어 주세요. 대부분의 capability는 harness에 속해요. 구분은 What goes where?를 참고하세요.

capability 패키지 배포하기 (Publishing capability packages)

Capability를 설치 가능하게 만들고 에이전트 스펙에서 쓰려면:

  1. get_serialization_name() 구현 — 기본값은 클래스 이름이에요. 스펙 지원에서 제외하려면 None을 반환하세요.
  2. from_spec() 구현 — 기본값은 cls(*args, **kwargs)예요. 생성자가 직렬화 불가능한 타입을 받을 때 오버라이드하세요.
  3. 패키지 이름 — 사용자가 패키지를 찾을 수 있도록 pydantic-ai- 프리픽스를 쓰세요 (예: pydantic-ai-guardrails).
  4. 등록 (Registration) — 사용자는 Agent.from_spec 또는 Agent.from_file의 custom_capability_types로 커스텀 capability 타입을 넘겨요.
from pydantic_ai import Agent

from my_package import MyCapability

agent = Agent.from_file('agent.yaml', custom_capability_types=[MyCapability])

구현 상세는 스펙의 커스텀 capabilities를 참고하세요.

Pydantic AI Harness

Pydantic AI Harness는 Pydantic AI의 공식 capability 라이브러리예요. 메모리·가드레일·컨텍스트 관리 같은 독립형 capability가 코어가 아니라 여기에 있어요. 전체 분류는 What goes where?, capability 매트릭스로 바로 가려면 그 링크를 참고하세요.

서드파티 생태계 (Third-party ecosystem)

Capabilities

Capabilities는 훅·지시문·모델 설정과 함께 도구를 묶어야 하는 패키지의 권장 확장 메커니즘이에요. 커뮤니티 패키지는 서드파티 capabilities를 참고하세요.

Toolsets

많은 서드파티 확장이 toolsets로 제공되며, 훅·지시문·모델 설정을 활용하기 위해 capabilities로 감쌀 수도 있어요. 전체 목록은 서드파티 toolsets를 참고하세요.

다른 확장 지점 (Other extension points)

커스텀 toolsets (Custom toolsets)

특수한 도구 실행 요구(커스텀 전송, 도구 필터링, 실행 래핑)를 위해 AbstractToolset을 구현하거나 WrapperToolset을 서브클래스하세요:

  • AbstractToolset — 도구 정의·실행에 대한 전체 제어
  • WrapperToolset — 래핑된 toolset에 위임, 특정 메서드 오버라이드

상세는 커스텀 Toolset 구축을 참고하세요.

팁

Toolset이 지시문·모델 설정·훅도 제공해야 한다면, 대신 커스텀 capability를 만드는 걸 고려해 보세요.

커스텀 모델 (Custom models)

Pydantic AI가 아직 지원하지 않는 모델 프로바이더에 연결하려면 Model을 구현하세요:

  • Model — 모델 구현의 베이스 인터페이스
  • WrapperModel — 래핑된 모델에 위임, 계측(instrumentation)이나 변환 추가에 유용

상세는 커스텀 모델을 참고하세요.

커스텀 에이전트 (Custom agents)

커스텀 에이전트 동작을 위해 AbstractAgent 또는 WrapperAgent를 서브클래스하세요:

  • AbstractAgent — 에이전트 구현의 베이스 인터페이스. run, run_sync, run_stream 제공
  • WrapperAgent — 래핑된 에이전트에 위임, 전/후 처리나 컨텍스트 관리 추가에 유용

더 알아보기 (Learn more)