Pydantic AI Docs

Pydantic AI Docs

이 문서에서는 PydanticAIDocs capability를 소개해요. 에이전트에 read_pyai_docs(topic)라는 단일 도구를 제공하며, 이 도구가 Pydantic AI 문서 페이지를 찾아 그대로 반환해요. 앞에서 컨텍스트에 아무것도 묶지 않아요. 각 호출은 구성된 로컬 체크아웃에서 주제를 먼저 해석하고, 없으면 pydantic/pydantic-ai:main에서 페이지를 가져와요.

출처: 문서

본문

PydanticAIDocs는 에이전트에 read_pyai_docs(topic)이라는 단일 도구를 제공하며, Pydantic AI 문서 페이지를 찾아 그대로 반환해요. 앞에서 컨텍스트에 아무것도 묶지 않아요. 각 호출은 구성된 로컬 체크아웃에서 주제를 먼저 해석한 뒤, 없으면 pydantic/pydantic-ai:main에서 페이지를 가져와요. 그래서 로컬 체크아웃이 있든 없든 동작해요(원격 폴백은 네트워크 액세스가 필요해요).

소스

Pydantic AI Harness가 0.x 릴리스인 동안에는 minor 릴리스 사이에 API가 바뀔 수 있어요. 그럴 때는 deprecation 경고와 릴리스 노트 마이그레이션 안내가 (당신이나 당신의 에이전트에게) 정확히 업그레이드 방법을 알려줘요. 버전 정책을 참고하세요.

The problem

Pydantic AI capability, hooks, 도구, 툴셋을 저작하는 에이전트는 해당 API에 대한 현재 문서가 필요해요. 문서를 시스템 프롬프트에 미리 로드하면 에이전트가 전체적으로 거의 필요로 하지 않는 컨텍스트를 소모하고, main에서 표류하는 스냅샷을 고정해요.

The solution

PydanticAIDocs는 read_pyai_docs(topic)이라는 하나의 도구를 노출하며, 요청된 페이지를 찾아 그대로 반환해요. 각 호출은 구성된 로컬 체크아웃에서 주제를 먼저 해석한 뒤, 없으면 pydantic/pydantic-ai:main에서 페이지를 가져와요. 그래서 로컬 체크아웃이 있든 없든 동작해요(원격 폴백은 네트워크 액세스가 필요해요).

사용 가능한 주제는 capabilities, hooks, tools, tools-advanced, toolsets, agent이에요.

Usage

PydanticAIDocs()를 capabilities에 넣어 Agent를 구성하세요. local_docs_path를 로컬 Pydantic AI 문서 체크아웃에 지정하면 먼저 디스크에서 읽고, 생략하면 항상 원격 소스에서 가져와요:

from pathlib import Path

from pydantic_ai import Agent
from pydantic_ai_harness import PydanticAIDocs

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[PydanticAIDocs(local_docs_path=Path('~/pydantic/ai/base/docs').expanduser())],
)

result = agent.run_sync('Read the toolsets docs, then explain how to build a FunctionToolset.')
print(result.output)

이 capability는 또한 read_pyai_docs 도구가 존재한다는 것과, Pydantic AI capability, hook, 도구, 툴셋을 저작하거나 수정하기 전에 메모리에 의존하는 대신 관련 주제를 읽으라는 짧은 정적 지침을 추가해요. 이 지침은 캐시 안정적이라 턴 사이에 프롬프트 캐시 접두사를 무효화하지 않아요.

Resolution order

각 호출은 이 순서로 해석돼요:

1. 로컬 체크아웃 -- local_docs_path(또는 PYDANTIC_AI_HARNESS_DOCS_PATH 환경 변수)가 설정되고 {path}/{topic}.md가 존재하면 그 파일을 읽어 반환.
2. 원격 가져오기 -- 그렇지 않으면 https://raw.githubusercontent.com/pydantic/pydantic-ai/main/docs/{topic}.md에서 페이지를 가져옴.
3. 둘 다 해석 실패 -- 시도한 로컬 경로와 URL을 명명하는 설명적 오류.

이 capability는 절대 git을 실행하지 않아요. 로컬 체크아웃을 직접 최신으로 유지하세요. 원격 경로는 항상 main을 읽으므로 신선한 폴백이에요.

local_docs_path는 PYDANTIC_AI_HARNESS_DOCS_PATH 환경 변수보다 우선해요. 둘 다 ~가 확장되므로, 원시 ~/... 경로는 조용히 원격 소스로 폴스루하는 대신 로컬 체크아웃으로 해석돼요. 둘 다 설정하지 않으면 모든 호출이 곧바로 원격 소스로 갑니다.

Configuration

Option

Default

Purpose

local_docs_path

None

먼저 읽을 로컬 pyai 문서 체크아웃. PYDANTIC_AI_HARNESS_DOCS_PATH 환경 변수, 그 다음 원격 소스로 폴백.

cache

True

capability 수명 동안 반환된 각 문서를 in-process로 memoize해서, 주제가 최대 한 번 읽히거나 가져와짐.

캐싱은 capability 인스턴스에 살며 그것이 만드는 툴셋들에 걸쳐 공유되므로, memoize된 주제는 같은 PydanticAIDocs를 재사용하는 여러 에이전트 실행을 넘어 생존해요. cache=False로 설정하면 매 호출마다 다시 읽거나 가져와요 — 장수하는 capability 아래에서 로컬 체크아웃이 바뀔 때 유용해요.

Agent spec (YAML/JSON)

PydanticAIDocs는 에이전트를 YAML이나 JSON으로 정의하는 Pydantic AI의 agent spec 기능과 함께 동작해요. 직렬화 이름은 PydanticAIDocs예요:

# agent.yaml
model: anthropic:claude-sonnet-4-6
capabilities:
  - PydanticAIDocs: {}

from pydantic_ai import Agent
from pydantic_ai_harness import PydanticAIDocs

agent = Agent.from_file('agent.yaml', custom_capability_types=[PydanticAIDocs])
result = agent.run_sync('...')
print(result.output)

spec 로더가 PydanticAIDocs를 인스턴스화하는 방법을 알도록 custom_capability_types를 전달하세요.

PyaiDocs로 이름이 바뀌기 전에 저장된 spec은 이전 블록 이름을 사용해요. 계속 로드하려면 deprecate된 PyaiDocs 클래스(pydantic_ai_harness.docs에서 import되며 deprecation 경고를 발생)를 PydanticAIDocs와 함께 또는 대신 전달하세요 — PyaiDocs 직렬화 이름을 유지해요. 마이그레이션하려면 PydanticAIDocs로 다시 저장하세요.

API reference

PydanticAIDocs

Bases: AbstractCapability[AgentDepsT]

요청 시 Pydantic AI 문서를 찾아 반환.

단일 read_pyai_docs(topic) 도구를 노출해요. 문서는 요청될 때 찾아 반환되며, 절대 컨텍스트에 묶이지 않아요. 각 호출은 구성된 로컬 체크아웃에서 주제를 먼저 해석한 뒤 pydantic/pydantic-ai:main에서 페이지를 가져오므로 어떤 환경에서도 동작해요.

로컬 체크아웃 경로는 local_docs_path에서 오며, 설정되지 않았으면 PYDANTIC_AI_HARNESS_DOCS_PATH 환경 변수에서 와요. 둘 다 없으면 모든 호출이 곧바로 원격 소스로 갑니다. 이 capability는 절대 git을 실행하지 않아요 — 로컬 체크아웃을 직접 최신으로 유지하세요. 원격 경로는 항상 main을 읽어요.

from pathlib import Path

from pydantic_ai import Agent
from pydantic_ai_harness.pydantic_ai_docs import PydanticAIDocs

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[PydanticAIDocs(local_docs_path=Path('~/pydantic/ai/base/docs').expanduser())],
)

Attributes

local_docs_path

먼저 읽을 로컬 pyai 문서 체크아웃. None이면 PYDANTIC_AI_HARNESS_DOCS_PATH 환경 변수, 그 다음 원격 소스로 폴백.

Type: Path | None Default: None

cache

True이면 반환된 각 문서를 capability 수명 동안 in-process로 memoize해서 주제가 최대 한 번 읽히거나 가져와짐.

Type: bool Default: True

Methods

get_instructions

def get_instructions() -> AgentInstructions[AgentDepsT] | None

docs 도구 사용에 대한 정적이고 캐시 안정적인 안내.

Returns

AgentInstructions[AgentDepsT] | None

get_toolset

def get_toolset() -> AgentToolset[AgentDepsT] | None

해석된 로컬 경로와 공유 캐시 위에 read_pyai_docs를 제공하는 툴셋.

Returns

AgentToolset[AgentDepsT] | None

get_serialization_name

@classmethod

def get_serialization_name(cls) -> str | None

agent-spec 지원용 직렬화 이름.

Returns

str | None

더 알아보기 (Learn more)

• pydantic-ai-harness 문서