Wait Tool

Wait Tool

WaitTool은 에이전트가 장기 실행 작업을 다시 확인하기 전에 잠시 멈출 수 있게 해주는 도구예요.

출처: 문서

본문

개요 (Overview)

WaitTool은 주어진 초(seconds) 동안 실행을 멈춥니다. 이 도구가 필요한 이유는, 에이전트가 장기 실행 작업(샌드박스 빌드, 배포, 일괄 임포트, 비동기 API 작업)을 시작할 때 시간이 흐르게 할 방법이 없기 때문이에요. 이 도구가 없으면 에이전트는 빡빡한 루프로 폴링하거나, 작업이 끝나기 전에 포기하게 됩니다.

이 도구는 API 키가 필요 없고 표준 라이브러리 외의 의존성도 없어요.

언제 사용하나요 (When to Use It)

도구의 설명은 모델에게, 대역 외(out-of-band) 작업이 실제 시간을 필요로 할 때 이 도구를 사용하도록 안내합니다:

  • 아직 실행 중인 샌드박스 빌드, 테스트 실행 또는 스크립트
  • 아직 롤아웃 중인 배포 또는 프로비저닝 단계
  • 일괄 임포트, 내보내기 또는 학습 작업
  • 나중에 폴링할 job id를 반환한 비동기 API
  • 재시도 전에 쿨다운이 필요한 레이트 리밋(rate limit) 또는 백오프(backoff)

모델이 따르도록 유도되는 패턴은: 작업 시작 → 대기 → 상태 확인 → 여전히 실행 중이면 다시 대기 입니다. 설명은 또한 대화 속도를 맞추기 위해 대기하지 말 것과, 필요한 정보가 이미 있을 때 대기하지 말 것을 안내합니다 — 대기는 단지 시계 시간이 흐르게 할 뿐이고 작업을 진행시키거나 확인하지 않기 때문이에요.

설치 (Installation)

이 도구는 crewai-tools에 포함되어 있습니다:

uv add crewai-tools

예제 (Example)

from crewai import Agent, Crew, Task
from crewai.tools import tool
from crewai_tools import WaitTool

wait_tool = WaitTool()

@tool("Check build status")
def check_build_status_tool(build_id: str) -> str:
    """Return the current status of a build: queued, running, passed, or failed."""
    # Replace this with a call to your own build system.
    return my_ci_client.get_build(build_id).status

build_agent = Agent(
    role="Build Monitor",
    goal="Start the build and report its final status",
    backstory="An engineer who knows that builds take time.",
    tools=[wait_tool, check_build_status_tool],
    verbose=True,
)

monitor_task = Task(
    description=(
        "Start the build, then wait and re-check its status until it finishes."
    ),
    expected_output="The final build status.",
    agent=build_agent,
)

crew = Crew(agents=[build_agent], tasks=[monitor_task])
result = crew.kickoff()

인자 (Arguments)

인자 타입 필수 설명
seconds float ✅ 대기할 시간(초). 0 이상이어야 합니다.
reason str ❌ 무엇을 기다리는지에 대한 선택적 설명. 도구 결과에 그대로 반영됩니다.

초기화 파라미터 (Initialization Parameters)

파라미터 타입 기본값 설명
max_seconds float 300 단일 대기의 상한. 더 긴 요청은 거부되지 않고 이 값으로 제한됩니다.

긴 대기 제한 (Capping Long Waits)

한 번의 호출은 최대 max_seconds만큼 기다립니다. 에이전트가 더 많은 시간을 요청하면 도구는 최대치만큼 기다리고 결과에 그 사실을 알려서, 실패하는 대신 에이전트가 다시 호출할 수 있게 합니다:

wait_tool = WaitTool()
wait_tool.run(seconds=3600)
# 'Waited 300 seconds. Requested 3600 seconds, capped at 300 seconds per call -
#  call this tool again if more waiting is needed.'

워크플로가 진짜로 더 긴 단일 대기가 필요하면 상한을 올리세요:

wait_tool = WaitTool(max_seconds=1800)

비동기 지원 (Async Support)

이 도구는 동기(sync)와 비동기(async) 실행을 모두 구현하므로, await 시 이벤트 루프를 차단하지 않습니다:

import asyncio

async def main():
    result = await wait_tool.arun(seconds=30, reason="waiting for the sandbox build")
    print(result)

asyncio.run(main())

더 알아보기 (Learn more)