백그라운드 에이전트 도구

백그라운드 에이전트 도구 (Background Agents Tool)

오케스트레이터가 서브 에이전트에 작업을 병렬로 나눠 주고 결과를 비동기로 모으는 방법을 설명해요.

출처: 문서

본문

백그라운드 에이전트 도구는 오케스트레이터가 서브 에이전트에 작업을 동시에 배달하고 결과를 비동기로 수집하게 해 줘요. transfer_task(서브 에이전트가 끝날 때까지 블록)와 달리 백그라운드 에이전트 작업은 병렬로 실행돼요 — 오케스트레이터가 여러 작업을 시작하고, 다른 일을 하다가 나중에 확인할 수 있어요.

사용 가능한 도구

도구 설명
run_background_agent 백그라운드에서 서브 에이전트 작업 시작; 작업 ID 반환
list_background_agents 상태와 실행 시간과 함께 모든 백그라운드 작업 나열
view_background_agent ID로 작업의 라이브 출력 또는 최종 결과 보기
stop_background_agent ID로 실행 중인 작업 취소

run_background_agent 파라미터

파라미터 타입 필수 설명
agent string ✓ 실행할 서브 에이전트 이름. 호출자의 sub_agents 아래에 나열되어야 함
task string ✓ 서브 에이전트가 달성해야 할 작업의 명확하고 간결한 설명
expected_output string ✗ 호출자가 기대하는 결과 형식에 대한 선택적 설명

run_background_agent는 작업 ID 문자열을 반환해요. 서브 에이전트가 실행하는 도구는 부모 세션의 권한을 상속해요. 백그라운드 작업은 비대화형으로 실행되기 때문에, 보통 사용자 승인을 요청하는 도구 호출은 자동으로 거부돼요. 백그라운드 에이전트가 변경 도구를 실행하게 하려면 부모 세션에서 명시적으로 승인해야 해요(예: YOLO 모드 또는 명시적 허용 규칙).

백그라운드 위임은 transfer_task와 같은 런타임 가드를 공유해요: 위임 순환은 거부되고 체인은 중첩 위임 10개로 제한돼요.

view_background_agent와 stop_background_agent 파라미터

파라미터 타입 필수 설명
task_id string ✓ run_background_agent 또는 list_background_agents가 반환한 작업 ID

list_background_agents는 파라미터를 받지 않아요.

구성

toolsets:
  - type: background_agents

구성 옵션은 없어요. 에이전트가 백그라운드 작업을 배달할 대상 에이전트를 가질 수 있도록 sub_agents를 구성해야 해요.

예시

agents:
  coordinator:
    model: openai/gpt-4o
    description: Orchestrates parallel research
    instruction: Fan out research tasks and synthesize results.
    sub_agents: [researcher]
    toolsets:
      - type: background_agents
      - type: think

  researcher:
    model: openai/gpt-4o
    description: Web researcher
    instruction: Research topics thoroughly.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo

팁 언제 쓸까 오케스트레이터가 여러 전문가에게 작업을 병렬로 나눠야 할 때 background_agents를 사용하세요 — 예를 들어 여러 주제를 동시에 조사하거나 독립적인 코드 분석을 나란히 실행할 때요. TUI에서 각 백그라운드 작업의 토큰 사용량은 실시간으로 계산돼요. 사이드바의 Agents 패널이 로스터 행에 서브 에이전트의 컨텍스트 사용률을 보여주고, Agent Inspector가 정확한 토큰 수를 보여주며, 작업 비용이 세션 총액에 합산돼요.

Harness 서브 에이전트 사용하기

백그라운드 에이전트는 harness 기반 서브 에이전트에서도 똑같이 잘 동작해요 — Claude Code나 Codex 같은 외부 코딩 CLI로 구동되는 서브 에이전트요. 이렇게 하면 여러 독립적인 코딩 작업을 병렬로 배달할 수 있어요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Orchestrator that fans out coding tasks
    instruction: |
      Dispatch the frontend and backend tasks in parallel,
      then collect results and produce a summary.
    sub_agents:
      - claude-coder
      - codex-coder
    toolsets:
      - type: background_agents

  claude-coder:
    description: Frontend specialist (Claude Code)
    harness:
      type: claude-code
      effort: medium

  codex-coder:
    description: Backend specialist (Codex)
    harness:
      type: codex

오케스트레이터는 각 코딩 작업에 run_background_agent를 호출하고, 끝나면 list_background_agents와 view_background_agent로 결과를 모아요.

참고 Harness 도구셋은 무시돼요 Harness 에이전트는 외부 CLI의 자체 도구를 사용해요 — harness 에이전트에 설정한 toolsets:는 조용히 무시돼요. 자세한 내용과 주의사항은 Coding Harnesses를 참고하세요.

examples/coding_harness_background_agents.yaml에서 완전한 구성을 확인하세요.

더 알아보기 (Learn more)