백그라운드 작업 도구

백그라운드 작업 도구 (Background Jobs Tool)

에이전트가 다른 일을 계속하는 동안 셸 명령을 백그라운드에서 실행하는 방법을 설명해요. 로컬 서버, 파일 감시, 긴 빌드, 테스트 스위트에 유용해요.

출처: 문서

본문

background_jobs 도구셋은 에이전트가 다른 작업을 계속하는 동안 계속 실행돼야 하는 셸 명령을 시작해요. 로컬 서버, 파일 감시, 긴 빌드, 테스트 스위트 같은 것이죠. 작업 ID를 즉시 반환하고, 작업당 최대 10MB의 결합 stdout/stderr를 캡처하며, 에이전트 세션이 끝나면 실행 중인 모든 작업을 종료해요.

짧은 동기 명령에는 shell 도구셋을 사용하세요. 동기 명령과 장기 실행 프로세스가 모두 필요하면 두 도구셋을 함께 추가하세요.

구성

toolsets:
  - type: shell
  - type: background_jobs

옵션

속성 타입 설명
env object 모든 백그라운드 작업 명령에 설정할 환경 변수
recall boolean run_background_job이 recall 파라미터를 노출하게 해서 작업이 끝날 때 에이전트를 안내하게 하기(아래 참고). 기본 false

커스텀 환경 변수

toolsets:
  - type: background_jobs
    env:
      MY_VAR: "value"
      PATH: "${env.PATH}:/custom/bin"

백그라운드 작업 리콜

recall: true를 설정하면 run_background_job 도구가 recall 불리언 파라미터를 노출해요:

toolsets:
  - type: background_jobs
    recall: true

에이전트가 recall: true로 백그라운드 작업을 시작하면, Docker Agent는 작업이 끝난 후 실행 중인 에이전트 루프로 안내 메시지를 다시 보내요. 메시지에는 짧은 완료 문장과 작업 출력이 담겨 있어서, 에이전트는 view_background_job을 폴링하지 않고 반응할 수 있어요.

완료가 중요한 유한한 백그라운드 작업(예: 긴 빌드나 테스트 스위트)에 리콜을 사용하세요. 중지될 때까지 실행되길 기대하는 서버와 감시자에는 피하세요. examples/shell_recall.yaml에서 완전한 구성을 확인하세요.

사용 가능한 도구

백그라운드 작업 도구셋은 다섯 개의 도구를 노출해요:

도구 이름 설명
run_background_job 명령을 비동기로 시작하고 작업 ID를 즉시 반환. 서버/감시자 등에 사용
list_background_jobs 상태, 실행 시간, 메타데이터와 함께 모든 백그라운드 작업 나열
view_background_job ID로 특정 백그라운드 작업의 버퍼된 출력과 상태 보기
stop_background_job 실행 중인 백그라운드 작업 중지. 자식 프로세스도 종료됨
wait_background_job 작업이 끝날 때까지 블록하고 종료 코드와 출력 반환. 이미 끝난 작업에는 안전

run_background_job 파라미터

파라미터 타입 필수 설명
cmd string ✓ 백그라운드에서 실행할 셸 명령
cwd string ✗ 명령을 실행할 작업 디렉터리(기본: .)
recall boolean ✗ background_jobs 도구셋이 recall: true일 때만 사용 가능. true면 작업이 끝날 때 출력과 함께 안내 메시지 전송

view_background_job과 stop_background_job은 각각 run_background_job이나 list_background_jobs가 반환한 job_id 문자열 하나를 필수로 받아요.

wait_background_job 파라미터

파라미터 타입 필수 설명
job_id string ✓ run_background_job 또는 list_background_jobs가 반환한 작업 ID
timeout integer ✗ 대기할 최대 초(기본: 60). 한도가 걸리면 작업이 아직 실행 중일 때 현재 출력과 안내를 반환하고 작업은 백그라운드에서 계속됨

경고 안전 백그라운드 작업은 에이전트 프로세스와 같은 접근 권한으로 셸 명령을 실행해요. 더 이상 필요 없어지면 서버와 감시자를 중지하고, 추가 격리를 위해 Sandbox Mode를 사용하세요.

더 알아보기 (Learn more)