Agent Flow 소개
코딩 에이전트에게 작업을 맡기고 나면 한동안 볼 수 있는 것은 스크롤로 흘러가는 로그뿐이고, 결국 손에 남는 것은 마지막 결과물입니다. 결과가 맞으면 문제가 없지만 어긋났을 때는 곤란해집니다. 에이전트가 문제를 어떻게 쪼갰는지, 어떤 도구를 어떤 순서로 불렀는지, 어느 단계에서 시간과 토큰이 빠져나갔는지가 로그 안에 섞여 있어서, 잘못된 판단이 시작된 지점을 찾으려면 수백 줄을 거슬러 읽어야 합니다.
Agent Flow는 그 실행 과정을 상호작용 가능한 노드 그래프로 펼쳐 보여주는 시각화 도구입니다. 에이전트가 일하는 동안 도구 호출과 분기, 반환 흐름이 실시간으로 그래프에 그려지고, 노드를 눌러 세부 내용을 들여다볼 수 있습니다. 만든 사람은 Simon Patole이며, AI 에이전트로 게임을 만드는 플랫폼인 CraftMyGame을 개발하다가 에이전트의 동작을 디버깅하는 일이 너무 번거로워 직접 만들어 쓰던 것을 공개했다고 밝히고 있습니다.
화면을 보면 이 도구가 무엇을 드러내려 하는지 분명해집니다. 가운데 캔버스에는 실행 중인 에이전트와 하위 에이전트가 노드로 놓이고 각 노드에 누적 토큰과 비용이 함께 표시됩니다. 오른쪽 패널은 그 비용을 에이전트별과 도구별로 쪼개 보여주고, 아래쪽 타임라인은 실행 전체를 시간축으로 늘어놓습니다. 저장소는 이 밖에도 전체 실행 타임라인과 파일 주목도 히트맵, 메시지 트랜스크립트 패널을 제공한다고 적고 있습니다.
Agent Flow가 두 런타임에서 이벤트를 받는 방식
Agent Flow는 Claude Code와 Codex 두 런타임의 세션을 동시에 자동 감지해 나란히 보여주며, 각 세션에는 어느 런타임에서 왔는지 표시가 붙습니다. 한쪽만 쓰더라도 다른 쪽은 아무 동작도 하지 않으므로 따로 설정할 필요가 없습니다. 두 런타임에서 이벤트를 가져오는 방법은 서로 다릅니다:
| 항목 | Claude Code | Codex |
|---|---|---|
| 수집 방식 | 경량 HTTP 훅 서버가 이벤트를 직접 수신 | 롤아웃 파일을 뒤따라 읽기 |
| 감시 대상 | ~/.claude/projects/ |
~/.codex/sessions/**/rollout-*.jsonl |
| 지연 | 훅에서 곧바로 스트리밍 | 롤아웃 파일에 기록된 뒤 |
| 얻는 정보 | 실행 이벤트 | 도구 호출, 추론(reasoning), Codex가 직접 집계한 토큰 수 |
Codex 쪽에서 토큰 수를 Codex 자신의 이벤트 스트림에서 가져온다는 점이 실용적인 차이를 만듭니다. 시각화 도구가 따로 추정하지 않고 런타임이 집계한 값을 그대로 쓰기 때문입니다. Codex를 기본 경로가 아닌 곳에 설치했다면 CODEX_HOME 환경 변수를 지정하면 됩니다.
감시할 런타임을 한쪽으로 제한하고 싶다면 VS Code 확장에서는 agentVisualizer.runtime 설정을 auto, claude, codex 중에서 고르고, pnpm run dev와 npx agent-flow-app으로 실행할 때는 AGENT_FLOW_RUNTIME 환경 변수를 씁니다. 설정 키의 접두사는 프로젝트 이름과 달리 agentVisualizer이므로, 설정 파일에서는 이 이름을 그대로 적어야 합니다.
Agent Flow와 비슷한 목적의 다른 도구들
에이전트의 실행을 사람이 볼 수 있게 만드는 도구는 PyTorchKR에도 여럿 소개된 적이 있습니다. 세션이 끝난 뒤 기록을 검색하고 분석하는 쪽으로는 agentsview가 있고, 토큰 사용량과 비용을 추적하는 대시보드로는 CodeBurn이 있습니다. 상태를 항상 곁눈으로 확인하는 용도라면 Claude HUD 같은 상태 표시줄 계열이 가볍습니다.
Agent Flow가 이들과 다른 점은 실행이 진행되는 동안의 구조를 그래프로 보여준다는 것입니다. 어느 하위 에이전트가 어디서 갈라져 나왔고 그 아래에서 어떤 도구가 불렸는지가 공간 배치로 드러나므로, 목록으로 훑을 때는 잘 보이지 않는 불필요한 분기나 중복 작업이 눈에 들어옵니다. 반대로 지난 세션을 뒤져 특정 대화를 찾는 작업이라면 검색 기반 도구가 더 맞습니다.
Agent Flow는 누구에게 맞는가
하위 에이전트를 여러 개 띄우는 복잡한 워크플로우를 짜고 있고, 그 워크플로우가 왜 느리거나 왜 엉뚱한 결과를 내는지 진단해야 하는 사용자에게 Agent Flow가 가장 잘 맞습니다. 프롬프트를 다듬는 과정에서 에이전트가 지시를 어떻게 해석했는지 관찰하려는 경우에도 쓸모가 있습니다.
반대로 단일 세션에서 간단한 편집만 맡기는 사용법이라면 Agent Flow가 보여주는 그래프가 얻는 것에 비해 번거롭습니다. 실행 환경도 확인이 필요합니다. Node.js 20 이상과 pnpm, Claude Code CLI가 필요하고, VS Code 확장으로 쓰려면 1.85 이상의 VS Code 호환 편집기가 있어야 합니다. 저장소는 VS Code와 Cursor, Windsurf를 그 예로 들고 있습니다.
Agent Flow 설치와 실행
가장 빠른 방법은 VS Code 없이 브라우저에서 바로 띄우는 것입니다. 저장소를 받을 필요도 없습니다:
npx agent-flow-app
이 명령이 시각화 도구를 브라우저에 띄우고, 다른 터미널에서 Claude Code 세션을 시작하면 이벤트가 실시간으로 흘러 들어옵니다. --port로 포트를 바꾸고(기본값 3001), --no-open으로 브라우저 자동 실행을 막고, --verbose로 상세 이벤트 로그를 볼 수 있습니다.
소스에서 실행하려면 다음과 같습니다:
git clone https://github.com/patoles/agent-flow.git
cd agent-flow
pnpm i
pnpm run setup
pnpm run dev
pnpm run setup이 Claude Code 훅을 설정하는 단계이며 한 번만 실행하면 됩니다. pnpm run dev는 Next.js 개발 서버와 이벤트 릴레이를 함께 띄우고, 릴레이가 Claude Code 이벤트를 받아 SSE(Server-Sent Events)로 브라우저에 흘려보냅니다. 실행 후 접속 주소는 http://localhost:3000입니다.
VS Code 확장으로 쓰려면 확장을 설치한 뒤 명령 팔레트에서 Agent Flow: Open Agent Flow를 실행하고, 작업 공간에서 Claude Code나 Codex 세션을 시작하면 자동으로 감지됩니다. 확장은 패널을 처음 열 때 Claude Code 훅을 알아서 설정하며, 다시 설정해야 하면 명령 팔레트의 Agent Flow: Configure Claude Code Hooks를 쓰면 됩니다. 단축키는 macOS에서 Cmd+Alt+A, 윈도우와 리눅스에서 Ctrl+Alt+A입니다.
에이전트 실행 기록이 JSONL 파일로 남아 있다면 agentVisualizer.eventLogPath 설정에 그 경로를 지정해 재생하거나 실시간으로 따라 볼 수도 있습니다.
Agent Flow가 수집하는 원격 측정 정보
이 항목은 설치 방식에 따라 동작이 달라서 미리 확인해 둘 값어치가 있습니다. 익명 사용 통계는 공개된 npx agent-flow-app 실행 파일에서만 기본으로 켜져 있고, pnpm run dev와 VS Code 확장은 아무것도 보내지 않습니다. 보내는 항목은 세션 수와 지속 시간, 이벤트 수, 운영체제와 아키텍처, Agent Flow 버전, 관측된 모델 식별자 종류, 감시한 런타임, 오류 클래스 이름까지의 집계 값이며, 프롬프트와 파일 경로, 도구 호출, 사용자 정보, 환경 변수는 전송하지 않는다고 명시하고 있습니다.
끄려면 AGENT_FLOW_TELEMETRY=false 또는 DO_NOT_TRACK=1을 설정하면 되고, 이렇게 끈 설치본은 ~/.agent-flow/ 디렉토리조차 만들지 않습니다. 실제로 무엇이 쌓였는지는 ~/.agent-flow/telemetry/events.jsonl을 열어 직접 확인할 수 있으며, 정확한 전송 항목은 저장소의 scripts/telemetry.ts의 serialize() 함수에 정의되어 있습니다.
Agent Flow의 라이선스
Agent Flow는 Apache 라이선스 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
단, "Agent Flow"라는 이름과 관련 로고는 Simon Patole의 상표이므로, 이름과 로고를 그대로 쓰는 파생 배포를 계획한다면 저장소의 TRADEMARK.md에 적힌 사용 지침을 먼저 확인해야 합니다.
Agent Flow 데모 영상
Agent Flow VS Code 확장 설치하기
Agent Flow 프로젝트 GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다. 
이 도구를 직접 설치해 사용해보셨다면, 
파이토치 한국 사용자 모임
회원들을 위해 경험이나 팁을 댓글로 남겨주세요! 