Researcher

Researcher

이 문서에서는 Researcher capability를 소개해요. 소스가 뒷받침되는 답변으로 폭넓은 웹 연구를 수행할 수 있는 컴팩트한 스택을 Pydantic AI 에이전트에 제공하고, 여러 core capability를 결합한 combined capability로 구성돼 있어요. 그대로 사용하거나 분해해서 쓸 수 있어요.

출처: 문서

본문

Researcher는 Pydantic AI 에이전트에 소스가 뒷받침되는 답변으로 폭넓은 웹 연구를 수행할 수 있는 컴팩트한 스택을 제공해요. 아래 capabilities로 만든 일반적인 combined capability이므로, 그대로 사용하거나 분해할 수 있어요.

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

Usage

로컬 검색 및 fetch 폴백(DuckDuckGo 검색, 페이지를 Markdown으로 변환하는 fetch)을 설치하세요:

• pip
• uv

Terminal

pip install "pydantic-ai-harness[researcher]"

Terminal

uv add "pydantic-ai-harness[researcher]"

그 다음 질문을 던져보세요:

from pydantic_ai import Agent
from pydantic_ai_harness import Researcher

agent = Agent('openai:gpt-5.6-sol', capabilities=[Researcher()])

result = agent.run_sync('What changed in the last three major releases of Django?')
print(result.output)

같은 에이전트는 모든 Pydantic AI 인터페이스에서 동작해요: 터미널 채팅용 agent.to_cli_sync(), 브라우저 채팅 UI용 agent.to_web().

또는 파일을 건너뛰고 export된 researcher_agent를 clai(Pydantic AI CLI)와 함께 uvx로 실행할 수도 있어요:

Terminal

uvx --with 'pydantic-ai-harness[researcher]' clai -a pydantic_ai_harness.researcher:researcher_agent -m openai:gpt-5.6-sol

What's inside

말 그대로 이 capability들을 이 순서로 결합한 것이에요:

• 간결한 기본 연구 지침: 아래 Instructions 참고
• Core WebSearch(local=True): 모델이 지원할 때는 프로바이더의 네이티브 웹 검색, 그렇지 않을 때는 로컬 DuckDuckGo 폴백
• Core WebFetch(local=True): 결과 뒤에 있는 페이지를 읽기. 지원되면 네이티브, 아니면 로컬 폴백으로, 주장을 소스에 대조해 확인할 수 있어요
• SubAgents: 위임(delegation), 기본적으로 웹에 특화된 researcher 하위 에이전트를 가져요
• ToolOutputLimits: 단일 도구 결과가 소비할 수 있는 컨텍스트 양을 제한해요

subagents=[]를 전달하면 위임을 비활성화하고, 자체 SubAgent 항목을 공급할 수도 있어요.

Instructions

Researcher에는 짧은 기본 연구 지침(DEFAULT_RESEARCHER_INSTRUCTIONS, 아래 blown-out equivalent에 전체가 적혀 있음)이 포함돼 있어요. instructions='...'를 전달해 나만의 것으로 바꾸거나, instructions=None으로 기본 지침 없이 능력만 가져갈 수 있어요.

Making it more powerful

• 특정 형식으로 연구하기: 에이전트에 타입이 지정된 output_type을 제공하세요 — 각각 소스 링크가 있는 조사 결과의 Pydantic 모델로, 그러면 연구자가 산문 대신 구조화된 데이터를 반환해요.
• 더 높은 품질의 검색: 검색 백엔드를 Exa Search로 교체하세요.
• Fan out: Dynamic Workflow를 추가해 에이전트가 병렬로 타입이 지정된 연구자 하위 에이전트를 생성하고 그 구조화된 결과를 결합하게 하세요.

Blown-out equivalent

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebFetch, WebSearch
from pydantic_ai_harness import SubAgent, SubAgents, ToolOutputLimits

instructions = """\
Search broadly before drawing conclusions.
Read the sources that support each important claim.
Prefer primary and authoritative sources.
Cite every factual claim with a direct source link.
Distinguish sourced facts from your own inference.
"""

sub_researcher = SubAgent(
    Agent(
        name='researcher',
        description='Research a focused sub-question on the web and report back with findings and source links',
        capabilities=[WebSearch(local=True), WebFetch(local=True), ToolOutputLimits()],
    )
)

agent = Agent(
    'openai:gpt-5.6-sol',
    instructions=instructions,
    capabilities=[
        WebSearch(local=True),  # native provider search, DuckDuckGo fallback on models without it
        WebFetch(local=True),  # read the pages behind the results, native or local
        SubAgents(agents=[sub_researcher], agent_folders=None),
        ToolOutputLimits(),
    ],
)

소스 코드를 참고하세요.

API reference

Researcher

Bases: CombinedCapability[AgentDepsT]

일반 combined capability로 구축된 완전한 연구 에이전트 harness예요.

간결한 기본 지침이 포함돼 있어요. instructions=를 전달해 바꾸거나, instructions=None으로 기본 지침 없이 실행할 수 있어요.

researcher_agent

module:variable 대상을 로드하는 CLI용 모델 없는 연구 에이전트예요.

Default: Agent(name='researcher', capabilities=[Researcher()])

더 알아보기 (Learn more)

• pydantic-ai-harness 문서