지연 도구 호출 처리
지연 도구 호출 처리 (Handle Deferred Tool Calls)
HandleDeferredToolCalls는 에이전트 실행 중에 지연 도구 호출(deferred tool calls)을 인라인으로 해결해 주는 캐퍼빌리티예요. 이 캐퍼빌리티를 쓰면 지연된 호출을 처리하는 흐름을 코드로 자동화할 수 있어요.
출처: 문서
본문
도구가 승인(approval)을 요구하거나 외부 실행이 필요할 때, 에이전트는 보통 일시 중지하며 DeferredToolRequests를 출력으로 반환해요. 이 캐퍼빌리티는 그 호출들을 가로채서, 여러분의 핸들러를 호출해 해결하고 런을 자동으로 계속 진행시킵니다:
from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities import HandleDeferredToolCalls
from pydantic_ai.tools import DeferredToolRequests, DeferredToolResults
async def handle_deferred(ctx: RunContext, requests: DeferredToolRequests) -> DeferredToolResults:
return requests.build_results(approve_all=True) # (1)
agent = Agent('openai:gpt-5.2', capabilities=[HandleDeferredToolCalls(handle_deferred)])
- (1) 승인을 기다리고 있는 모든 호출을 자동 승인합니다. 실제 핸들러는 보통
requests.approvals와requests.calls를 검사해서 호출마다 결정합니다 — 운영자에게 프롬프트를 띄우거나, 정책을 확인하거나, 외부 호출을 실행하는 식이에요.
핸들러는 sync 또는 async 모두 가능합니다. 일부 또는 모든 대기 중 호출에 대한 결과가 담긴 DeferredToolResults를 반환하거나, 거절하려면 None을 반환해요 — 이 경우 체인의 다음 HandleDeferredToolCalls 캐퍼빌리티가 기회를 얻고, 처리되지 않은 호출은 평소처럼 DeferredToolRequests 출력으로 올라갑니다.
핸들러로 지연 호출 해결하기를 보면 이 기능이 더 넓은 지연 도구 흐름에서 어떻게 자리 잡는지 알 수 있어요. 사람 개입 승인과 외부 도구 실행도 다룹니다.