에이전트에 Herdr 지원 추가하기

코딩 에이전트를 구축하면 자신의 코드에서 Herdr의 일급 시민으로 만들 수 있습니다. Herdr에게 풀 요청을 할 필요도 없고 Herdr 릴리스를 기다릴 필요도 없습니다.

에이전트가 Herdr에 보고하면 사용자는 다음을 얻을 수 있습니다.

사이드바 및 herdr agent list에 에이전트 이름과 idle, working 또는 blocked 상태
완료되거나 결정이 필요할 때 알림
herdr agent wait 및 에이전트 상태를 기다리는 기타 자동화
Herdr 서버를 다시 시작한 후 동일한 패널에 동일한 세션이 다시 표시됩니다.

Herdr는 벤더가 통합을 제공하지 않는 에이전트를 위한 통합을 소유하고 있습니다. 에이전트를 유지 관리하는 경우 통합을 직접 소유한다는 것은 자신의 릴리스 일정에 따라 문제를 수정할 수 있음을 의미합니다.

작동 원리

Herdr 패널의 모든 프로세스는 다음 환경 변수를 상속합니다.

변수	의미
`HERDR_ENV`	`1` Herdr 내부
`HERDR_PANE_ID`	에이전트가 실행되는 창
`HERDR_BIN_PATH`	이 패널을 소유한 Herdr 바이너리
`HERDR_SOCKET_PATH`	Herdr의 API 소켓

귀하의 에이전트는 "$HERDR_BIN_PATH"를 통해 세 가지 종류의 보고서를 작성합니다.

State. 변경될 때마다 idle, working 또는 blocked을 보고합니다.
Resume 명령. 현재 세션을 다시 여는 명령을 보고합니다.
Release. 에이전트가 종료되면 패널을 해제합니다.

HERDR_ENV=1 및 기타 변수가 설정된 경우에만 보고합니다. Herdr 외부에서는 통합이 아무 작업도 수행해서는 안 됩니다.

상태 보고

bash

"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
  --source my-agent \
  --agent my-agent \
  --state working \
  --seq 1

차례가 시작되면 working을 보고하고, 에이전트가 입력할 준비가 되면 idle을 보고하고, 사용자가 무언가를 결정해야 할 때는 blocked를 보고합니다. 블록을 설명하려면 --message을 추가하세요.
--agent은 사용자에게 표시되는 이름입니다. Herdr가 이미 지원하는 에이전트의 이름이 아닌 자신의 에이전트 이름을 사용하세요.
--source은 통합을 식별합니다. 안정적이고 독특하게 유지하세요. Herdr의 자체 통합에서는 해당 프리픽스를 사용하므로 herdr:로 시작하지 마십시오.
--seq은 선택 사항이지만 권장됩니다. 전체 세션 및 에이전트 재시작을 포함하여 소스에서 보고할 때마다 증가해야 합니다. 타임스탬프가 잘 작동합니다. Herdr는 번호가 마지막으로 승인한 것보다 높지 않은 보고서를 무시하므로 늦거나 순서가 잘못된 보고서는 최신 상태를 덮어쓸 수 없습니다.

제목이나 사용자 정의 상태 텍스트 등 상태를 변경하지 않고 에이전트가 표시되는 방식을 변경하려면 사용자 정의 상태 라벨을 참조하세요.

재개 명령 보고

-- 뒤에 현재 세션을 재개하는 명령을 넣으세요. 모델이나 권한 모드 등 세션에 필요한 옵션을 포함하면 재개된 세션이 동일하게 작동합니다.

bash

"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
  --source my-agent \
  --agent my-agent \
  --state idle \
  --seq 2 \
  --agent-session-id "$SESSION_ID" \
  -- my-agent --resume "$SESSION_ID" --model my-model

명령을 상태 보고서에 첨부하거나 세션만 변경될 때 pane report-agent-session과 함께 보낼 수 있습니다. 에이전트가 세션을 전환할 때마다 다시 보고하세요.

Herdr 서버가 다시 시작된 후 Herdr는 동일한 디렉터리에서 패널을 열고 그곳에서 해당 명령을 실행합니다. 명령은 다음 규칙을 따라야 합니다.

첫 번째 단어는 경로가 아닌 my-agent과 같은 사용자 PATH의 일반 명령 이름입니다.
인수에 아포스트로피나 제어 문자가 포함되어 있지 않습니다.
인수는 최대 64개, 총 8KiB입니다.
소스가 먼저 패널을 보유해야 하므로 명령 앞이나 명령과 함께 report-agent을 사용하여 상태 보고서를 보내십시오. 그렇지 않으면 Herdr는 resume_not_accepted로 대답합니다.

Herdr는 invalid_resume_argv을 사용하여 처음 세 가지 규칙을 위반하는 명령을 거부하고 해당 보고서를 적용하지 않습니다. 사용자는 [session] resume_agents_on_restore = false을 사용하여 이력서를 끌 수 있습니다.

종료 시 해제

bash

"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
  --source my-agent \
  --agent my-agent \
  --seq 3

해제하면 패널에서 에이전트의 이름, 상태 및 재개 명령이 즉시 지워집니다. 사용자가 실제로 종료한 경우에만 해제하세요. 에이전트가 동일한 프로세스에서 한 세션을 다른 세션으로 대체하는 경우 해제하는 대신 새 세션을 보고하세요.

에이전트가 해제되지 않고 종료되면 Herdr는 패널이 유휴 쉘 프롬프트로 돌아가는 것을 확인하고 에이전트와 재개 명령을 지웁니다. 일반적으로 1~2초 정도 걸립니다. 이는 릴리즈를 대체하는 것이 아닌 안전망입니다.

방해가 되지 않도록 하세요

Herdr가 에이전트의 속도를 늦추도록 두지 마십시오. 백그라운드에서 또는 짧은 시간 초과로 보고서를 보내고 오류를 무시합니다.
최신 상태만 보냅니다. 보고서가 작성되는 동안 여러 변경 사항이 대기열에 있으면 이전 변경 사항을 삭제하세요.
재개 명령에는 Herdr 0.9.2 이상이 필요합니다. 이전 버전에서는 이를 무시하므로 상태 보고서와 릴리스가 계속 작동합니다.

소켓을 직접 사용

HERDR_BIN_PATH 및 CLI는 Windows를 포함하여 이식 가능한 선택입니다. 에이전트에 직접 IPC가 필요한 경우 소켓 API에 설명된 동등한 pane.report_agent, pane.report_agent_session 및 pane.release_agent 요청을 보냅니다. 재개 명령은 resume_argv 배열에 들어갑니다.

통합 확인

Herdr 패널에서 에이전트를 시작한 다음 Herdr에 표시되는 내용을 확인하세요.

bash

herdr pane get "$HERDR_PANE_ID"
herdr agent list

일반 세션을 건드리지 않고 복원을 테스트하려면 별도의 명명된 세션을 사용하십시오.

herdr --session my-agent-test을 시작한 다음 패널에서 에이전트를 실행하세요.
herdr session stop my-agent-test으로 해당 세션을 중지하세요.
herdr --session my-agent-test를 다시 시작하세요. 패널에서 재개 명령을 실행해야 하며 에이전트가 다시 보고해야 합니다.