Advisor

실행자(executor) 모델이 답하거나 결정에 들어가기 전에 별도의 어드바이저(advisor) 모델을 상담할 방법을 줘요.

Pydantic AI Harness가 0.x 릴리스인 동안 API는 마이너 릴리스 사이에 바뀔 수 있어요. 바뀔 때는 폐기 경고와 릴리스 노트 마이그레이션 안내가 정확히 어떻게 업그레이드할지 알려줘요. 버전 정책 참고.

출처: 문서

본문

사용법 (Usage)

첫 번째 인자로 어드바이저 모델을 넘기세요. 모델은 Pydantic AI가 받아들이는 어떤 모델 이름이나 모델 인스턴스든 될 수 있어요:

from pydantic_ai import Agent
from pydantic_ai_harness import Advisor

agent = Agent(
    'openai:gpt-5.4',
    capabilities=[
        Advisor(
            'anthropic:claude-opus-4-8',
            max_uses=1,
            max_tokens=4096,
        )
    ],
)

result = agent.run_sync(
    'Design a zero-downtime database migration. Consult the advisor before choosing a plan.'
)
print(result.output)

실행자가 언제 상담할지 결정해요. 상담이 필요할 때 사용자 프롬프트나 에이전트 지시문에서 명시적으로 물어보게 하세요.

구조화된 답 (Structured answers)

output_type을 Pydantic AI Agent에 넘길 출력 명세 — Pydantic 모델, 스칼라 타입, NativeOutput(...) 같은 — 로 설정하세요. 기본값은 str이에요. 어드바이저 모델은 선택한 출력 모드를 지원해야 합니다.

프로바이더 네이티브 어드바이저 도구는 출력 스키마를 받지 않아요. 그래서 기본이 아닌 output_type은 auto 모드에서 로컬 실행을 선택하고, mode='native'와 결합하면 ValueError가 발생해요.

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai_harness.advisor import Advisor


class Decision(BaseModel):
    proceed: bool
    risk_score: float


agent = Agent(
    'openai:gpt-5.4',
    capabilities=[Advisor('openai:gpt-5.4', output_type=Decision)],
)

성공한 상담은 문자열 표현이 아니라 검증된 객체를 도구 결과로 반환해요. 로컬 어드바이저의 지시문은 산문 대신 구성된 출력 형식을 요청하고, 도구 설명은 실행자에게 검증된 답을 기대하라고 알려줘요. max_uses를 초과하면 구조화된 답 대신 여전히 한도 메시지를 반환해요.

프로바이더 적응 (Provider adaptation)

Advisor는 두 실행 경로를 통해 하나의 논리 도구를 노출해요:

네이티브: 실행자와 어드바이저가 모두 호환되는 Anthropic 프로바이더에 있거나 모두 OpenRouter를 쓰면, Pydantic AI의 프로바이더 네이티브 AdvisorTool이 상담을 실행해요.
로컬 폴백: 그 외의 모든 조합은 advisor 함수 도구를 얻어요. 호출하면 구성된 어드바이저 모델로 별도의 Pydantic AI 에이전트를 실행해요.

기본 auto 모드에서 네이티브 선택은 보수적이에요. capability는 실행자와 어드바이저가 프로바이더를 공유할 때만 명시적 프로바이더 한정 모델 이름을 재사용하므로, Anthropic 모델 ID가 OpenRouter 카탈로그 슬러그에 어떻게 매핑되는지 추측하지 않아요. 예를 들어:

from pydantic_ai_harness import Advisor

# Native for an Anthropic executor; local for OpenAI, Google, and other executors.
anthropic_advisor = Advisor('anthropic:claude-opus-4-8')

# Native for an OpenRouter executor.
openrouter_advisor = Advisor('openrouter:anthropic/claude-opus-4.8')

Model 인스턴스를 넘기면 auto 모드에서 로컬 실행을 선택해요. 이는 그 인스턴스의 프로바이더·클라이언트·자격 증명·베이스 URL·계측을 보존해요. 문자열 모델 이름은 로컬 실행이 선택될 때만 해석되므로, 네이티브 상담은 실행자 프로바이더의 기존 구성을 사용해요.

Pydantic AI의 해석된 실행자 모델 프로파일이 최종 지원 결정을 내려요. 네이티브 도구를 지원하지 않는 클라이언트나 모델은 로컬 폴백을 사용해요.

옵션 (Options)

옵션	기본	동작
`model`	필수	어드바이저 모델 이름 또는 `Model` 인스턴스
`mode`	`'auto'`	실행 정책: `'auto'`, `'native'`, `'local'`
`output_type`	`str`	로컬 어드바이저 출력 명세. 기본 아닌 값은 로컬 실행 필요
`max_uses`	`None`	한 실행자 모델 요청에서 최대 상담 수. 최소 `1`
`max_tokens`	`None`	각 상담의 최대 출력 토큰. 최소 `1024`
`caching`	`None`	Anthropic 네이티브 프롬프트 캐시 TTL: `'5m'` 또는 `'1h'`
`forward_history`	`False`	완료된 실행자 메시지 히스토리를 로컬 상담에 전달

상담이 실행자 프로바이더 안에 머물러야 하면 mode='native'를, 구성된 어드바이저 프로바이더가 별도 요청을 받아야 하면 mode='local'을 쓰세요. 네이티브 모드는 anthropic:<model> 또는 openrouter:<model> 문자열과 같은 프로바이더의 실행자가 필요해요. 실행자가 지원이 없을 때 폴백하지 않아요.

max_uses는 Anthropic 네이티브 도구와 같은 요청별 범위를 가져요. 인자가 검증되는 호출만 이 할당량을 소비해요. 실행자가 다음 모델 요청을 할 때 리셋돼요. OpenRouter는 네이티브 max_uses를 무시하므로, 이 옵션이 설정되면 auto 모드가 로컬 폴백을 선택해요. OpenRouter + mode='native' + max_uses 조합은 거부됩니다.

caching은 기회주의적 Anthropic 네이티브 최적화예요. OpenRouter와 로컬 폴백에는 동등한 제어가 없어요.

forward_history는 명시적으로 선택했든 auto 폴백이든 로컬 실행 경로에만 영향을 줘요. 네이티브 도구 구성이나 네이티브-대-로컬 선택은 바꾸지 않아요. 활성화되면 로컬 어드바이저는 현재 응답 전의 완료된 실행자 메시지 히스토리를 받아요. 현재 응답은 부분 텍스트와 해결되지 않은 도구 호출을 포함해 전달되지 않으므로, 상담 프롬프트는 여전히 완전한 현재 질문을 담아야 해요.

문자열 모델 구성은 custom_capability_types에 Advisor를 넘겨 YAML 또는 JSON 에이전트 스펙에서 로드할 수 있어요. 런타임 Model 인스턴스와 커스텀 출력 명세는 Python 전용으로 남아요.

어드바이저에게 전달되는 컨텍스트 (Context passed to the advisor)

컨텍스트는 실행 경로에 따라 달라져요:

경로	어드바이저 컨텍스트
Anthropic 네이티브	프로바이더가 시스템 지시문·도구 정의·이전 턴과 결과·지금까지 생성된 실행자 텍스트를 포함한 전체 트랜스크립트를 제공
OpenRouter 네이티브	실행자가 상담 프롬프트를 제공. Pydantic AI가 `forward_transcript=false` 구성
로컬 폴백	실행자가 `advisor` 함수 도구를 통해 상담 프롬프트를 제공. `forward_history=True`이면 어드바이저가 완료된 실행자 메시지 히스토리도 받음

로컬 어드바이저는 자체 고정 지시문을 사용해요. 실행자 의존성·도구·toolsets를 상속하지 않아요. forward_history는 완료된 메시지만 추가해요. 실행자의 현재 부분 응답은 포함하지 않아요.

이식 가능한 동작을 위해 실행자에게 상담 프롬프트에 질문과 모든 관련 증거를 넣으라고 알리세요. 로컬 도구 설명이 이 요구를 강화해요.

로컬 폴백은 그 프롬프트를 구성된 어드바이저 모델과 프로바이더로 보내요. 네이티브 실행은 실행자 프로바이더 구성을 사용해요. 자격 증명·트랜스크립트 공유·프로바이더 정책을 검토할 때 이 구분을 데이터 라우팅 선택으로 취급하세요.

사용량, 실패, 관측 가능성 (Usage, failures, and observability)

로컬 어드바이저 요청은 부모 실행의 RunUsage와 UsageLimits를 공유하므로, 그 요청과 토큰이 에이전트 트리의 정상 한도에 포함돼요. 네이티브 프로바이더는 자기 프로토콜대로 어드바이저 사용량을 보고해요. Anthropic은 RequestUsage.details에 어드바이저 특정 값을 기록하고, OpenRouter는 응답 프로바이더 상세에서 집계된 서버 도구 수를 노출해요.

잘못된 옵션 조합은 Advisor가 구성될 때 실패해요. 실행자·프로바이더 호환성은 실행이 모델 요청을 준비할 때 검증돼요. Anthropic은 네이티브 어드바이저 오류를 도구 결과로 보고해 실행자가 계속할 수 있게 해요. 로컬 어드바이저가 잘못된 모델 동작을 만들면, 실행자는 Pydantic AI의 다른 서브에이전트 지원 도구와 마찬가지로 일반 도구 재시도를 받아요. 로컬 모델 해석·인증·프로바이더·요청·사용량 한도 오류는 그 외에는 전파되어 실행을 멈출 수 있어요. 로컬 호출이 max_uses를 초과하면, 도구는 실행자에게 더 이상 조언 없이 계속하라고 알리는 경계 있는 메시지를 반환해요.

구성 (Composition)

capability는 순서 제약이 필요 없어요. Pydantic AI의 네이티브 또는 로컬 도구 선택을 통해 다른 capability·일반 toolsets와 조합돼요.

어드바이저 도구는 항상 보이고 Tool Search를 통해 지연되지 않아요. 그것은 도구 이름과 toolset ID advisor를 예약해요. 네이티브 도구가 안정적 정체성 하나를 가지므로 에이전트당 Advisor 인스턴스 하나가 지원돼요.

스트리밍 중 실행자 스트림은 어드바이저 상담이 실행되는 동안 멈추고 완료된 조언이 준비되면 재개돼요. 로컬 폴백은 어드바이저 모델의 토큰 델타를 실행자 스트림에 접합하지 않아요.

로컬 상담은 병렬로 실행될 수 있어요. max_uses가 설정되면 호출이 어드바이저 모델 요청을 시작하기 전에 요청별 할당량을 청구하므로, 병렬 호출이 그것을 초과할 수 없어요.

네이티브 조언은 실행자 모델 요청의 일부로 남기 때문에 영속 실행과 호환돼요. 로컬 실행은 모든 영속 백엔드에서 같은 의미론을 아직 보존하지 못해요. Temporal과 Prefect는 반환된 조언을 체크포인트할 수 있지만, 활동-로컬 또는 태스크-로컬 RunUsage의 변경은 바깥 실행으로 병합되지 않아요. DBOS는 일반 함수 도구 호출을 체크포인트하지 않으므로, 워크플로우 재생 중 로컬 어드바이저 요청이 다시 실행될 수 있어요.

지원되는 프로바이더로 에이전트를 영속 실행할 때는 mode='native'를 쓰세요. Harness는 Pydantic AI core가 아직 공개 영속-컨텍스트 계약을 노출하지 않으므로 영속 통합을 검사하지 않아요. 따라서 로컬 실행(auto 폴백 포함)은 이 capability가 거부하는 게 아니라 영속 실행에서 미지원이에요.

API 참고 (API reference)

Advisor

Bases: NativeOrLocalTool[AgentDepsT]

에이전트가 프로바이더 네이티브 도구 또는 로컬 폴백을 통해 다른 모델을 상담하게 해요.

auto 모드에서 Advisor는 명시적 프로바이더 한정 모델 이름이 호환되는 Anthropic 또는 OpenRouter 실행자와 일치할 때 Pydantic AI의 네이티브 AdvisorTool을 사용해요. 다른 모든 모델에서는 별도의 Pydantic AI 에이전트로 뒷받침되는 advisor 함수 도구를 노출해요.

from pydantic_ai import Agent
from pydantic_ai_harness.advisor import Advisor

agent = Agent(
    'openai:gpt-5.4',
    capabilities=[Advisor('anthropic:claude-opus-4-8')],
)

속성 (Attributes)

id

One-off: 에이전트에는 어드바이저 하나가 있고 그 도구 이름은 고정이에요.

__init__에서 올려 보내기만 하는 대신 여기 선언되어, 클래스가 독자 — 그리고 하나의 id 아래 이 capability가 둘이면 무엇을 뜻하는지 결정하는 Pydantic AI — 가 볼 수 있는 곳에 명시해요.

타입: str | None 기본: 'advisor'

output_type

기본적으로 텍스트인, 로컬 상담용 출력 명세.

기본 아닌 명세는 auto 모드에서 로컬 실행을 선택하고 native 모드와 호환되지 않아요. 성공한 상담은 검증된 출력을 실행자에게 직접 반환해요.

타입: OutputSpec[object] 기본: output_type

model

상담할 모델.

Agent와 같은 모델 이름과 모델 인스턴스를 받아요. auto 모드에서는 모델 인스턴스가 로컬 실행을 사용해 그 프로바이더 구성이 보존돼요.

타입: ModelSelection 기본: model

mode

어드바이저 상담이 실행되는 방식.

auto는 명시적 같은-프로바이더 모델 이름에만 네이티브 어드바이저를 사용해요. native는 프로바이더 네이티브 어드바이저를 요구하고, local은 항상 별도 Pydantic AI 에이전트를 실행해요.

타입: Literal['auto', 'native', 'local'] 기본: mode

max_uses

한 실행자 모델 요청에서 최대 상담 수.

한도는 다음 실행자 요청에서 리셋돼요. OpenRouter의 네이티브 어드바이저는 이 옵션을 존중하지 않으므로, 설정하면 거기서 로컬 폴백을 선택해요.

타입: int | None 기본: max_uses

max_tokens

각 어드바이저 상담의 최대 출력 토큰.

1024 미만 값은 거부되어, 설정이 모든 네이티브·로컬 실행 경로에서 유효하게 유지돼요.

타입: int | None 기본: max_tokens

caching

Anthropic 네이티브 어드바이저 프롬프트 캐싱.

기회주의적 최적화예요. OpenRouter와 로컬 폴백은 동등한 캐시 제어를 제공하지 않아요.

타입: Literal['5m', '1h'] | None 기본: caching

forward_history

로컬 상담이 실행자의 완료된 메시지 히스토리를 받을지 여부.

네이티브 실행은 프로바이더의 트랜스크립트 동작을 그대로 유지해요.

타입: bool 기본: forward_history

메서드 (Methods)

for_run

@async

def for_run(ctx: RunContext[AgentDepsT]) -> Advisor[AgentDepsT]

로컬 사용량이 이 실행에 격리된 새 capability를 반환해요.

반환

Advisor[AgentDepsT]

after_model_request

@async

def after_model_request(
    ctx: RunContext[AgentDepsT],
    *,
    request_context: ModelRequestContext,
    response: ModelResponse,
) -> ModelResponse

각 실행자 응답에 대해 로컬 상담 할당량을 리셋해요.

반환

ModelResponse

더 알아보기 (Learn more)

Pydantic AI Harness — 패키지 전반.
Pydantic AI capabilities — capability 시스템.