Background Tools

BackgroundTools는 선택된 도구를 백그라운드에서 실행하게 해서, 에이전트가 기다리지 않고 계속 일하게 해요. 모델이 결과가 준비될 때까지 다른 것을 작업할 수 있을 때 쓰세요.

이 예제를 실행하기 전에 OpenAI 프로바이더를 설치하세요:

pip install "pydantic-ai-slim[openai]" pydantic-ai-harness

uv add "pydantic-ai-slim[openai]" pydantic-ai-harness

import asyncio

from pydantic_ai import Agent
from pydantic_ai_harness import BackgroundTools

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

@agent.tool_plain(metadata={'background': True})
async def slow_research(query: str) -> str:
    """Research a topic thoroughly. Runs in the background."""
    await asyncio.sleep(60)  # Replace with real work.
    return f'Research findings for {query!r}'

기본적으로 metadata={'background': True}가 있는 어떤 도구든 백그라운드에서 실행돼요. BackgroundTools는 모델에게 도구가 실행되는 동안 어떻게 계속할지 알려줘요.

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

출처: 문서

본문

어떤 도구가 백그라운드로 실행되는지 선택하기 (Selecting which tools run in the background)

BackgroundTools(tools=...)은 표준 ToolSelector를 받아요:

from pydantic_ai_harness import BackgroundTools

# By metadata key (default)
BackgroundTools()                                 # tools with metadata={'background': True}
BackgroundTools(tools={'background': True})       # explicit form
BackgroundTools(tools={'kind': 'research'})       # custom metadata key

# By name
BackgroundTools(tools=['slow_research', 'deep_dig'])

# By function
BackgroundTools(tools=lambda ctx, td: td.name.startswith('research_'))

모델이 결정하게 하기 (Letting the model decide)

metadata={'background': 'optional'}을 사용해 각 호출에 대해 모델이 결정하게 해요. 모델은 run_in_background 인자를 보지만, 당신의 함수는 그것을 받지 않아요.

BackgroundTools(tools=...)가 선택한 도구는 항상 백그라운드에서 실행돼요. 순차 도구와 realtime 세션은 정상적으로 실행돼요. 함수 자신의 파라미터 중 하나로 run_in_background을 사용하지 마세요.

from pydantic_ai import Agent
from pydantic_ai_harness import BackgroundTools

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

@agent.tool_plain(metadata={'background': 'optional'})
async def slow_research(query: str) -> str:
    return f'Research findings for {query!r}'

도구 일괄 표시 (Marking tools in bulk)

개별 정의를 건드리지 않고 여러 도구를 백그라운드로 표시하려면 SetToolMetadata 또는 FunctionToolset.with_metadata(...)와 결합하세요:

from pydantic_ai import Agent, FunctionToolset
from pydantic_ai_harness import BackgroundTools

async def deep_research(query: str) -> str:
    return f'Research findings for {query!r}'

async def crawl_site(url: str) -> str:
    return f'Crawled {url}'

research_tools = FunctionToolset([deep_research, crawl_site]).with_metadata(background=True)
agent = Agent(
    'openai:gpt-5.6-sol',
    toolsets=[research_tools],
    capabilities=[BackgroundTools()],
)

실행 중 무슨 일이 일어나나 (What happens during a run)

모델은 먼저 도구가 시작됐다는 메시지를 받아요. 메시지는 작업 ID를 포함해요. 도구가 끝나면 모델은 같은 작업 ID로 결과를 받아요.

도구가 반환한 텍스트와 파일은 모델에 보내져요. 애플리케이션 전용 메타데이터는 보내지지 않아요. 도구가 예기치 않게 실패하면 모델은 오류 타입을 보지만, 개인 정보를 담을 수 있는 오류 메시지는 보지 못해요. 재시도가 소진되거나 CancelledError가 발생하면 실행이 끝나요. 도구는 ctx.cancel()을 호출해 실행과 다른 백그라운드 도구를 멈출 수 있어요.

정상 실행은 백그라운드 도구가 끝나기를 기다려요. 대기 중인 호출은 tool_calls_limit에 세어요. 실행이 일찍 멈추거나 중지되면 완료되지 않은 도구는 취소되고 결과는 전달되지 않아요. 비동기 도구는 취소를 허용해야 해요. 무시하면 실행이 멈추지 못할 수 있어요.

주의

Python은 동기 도구를 반환 전에 멈출 수 없어요. 실행을 취소해도 그 도구를 여전히 기다려요.

동기 백그라운드 도구는 에이전트나 다른 도구와 동시에 공유 데이터를 바꿀 수 있어요. 공유 데이터를 동시 변경으로부터 보호하세요.

한계 (Limitations)

run_stream()과 run_stream_sync()는 백그라운드 도구를 기다리지만 그 결과를 전달하지 않아요. 스트리밍 응답은 작업이 시작됐다고만 말할 수 있어요. 최종 응답이 결과를 필요로 하면 run_stream_events(), run(), run_sync()을 사용하거나 agent.iter()를 모두 소비하세요.
순차 도구는 더 일찍 시작된 백그라운드 작업과 겹칠 수 있어요. 겹치면 안 되는 도구는 공유 데이터를 보호하거나 백그라운드로 실행하지 않아야 해요.
Realtime 세션은 이미 도구를 동시에 실행하므로 BackgroundTools는 그것을 그대로 둬요.
나중 결과 메시지는 도구-결과나 도구-오류 훅을 통과하지 않아요. 이것이 중요할 때는 도구 안에서 결과를 검증하거나 제한하세요.

추적 (Tracing)

BackgroundTools는 추적 스팬을 추가하지 않아요. Pydantic AI는 도구 호출과 그 즉시 "시작됨" 결과를 기록해요. 완료된 결과는 에이전트의 메시지 히스토리에 남아요.

영속 실행 (Durable execution)

BackgroundTools는 Temporal과 동작해요.

DBOS에서는 영속 작업을 명시적 DBOS 스텝에 넣고 백그라운드 도구에서 그 스텝을 호출하세요.

영속 활동·태스크 안에서 ctx.enqueue()를 호출하지 마세요. 재생 중에 그 메시지를 복원할 수 없어요.

API

BackgroundTools(tools: ToolSelector = {'background': True})

에이전트 스펙 (Agent spec, YAML/JSON)

이 예제를 사용하기 전에 Agent spec 지원을 설치하세요:

pip install "pydantic-ai-slim[spec]" pydantic-ai-harness

uv add "pydantic-ai-slim[spec]" pydantic-ai-harness

# agent.yaml
model: openai:gpt-5.6-sol
capabilities:
  - BackgroundTools: {}

from pydantic_ai import Agent
from pydantic_ai_harness import BackgroundTools

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

더 읽기 (Further reading)

더 알아보기 (Learn more)

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