덕삼
블로그

agy 실전 가이드 5편 — 비대화형 실행과 다른 에이전트와의 협업

agy 실전 가이드 마지막 5편입니다. 앞의 네 편은 지침 파일, 실행 모드와 컨텍스트, 스킬과 서브에이전트, MCP 와 훅을 다뤘습니다. 이번 편은 agy 를 사람이 아니라 스크립트나 다른 에이전트가 부르는 이야기입니다.

이번 편의 질문은 agy 를 스크립트나 다른 에이전트에서 부를 때 무엇을 고정해야 하나입니다. 답은 모드, 시간 제한, 출력 형식 세 가지입니다. 하나라도 기본값에 맡기면 버전이 바뀔 때 동작이 따라 바뀝니다. 대화를 이어 가야 한다면 -p 를 여러 번 부르지 말고 ACP 로 붙입니다.

한 줄 호출의 형태

제가 다른 에이전트 세션에서 agy 에게 짧은 의견을 물을 때 쓰는 형태입니다.

~/.local/bin/agy --mode plan --print-timeout 90s -p "도구를 쓰지 말고 답하라: <질문>"

인자마다 이유가 있습니다.

  • --mode plan: 2편에서 본 대로 기본 모드는 1.5.7 에서 auto 로 바뀌었습니다. 모드를 적어 두면 기본값이 또 바뀌어도 같은 모드로 돕니다.
  • --print-timeout 90s: 기본은 시간 제한이 없습니다(1.2.6 에서 5분 → 무제한). changelog 1.5.0 에 따르면 이 시한에 걸려 턴이 끊기면 종료 코드 3 과 AGY_ERROR 줄이 나옵니다.
  • “도구를 쓰지 말고”: plan 모드도 도구 목록은 그대로라서, 읽기만 시키려면 프롬프트에 적습니다.
  • 전체 경로: 제 셸 설정에서 agy 는 래퍼 함수입니다. 이 함수가 에이전트의 비대화형 셸에서는 보조 함수를 못 찾아 command not found 로 실패했습니다. 그래서 실행 파일 경로를 직접 씁니다.

출력 형식은 세 가지입니다

--output-format 은 text(기본), json, stream-json 을 받습니다. 2026-11-18 에 1.5.10 으로 세 번 불러 출력 모양을 확인했습니다.

json 은 끝날 때 봉투 하나를 냅니다. 이번 실행의 키는 conversation_id, status, response, duration_seconds, num_turns, usage 였습니다. status 는 SUCCESS 였고 종료 코드는 0 이었습니다. 스크립트에서는 jq -r '.response' 로 답만 꺼내면 됩니다.

stream-json 은 한 줄에 이벤트 하나씩 냅니다. 첫 줄 init 에는 작업 폴더, 도구 목록 60개, permission_mode, expanded_commands 가 있었습니다. 이어서 step_update 가 user_input, agent_response 단계를 알리고, 마지막 result 가 json 과 같은 내용을 담습니다. 응답 글자는 step_update 의 text_delta 로 조금씩 옵니다.

시간은 이렇게 나뉘었습니다. JSON 의 duration_seconds 는 3.9초였는데, 명령 시작부터 끝까지는 9.9초였습니다. 약 6초가 시작에 들었습니다. 한 번 잰 값이지만, 짧은 질문을 반복해 부르는 구조라면 이 고정 시간이 쌓입니다.

출력을 해석할 때 주의할 점이 있습니다. 3편에서 쓴 측정 스크립트는 처음에 user_input·agent_response 가 아닌 단계를 모두 도구 호출로 셌습니다. 1.4.0 에 도구가 아닌 단계가 생기자 판정이 전부 무너졌습니다. 이벤트 종류는 버전마다 늘어납니다. 아는 것을 골라 세고, 모르는 것은 무시하는 쪽으로 짭니다.

스크립트는 종료 코드와 status 를 함께 봅니다

공식 문서의 CI 예시는 json 출력과 넉넉한 시한을 함께 씁니다. 저는 이렇게 줄여 씁니다.

out=$(~/.local/bin/agy --mode plan --print-timeout 10m --output-format json -p "$PROMPT")
code=$?
[ "$code" -eq 0 ] && [ "$(jq -r .status <<<"$out")" = SUCCESS ] || exit 1
jq -r .response <<<"$out" > answer.md

changelog 1.4.11 부터는 턴이 일찍 끝나면 결과에 finished_reason 이 붙습니다. 시한에 걸려 답이 잘렸으면 print_timeout, 중단됐으면 interrupted 입니다. 잘린 답을 정상 답으로 저장하지 않으려면 이 값도 봅니다.

권한이 필요한 도구를 만나면 버전마다 달랐습니다

비대화형 실행에는 승인 버튼을 누를 사람이 없습니다. 이때 agy 는 도구를 “부드럽게 거절(soft-deny)“한다고 합니다. 공식 문서와 changelog 1.1.3 의 설명입니다. 실행은 계속되고 종료 코드는 0 이며, 필요한 허용 규칙을 표준 오류에 알려 준다는 설명입니다.

그런데 2026-11-04 에 1.5.0 으로 잴 때는 달랐습니다. run_command 가 승인을 기다리며 멈췄고, 알 수 없는 단계가 반복되다 시간 제한에 걸렸습니다. 그래서 측정은 버려도 되는 임시 폴더에서 --dangerously-skip-permissions 로 했습니다. 1.5.10 에서 다시 확인하지는 않았습니다.

여기서 얻은 원칙은 둘입니다. 하나, 종료 코드 0 만 보고 성공이라 판단하지 않습니다. 거절돼도 0 이 나올 수 있으니 status 와 표준 오류를 함께 봅니다. 둘, 실제 작업을 시킬 때는 필요한 명령만 permissions.allow 에 미리 열어 둡니다. 모든 확인을 끄는 플래그는 버려도 되는 폴더에서만 씁니다.

대화를 이으려면 ACP 로 붙입니다

제 맥에는 로컬 브리지가 하나 있습니다. 에이전트 CLI 여섯 개를 A2A(Agent2Agent) 에이전트로 노출하는 서버입니다. 한 에이전트가 다른 에이전트에게 node a2a.mjs send agy "<글>" 처럼 일을 넘깁니다. 처음에는 작업마다 agy -p 를 새로 띄웠습니다. 이 방식은 CLI 마다 출력 해석 코드가 필요했고, 브리지에서 agy 대화를 잇지 못했습니다.

그래서 ACP(Agent Client Protocol)로 바꿨습니다. 에디터가 에이전트를 표준 입출력으로 부리는 규격입니다. agy 는 이 규격을 agy acp 로 직접 지원합니다. Claude Code 와 Codex 는 별도 어댑터 패키지가 필요했습니다. 브리지는 대화마다 agy acp 프로세스를 하나 띄워 두고 턴을 이어 보냅니다. 2026-11-16 에 agy 1.5.9 로 확인했습니다. 숫자를 기억시킨 뒤 같은 대화로 다시 물었고, 그 숫자를 받았습니다.

보안 쪽 결과도 있습니다. 브리지는 기본으로 여섯 에이전트를 모두 확인 없이 돌립니다. agy 는 agy acp --dangerously-skip-permissions 로 띄웁니다. 확인을 켠 안전 모드에서 파일을 만들라고 시켰을 때 결과는 갈렸습니다.

에이전트 (안전 모드)권한을 물었나파일이 생겼나
agy물었다안 생겼다
Codex물었다안 생겼다
Claude Code (어댑터 경유)안 물었다생겼다

agy 는 권한 요청을 ACP 로 올려 보냈고, 브리지가 거절하자 파일을 만들지 않았습니다. 그래도 저는 이 결과에 기대지 않습니다. 브리지는 루프백 주소에만 열고 토큰을 요구합니다. 토큰을 가진 로컬 프로세스는 에이전트에게 무엇이든 시킬 수 있으니, 토큰 파일과 루프백이 실제 경계입니다.

커밋에는 에이전트와 모델 이름을 남깁니다

agy 가 한 작업은 사람 계정이 아니라 agy-ai 계정으로 커밋합니다. 커밋 제목은 [<모델>] <type>: <설명> (#이슈) 꼴입니다. 예를 들면 [Gemini 3.8 Flash] feat(keys): ... (#78) 입니다.

이 규칙은 agy 가 직접 다듬었습니다. 2026-09-30 오후의 일입니다. 셀프호스팅 GitLab 의 인프라 문서 저장소에 agy-ai 커밋 세 개가 40분 사이에 올라왔습니다.

시각커밋바뀐 규칙
15:03옵션 A커밋 작성자 이름에 모델명을 붙인다
15:20옵션 B커밋 제목 끝에 [<모델>] 을 붙인다
15:42최종커밋 제목 맨 앞에 [<모델>] 을 둔다

마지막 커밋의 diff 에 이유가 적혀 있습니다. GitLab 웹 화면은 이메일이 계정과 맞으면 작성자 이름을 계정 표시 이름으로 덮어씁니다. 그래서 작성자 이름에 넣은 모델명은 보이지 않았습니다. 제목 끝에 붙이면 긴 제목이 말줄임표로 잘리면서 모델명이 사라졌습니다. 지금은 Claude Code 와 Codex 도 이 규칙을 따릅니다. 제 저장소의 Claude Code 커밋도 [Claude Opus 5.5] docs: ... 처럼 모델명으로 시작합니다.

실제로 얼마나 맡겼나

2026-11-18 기준 제 로컬 클론에서 agy-ai 가 작성한 커밋은 머지를 빼고 9건입니다. 첫 커밋은 2026-09-30, 마지막 커밋은 2026-10-19 입니다. 문서가 6건입니다. 커밋 규칙 3건, 에이전트 메모리 1건, API 요약과 로드맵 2건입니다. 나머지는 발표 장표 HTML 1건과 관리 화면 기능 2건입니다. 제목이나 작성자 이름에 모델명이 붙은 커밋은 8건입니다. 그중 7건이 Gemini 3.8 Flash, 1건이 Gemini 4 Argon 입니다.

같은 저장소들에서 claude-ai 가 작성한 커밋은 머지를 빼고 1,419건입니다. 기간이 다르니 비율로 읽을 수는 없습니다. 그래도 제 작업에서 agy 가 주력이 아니라 보조였다는 점은 분명합니다. 해석하자면, agy 는 문서와 작은 화면 기능, 그리고 다른 에이전트의 두 번째 의견을 맡는 자리였습니다. 앞으로 agy 이름의 기능 커밋이 늘어난다면 이 해석은 바꿔야 합니다.

Claude Code 와 다른 점

표는 각 도구의 --help 와 브리지 기록 기준입니다(Claude Code 2.1.326, agy 1.5.10).

항목Claude Codeagy
비대화형 실행claude -pagy -p (--print, --prompt)
시간 제한 플래그--help 에 없음--print-timeout
출력 형식text, json, stream-jsontext, json, stream-json
대화 잇기-c, --resume-c, --conversation
ACP어댑터 패키지 필요agy acp 내장

가장 쓸모 있는 차이는 --print-timeout 과 agy acp 입니다. 다른 프로그램이 agy 를 부릴 때 시간을 묶고 대화를 이을 수단을 agy 가 직접 갖고 있습니다.

연재를 마치며

5편의 답은 이렇습니다. agy 를 기계가 부를 때는 모드·시간 제한·출력 형식을 고정하고, 대화를 이어야 하면 ACP 로 붙입니다. 종료 코드만 믿지 말고 status 를 함께 봅니다.

다섯 편을 관통하는 원칙은 하나입니다. agy 는 45일에 32번 버전이 바뀌는 도구라, 문서보다 실물을 먼저 봅니다. 동작을 적을 때는 버전과 날짜를 붙이고, 기본값에 기대지 않고 명시합니다. 지침은 AGENTS.md 한 곳에 두고, 지켜야 할 것은 항상 읽히는 자리에 둡니다.

다음에 확인할 것은 내 agy 의 agy --version 과 agy changelog 첫 화면입니다. 이 연재의 1.5.10 이후 무엇이 바뀌었는지가 거기에 있습니다.