에이전트 자동화

코딩 에이전트의 자동화 계층으로 Herdr를 사용하십시오. 스크립트로 이를 제어하거나 한 에이전트가 다른 에이전트를 위한 작업을 생성하고 상태를 검사하고 결과를 수집할 수 있습니다. 작업과 일치하는 기본 요소를 선택하세요.

패널은 에이전트 포함 여부에 관계없이 존재합니다. 에이전트는 현재 패널 내에서 실행 중인 인식된 프로세스입니다. 따라서 agent start에는 기존 쉘 패널이 필요하며 레이아웃을 생성, 분할 또는 이동하지 않습니다.

작업 공간을 생성하면 첫 번째 탭과 루트 창도 생성됩니다. 탭을 생성하면 루트 패널이 생성됩니다. 첫 번째 프로세스에 대해 반환된 패널 ID를 사용하고 해당 레이아웃에 다른 터미널이 필요한 경우에만 분할합니다.

생성 명령은 JSON을 출력합니다. 예측하는 대신 응답에서 ID를 캡처합니다.

created=$(herdr workspace create --cwd ~/project --label api --no-focus)
pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')


split=$(herdr pane split "$pane_id" --direction right --no-focus)
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')

workspace create은 .result.workspace, .result.tab 및 .result.root_pane을 반환합니다. tab create는 .result.tab 및 .result.root_pane을 반환합니다. pane split은 새 패널을 .result.pane로 반환합니다.

패널을 다른 작업 공간으로 이동하면 해당 작업 공간 한정 패널 ID가 변경됩니다. pane move 이후에는 .result.move_result.pane.pane_id을 계속합니다. 응답은 .result.move_result.previous_pane_id의 이전 값을 유지합니다. 실행 중인 프로세스는 시작 시 Herdr 환경을 유지하지만 이전 HERDR_PANE_ID은 해당 터미널의 별칭으로 유지되므로 --current은 안전하게 유지됩니다. 새 명령은 이동 후에도 이름으로 에이전트를 확인할 수 있지만 이미 진행 중인 대기는 agent_not_running로 끝납니다.

셸, 테스트, 서버, CI 감시자 및 기타 일반 터미널 프로세스에 대해 패널 명령을 사용합니다. Herdr가 어떤 에이전트가 실행 중인지 또는 그것이 working, blocked, done, idle 또는 unknown인지 이해해야 할 때 에이전트 명령을 사용하십시오.

w1:p2과 같은 패널 ID는 터미널 위치를 식별합니다. reviewer과 같은 에이전트 이름은 해당 패널에 있는 현재 에이전트의 편리한 별칭입니다. 이름은 [a-z][a-z0-9_-]{0,31}와 일치해야 하며 실시간 에이전트 간에 고유해야 합니다. 해당 에이전트가 종료되거나 해제되거나 교체되면 별칭이 지워집니다. 패널의 이름을 영구적으로 바꾸지는 않습니다.

에이전트 명령은 고유한 실시간 이름이나 현재 에이전트를 호스팅하는 패널 ID를 허용합니다.

사용 가능한 셸 패널은 대화형 셸 프롬프트에 있습니다. 셸 자체는 전경 명령, 편집기 또는 실행 중인 에이전트 없이 전경을 소유합니다. agent start을 호출하기 전에 패널을 프롬프트로 되돌립니다.

--kind은 지원되는 에이전트와 해당 정식 실행 파일을 선택합니다. 지원되는 종류는 pi, claude, codex, gemini, cursor, devin, agy, cline, omp, mastracode, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qwen, letta, maki 및 muse. -- 이후의 인수는 변경되지 않은 채 해당 실행 파일에 전달됩니다.

성공적인 agent start은 Herdr가 동일한 터미널에서 예상되는 에이전트를 감지하고 대화형 입력이 가능하다고 표시한 후에만 반환됩니다. 시작 중에 감지가 blocked을 보고하면 명령은 즉시 agent_not_ready을 반환합니다. 이름은 agent read 및 agent send-keys에 계속 사용할 수 있으며 idle 감지 보고 후 프롬프트를 표시할 준비가 됩니다. 시작은 기본적으로 30초 동안 기다립니다. --timeout은 3000보다 크고 300000밀리초 이하여야 합니다.

herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4

수동으로 실행된 에이전트는 자동으로 감지되며 패널 ID로 주소를 지정할 수 있습니다. 사람이 읽을 수 있는 안정적인 대상이 유용한 경우 이름을 지정하세요.

herdr agent get w1:p2
herdr agent rename w1:p2 reviewer

agent prompt은 텍스트와 인코딩된 Enter를 제출하고 터미널의 실시간 대괄호 붙여넣기 모드를 따릅니다. 이미 작업 중인 에이전트에게 메시지를 표시할 수 있습니다. 에이전트가 이미 blocked인 경우 터미널 입력을 보내지 않고 agent_blocked을 반환합니다. 대화를 검사하고 의도적인 응답을 위해 agent send-keys을 사용하십시오. esc, up, enter 또는 ctrl+c과 같은 상호작용에는 agent send-keys를 사용하세요. escape은 esc의 별칭으로 허용됩니다. 의도적으로 원시 터미널 제어를 원할 경우 패널 입력 명령을 사용하십시오.

창 입력은 현재 점유자에 관계없이 터미널의 주소를 지정합니다. 에이전트 입력은 라이브 에이전트를 확인하고 해당 에이전트가 더 이상 패널을 제어하지 않는 경우 작업을 거부합니다.

agent prompt --wait은(는) 입력을 보내거나 대기를 시작하지 않고 이미 agent_blocked를 사용하여 blocked 에이전트를 거부합니다. 그렇지 않으면 기다리기 전에 프롬프트와 지연된 Enter를 하나의 주문된 제출로 작성합니다. Windows에서 Codex는 Enter 전에 붙여넣기 경계를 수신하므로 제출은 프롬프트 크기에 의존하지 않습니다. 호출자 시간 초과에는 제출 시간이 포함됩니다. 프롬프트가 작동하지 않는 다른 상태에서 시작된 경우 Herdr는 제출 후 working 또는 blocked을 관찰하기 위해 최대 5초를 기다립니다. 그렇지 않으면 agent_prompt_stalled를 반환합니다. 호출자 시간 초과가 먼저 만료되면 일반적인 timeout 오류가 반환됩니다. 이렇게 하면 관련되지 않은 idle, done 또는 세션 변경이 대기를 완료하는 것을 방지할 수 있습니다. Herdr는 활동을 관찰한 후 요청된 정착 상태를 기다립니다. 개별 회전을 추적하지 않습니다. 에이전트가 이미 작업 중인 경우 활성 턴을 완료하면 대기 시간이 충족될 수 있습니다. 독립 실행형 agent wait은 현재 에이전트를 관찰하고 상태가 이미 일치하는 경우 즉시 반환합니다. 두 명령 모두 기본값은 idle, done 또는 blocked입니다. --until을 반복하여 몇 가지 정확한 상태를 허용합니다(예: --until idle --until done). 필요한 경우 --until unknown을 명시적으로 사용하세요. agent prompt에서 --until에는 --wait이 필요합니다.

idle 및 done은 모두 에이전트가 입력할 준비가 되었음을 의미합니다. CLI/API는 서버의 확인된 상태를 사용합니다. done는 유휴 상태이지만 아직 확인된 것으로 표시되지 않았습니다. 명시적인 pane focus / agent focus 명령은 대상을 확인된 것으로 표시하고 읽기는 수행하지 않습니다. 각 TUI 클라이언트는 조회된 완료를 독립적으로 추적하므로 클라이언트의 완료 배지는 CLI 또는 다른 클라이언트의 배지와 다를 수 있습니다. blocked는 Herdr가 승인 또는 질문 UI를 인식했음을 의미합니다. unknown은 에이전트가 있지만 Herdr가 해당 수명 주기를 자신있게 분류할 수 없음을 의미합니다. 성공적인 완료를 증명하지는 않습니다. 구별이 중요한 경우 정확한 --until 상태를 사용하세요.

시작 준비, 유휴 대화 복원 및 에이전트 대화 전환은 완료된 작업으로 간주되지 않습니다. 즉시 작업을 시작하는 에이전트는 Herdr가 유휴 프롬프트를 먼저 보지 않고도 첫 번째 작업을 완료할 수 있습니다. 에이전트 응답에는 completion_seq이 포함될 수 있으며, 이는 누가 본 것인지에 관계없이 현재 유휴 전환을 완료된 작업으로 식별합니다. 해당 전환의 state_change_seq과 일치합니다. 시작 및 세션 변경으로 인해 설정되지 않습니다. 이전 서버에서는 이 필드가 생략될 수 있습니다. 이전 서버에 연결된 클라이언트는 관찰된 작업 상태를 사용하여 완료 배지를 보호하므로 업데이트 사이에 시작하고 끝나는 차례를 놓칠 수 있습니다.

시간 초과 또는 agent_prompt_stalled은 입력이 전송되지 않았음을 증명하지 않습니다. 동일한 메시지를 두 번 제출하지 않으려면 재시도하기 전에 에이전트를 읽어보세요. ID와 에이전트 이름은 하나의 서버로 범위가 지정됩니다. TUI에서 다른 시스템을 선택해도 기존 패널에서 실행 중인 CLI 명령의 대상이 변경되지 않습니다.

pane wait-output은 에이전트 수명 주기를 해석하지 않습니다. 선택한 터미널 스냅샷을 폴링하고 즉시 검색하므로 이미 존재하는 텍스트가 일치할 수 있습니다. 기본 소스 이름은 recent입니다. 일치는 해당 소스를 최근 렌더링된 80개의 터미널 행에서 래핑되지 않은 최근 출력으로 처리합니다. --lines는 행 제한을 변경하고 --regex은 Rust 정규식 구문을 사용하여 한 번에 한 줄씩 일치시킵니다.

CLI에서 pane read 및 agent read은 모두 터미널 텍스트를 직접 출력합니다. 기본값은 ANSI 이스케이프가 제거된 UTF-8 텍스트입니다. 소스가 노출하는 터미널 이스케이프를 유지하려면 --format ansi 또는 --ansi을 사용하십시오. detection 소스는 항상 일반 텍스트입니다. 최근 소스의 경우 --lines N는 선택적 언래핑 전에 마지막 N 렌더링된 터미널 행을 선택합니다. 그렇지 않으면 기본값을 80행으로 읽습니다. visible 및 detection의 경우 --lines을 생략하면 전체 스냅샷이 반환되지만 이를 지정하면 줄 바꿈으로 구분된 마지막 N줄이 유지됩니다. 소켓 API는 .result.read.text에 텍스트를 반환합니다.

Claude Code 및 OpenCode와 같은 전체 화면 에이전트는 Herdr의 호스트 스크롤백 대신 터미널의 대체 화면에서 성적 기록 기록을 렌더링합니다. 대화 내용 하단에 유휴 상태이고 인식된 에이전트의 경우 recent 또는 recent-unwrapped에서 읽은 텍스트는 --lines가 표시되는 화면 이상을 요청할 때 자동으로 에이전트의 마우스 스크롤 인터페이스를 사용합니다. Herdr는 겹치는 페이지를 수집하고 읽기를 완료하기 전에 뷰포트를 아래쪽으로 반환합니다. 패널에 해당 에이전트가 포함되어 있으면 pane read에도 동일한 동작이 적용됩니다. 추가 옵션이 필요하지 않습니다.

다른 읽기는 수동적으로 유지됩니다. Herdr는 visible, detection 또는 ANSI 읽기, 출력 대기 및 구독, 수동으로 스크롤된 에이전트, 직접 연결 또는 마우스 휠 입력을 보고하지 않는 응용 프로그램에 대한 응용 프로그램 뷰포트를 이동하지 않습니다. 에이전트가 작동 중이거나 차단되었거나 알 수 없는 동안 대체 화면 기록이 필요한 명시적 agent read --lines N는 agent_not_idle을 반환합니다. 유휴 상태를 기다렸다가 다시 시도하거나 --source visible을 사용하세요. 다른 최근 읽기는 이전과 같이 사용 가능한 화면과 호스트 스크롤백을 반환합니다.

여전히 전체 응답을 받을 수 없는 경우 에이전트에게 임시 디렉터리에 Markdown으로 작성하고 파일 경로만 응답해 달라고 요청한 후 파일을 직접 읽어보세요.

성공적인 agent start, agent prompt 및 agent wait 명령은 .result.agent의 현재 에이전트를 반환합니다. pane wait-output는 .result.pane_id, .result.matched_line 및 .result.read에서 일치하는 스냅샷을 반환합니다.

대기 명령에는 기본 시간 제한이 없으며 무기한 대기할 수 있습니다. 시간 초과 또는 다른 서버 오류가 발생하면 CLI 명령은 JSON 오류를 stderr에 출력하고 상태 1로 종료됩니다. 잘못된 CLI 구문이 상태 2로 종료됩니다.

도우미를 시작하고, 작업을 제공하고, 작업이 완료될 때까지 기다립니다.

split=$(herdr pane split --current --direction right --no-focus)
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 120

에이전트가 입력을 요청하고 이를 검사하고 UI와 상호작용할 때까지 기다립니다.

herdr agent wait reviewer --until blocked --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 80
herdr agent send-keys reviewer esc

일반 프로세스를 실행하고 에이전트로 처리하지 않고 출력을 기다립니다.

herdr pane run w1:p3 "just test --watch"
herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000

전체 명령 및 옵션 목록은 CLI 참조을 참조하세요. 셸 완성은 동일한 명령 트리를 대화형으로 노출합니다.