서드파티 캐퍼빌리티

서드파티 캐퍼빌리티 (Third-Party Capabilities)

캐퍼빌리티는 서드파티 패키지가 Pydantic AI를 확장하는 권장 방식이에요. 훅·지침·모델 설정과 함께 도구를 묶을 수 있기 때문입니다. 여기서는 커뮤니티에서 만든 다양한 캐퍼빌리티 패키지들이 어떤 일을 하는지 카테고리별로 소개해 드릴게요.

출처: 문서

본문

캐퍼빌리티는 훅, 지침, 모델 설정과 함께 도구를 묶을 수 있으므로 서드파티 패키지가 Pydantic AI를 확장하는 권장 방식이에요. 전체 생태계는 Extensibility를 보세요. 서드파티 툴셋도 캐퍼빌리티로 감쌀 수 있습니다.

아래 사용 사례 중 다수는 Pydantic AI 자체나 공식 캐퍼빌리티 라이브러리인 Pydantic AI Harness가 퍼스트파티로도 제공해요. 그런 경우 내장 옵션을 먼저 소개하고, 커뮤니티 패키지는 대안으로 나열합니다.

작업 관리 (Task Management)

모델 소유의 작업 계획과 진행 추적에는 Pydantic AI Harness의 Planning이 있어요. 캐시 친화적이고 스스로 갱신되는 작업 계획입니다. 하위 작업·의존성·PostgreSQL 영속성을 지원하는 커뮤니티 대안:

  • pydantic-ai-todo — add_todo, read_todos, write_todos, update_todo_status, remove_todo 도구를 가진 TodoCapability. 하위 작업, 의존성, PostgreSQL 영속성을 지원합니다. 더 낮은 수준의 TodoToolset으로도 제공됩니다.

컨텍스트 관리 (Context Management)

Pydantic AI에는 내장 압축 — 공급자 네이티브 API와 모델 무관 히스토리 요약 — 이 있고, Pydantic AI Harness는 압축 전략의 전체 메뉴를 더합니다. 커뮤니티 대안:

  • summarization-pydantic-ai — 긴 대화를 관리하는 네 가지 캐퍼빌리티: ContextManagerCapability (실시간 토큰 추적, 설정 가능한 임계값에서 자동 압축, 큰 도구 출력 잘라내기); SummarizationCapability (LLM 기반 히스토리 압축); SlidingWindowCapability (비용 제로 메시지 정리); LimitWarnerCapability (하드 컨텍스트 한도 전에 곧 끝내라는 힌트 주입). 독립형 history_processors로도 제공됩니다: SummarizationProcessor, SlidingWindowProcessor, LimitWarnerProcessor.

멀티 에이전트 오케스트레이션 (Multi-Agent Orchestration)

Pydantic AI는 멀티 에이전트 패턴을 직접 지원하고, Pydantic AI Harness의 SubAgents는 자족적인 작업을 이름 붙은 자식 에이전트에 위임합니다. 커뮤니티 대안:

  • subagents-pydantic-ai — SubAgentCapability는 멀티 에이전트 위임 도구를 더합니다: task (서브에이전트 생성), check_task, wait_tasks, list_active_tasks, soft_cancel_task, hard_cancel_task, answer_subagent. sync·async·자동 실행 모드, 중첩 서브에이전트, 런타임 에이전트 생성을 지원합니다. create_subagent_toolset을 통해 더 낮은 수준의 툴셋으로도 제공됩니다.

가드레일과 안전 (Guardrails & Safety)

Pydantic AI Harness는 요청·응답을 검증하거나 차단하는 입력/출력 가드레일을 제공하고, Pydantic AI는 UsageLimits로 사용량·토큰·요청 한도를 강제해요. USD 비용 추적까지 포함한 여러 기성 쉴드를 묶은 커뮤니티 대안:

  • pydantic-ai-shields — 바로 쓰는 가드레일 캐퍼빌리티: CostTracking (런당 토큰 사용량과 USD 비용 추적, 예산 초과 시 BudgetExceededError 발생); ToolGuard (특정 도구 차단 또는 승인 요구); InputGuard·OutputGuard (커스텀 sync/async 검증 함수); PromptInjection, PiiDetector, SecretRedaction, BlockedKeywords, NoRefusals 콘텐츠 쉴드.

파일 연산과 샌드박싱 (File Operations & Sandboxing)

Pydantic AI Harness는 샌드박스된 FileSystem과 Shell 캐퍼빌리티, 그리고 도구 호출을 샌드박스 Python으로 실행하는 CodeMode를 제공합니다. 커뮤니티 대안:

  • pydantic-ai-backend — ConsoleCapability는 ls, read_file, write_file, edit_file, glob, grep, execute 도구를 세밀한 권한 시스템과 함께 등록합니다. 백엔드: StateBackend (인메모리, 테스트용), LocalBackend (실제 파일시스템), DockerSandbox (격리 컨테이너 실행), CompositeBackend (백엔드 간 라우팅). 더 낮은 수준의 ConsoleToolset으로도 제공됩니다.

에이전트 스킬 (Agent Skills)

Pydantic AI는 온디맨드 캐퍼빌리티를 통해 Agent Skills를 네이티브로 지원하며, 모델이 로드할 때까지 스킬을 한 줄 카탈로그 항목으로 축소합니다. 커뮤니티 대안:

  • pydantic-ai-skills — SkillsCapability는 점진적 공개(progressive disclosure)로 Agent Skills 지원을 구현합니다 (토큰을 줄이기 위해 온디맨드 로드). 파일시스템 및 프로그래매틱 스킬을 지원하며 agentskills.io와 호환됩니다.

데이터와 분석 (Data & Analytics)

구조화된 데이터를 조회·분석하는 캐퍼빌리티는 에이전트가 파일과 데이터베이스 위에서 질문에 답하도록 돕습니다:

  • pydantic-ai-chdb — ChDBCapability는 인프로세스 ClickHouse 엔진인 chDB로 로컬 파일(Parquet/CSV/JSON), 객체 스토리지, 원격 데이터베이스 위에서 분석 SQL을 제공합니다 — 엔진 자체는 서버나 연결 문자열 없이 실행됩니다 (원격 소스는 ClickHouse 테이블 함수로 접근하며 각각 자체 자격 증명을 사용). run_select_query (파라미터 바인딩이 있는 읽기 전용 ClickHouse SQL), list_databases, list_tables, describe_table, get_sample_data, list_functions, attach_file (옵트인 쓰기 세션) 도구와 스키마 우선 지침을 등록합니다. 세션은 기본적으로 엔진 수준 readonly=2 설정에 결과 상한을 두고, 타입 있는 엔진 오류는 ModelRetry로 매핑되어 모델이 쿼리를 고칠 수 있어요. 에이전트 스펙과 기본 호환되므로 from_spec / Agent.from_spec으로 로드할 수 있고, ChDBCapability(...).get_toolset()을 통한 낮은 수준 툴셋도 제공합니다.

검색과 RAG (Retrieval & RAG)

Pydantic AI는 RAG 예제에서 검색 패턴을 보여주는데, 벡터 데이터베이스에 검색 도구를 등록합니다. 다음 커뮤니티 패키지들은 이 패턴의 재사용 가능한 구현을 캐퍼빌리티로 제공하며, 인용 처리와 지침과 함께 검색 도구를 묶습니다:

  • haiku.rag — 임베디드 LanceDB를 뒷받침하는 Pydantic AI 에이전트용 로컬 우선 문서 RAG로, 데이터베이스 서버가 필요 없어요. RAGCapability는 하이브리드 벡터·전문(full-text) 검색, 선택적 재랭킹, 구조 인식 컨텍스트 확장, 페이지 번호와 섹션 제목 인용을 제공합니다. 각 문서의 DoclingDocument 구조가 보존되며, 컨텍스트 확장과 페이지·섹션 인용이 이것을 대상으로 해석됩니다. 검색된 그림은 비전 가능 모델에 이미지로 전달되고, 멀티모달 임베더와 함께라면 텍스트 벡터 공간을 공유하므로 텍스트 쿼리로 그림을 검색하거나 이미지를 쿼리로 쓸 수 있어요. 말뭉치에 걸친 계산이 필요한 질문에는 AnalysisCapability가 검색·인용과 모델이 작성한 파이썬을 Monty 샌드박스의 가상 문서 파일시스템 위에서 실행하는 것을 결합합니다. EvidenceCompactionCapability는 이전에 인용된 증거는 유지하면서 인용되지 않은 이전 검색 결과는 대체해 멀티턴 요청을 작게 유지하고, CitationPolicyCapability는 답변이 무엇에 근거하는지 명시적으로 선언하도록 요구합니다. 검색·분석 캐퍼빌리티는 지연 로딩을 지원합니다. 이 패키지는 create_search_toolset()과 create_document_toolset()을 통한 낮은 수준 툴셋도 제공합니다.

이 페이지에 패키지를 추가하려면 풀 리퀘스트를 열어 주세요.

자신의 캐퍼빌리티 패키지를 배포하려면 Publishing capabilities와 Extensibility를 참고하세요.

더 알아보기 (Learn more)