AI

Agent Flow — Claude Code에이전트 오케스트레이션을실시간으로 시각화하는 도구

반응형
Agent Flow — Claude Code 에이전트 오케스트레이션을 실시간으로 시각화하는 도구

AI AGENT VISUALIZATION

Agent Flow — Claude Code
에이전트 오케스트레이션을
실시간으로 시각화하는 도구

에이전트가 어떻게 생각하고, 분기하고, 협력하는지
실시간 노드 그래프로 지켜보세요

1. Agent Flow란 무엇인가

Agent Flow는 Claude Code 에이전트의 실행 과정을 실시간 인터랙티브 노드 그래프로 시각화해주는 오픈소스 도구입니다. Simon Patole가 개발했으며, 게임 개발 플랫폼인 CraftMyGame에서 인공지능 기반 게임 생성 파이프라인을 디버깅하던 중 탄생했습니다. Claude Code를 사용해본 개발자라면 누구나 경험했을 문제가 있습니다. 에이전트에게 복잡한 작업을 맡기면 최종 결과만 보일 뿐, 그 과정에서 에이전트가 어떤 도구를 호출했는지, 어떤 순서로 파일을 분석했는지, 어디서 분기가 발생했는지 전혀 알 수 없다는 것입니다. Agent Flow는 이 블랙박스를 완전히 투명하게 만들어줍니다.

이 도구의 핵심 가치는 에이전트의 사고 과정을 시각적으로 이해할 수 있게 해준다는 점입니다. 노드 그래프에서 각 노드는 에이전트의 개별 행동을 나타내고, 엣지는 행동 간의 인과 관계와 데이터 흐름을 보여줍니다. 개발자는 이를 통해 에이전트가 문제를 어떻게 분해하고 어떤 도구를 선택하는지 직관적으로 파악할 수 있습니다. 실시간 스트리밍 기능 덕분에 에이전트가 작업하는 동안 그래프가 즉시 업데이트되어, 마치 에이전트의 생각을 실시간으로 들여다보는 것 같은 경험을 제공합니다.

Apache 2.0 라이선스로 공개된 이 프로젝트는 현재 GitHub에서 568개의 스타를 받으며 빠르게 성장하고 있습니다. TypeScript 기반으로 작성되었으며, Next.js 웹 애플리케이션과 VS Code 확장 프로그램, 이벤트 릴레이 서버로 구성된 모듈형 아키텍처를 갖추고 있어 다양한 환경에서 유연하게 사용할 수 있습니다.

npx 한 줄로 Agent Flow를 즉시 시작할 수 있다

▲ npx 한 줄로 Agent Flow를 즉시 시작할 수 있다

2. 왜 필요한가 — 블랙박스 문제

Claude Code를 비롯한 에이전트 코딩 도구들은 놀라운 생산성을 제공하지만, 근본적인 한계가 있습니다. 에이전트의 실행 과정이 완전한 블랙박스라는 것입니다. 개발자가 복잡한 리팩토링 작업을 에이전트에게 맡기면, 터미널에는 진행 상황을 나타내는 간략한 텍스트만 표시될 뿐입니다. 에이전트가 어떤 파일을 먼저 읽었는지, 왜 특정 도구를 선택했는지, 중간에 에러가 발생했다가 자동으로 복구된 건 아닌지, 이 모든 것이 감춰져 있습니다.

이 블랙박스 문제는 단순한 호기심의 영역을 넘어 실질적인 개발 품질에 영향을 미칩니다. 에이전트가 비효율적인 경로를 반복해서 탐색하고 있을 수도 있고, 불필요한 서브에이전트를 생성해서 토큰을 낭비하고 있을 수도 있습니다. 또한 에이전트가 특정 파일을 과도하게 수정하거나, 의도하지 않은 방향으로 코드를 변경하고 있을 수도 있습니다. 이런 문제들을 발견하려면 에이전트의 실행 과정을 투명하게 들여다볼 수 있어야 합니다.

Agent Flow는 이 문제를 근본적으로 해결합니다. HTTP 훅을 통해 Claude Code의 모든 이벤트를 캡처하고, 이를 실시간 노드 그래프로 변환하여 브라우저에 표시합니다. 개발자는 에이전트가 작업하는 동안 마치 투명한 유리 상자를 통해 내부를 관찰하듯이 전체 실행 과정을 추적할 수 있습니다. 과거 세션의 로그를 JSONL 파일로 저장하고 나중에 리플레이할 수도 있어, 사후 분석과 팀 내 공유에도 활용할 수 있습니다.

💡 TIP: Agent Flow의 핵심 가치는 "관찰 가능성(Observability)"입니다. 서버 모니터링에 Grafana가 필요하듯, 에이전트 코딩에는 Agent Flow가 필요합니다. 에이전트의 행동을 이해해야 더 좋은 프롬프트를 작성할 수 있고, 더 효율적인 워크플로를 설계할 수 있습니다.

3. 핵심 기능 총정리

Agent Flow가 제공하는 기능들을 카테고리별로 살펴보겠습니다. 먼저 시각화 기능입니다. 가장 핵심이 되는 기능은 인터랙티브 노드 그래프 렌더링입니다. 에이전트의 각 행동이 노드로 표현되고, 노드 사이의 연결은 도구 호출 순서와 데이터 흐름을 나타냅니다. 사용자는 그래프를 팬과 줌으로 탐색할 수 있으며, 개별 노드를 클릭하면 해당 행동의 상세 페이로드를 확인할 수 있습니다. 색상과 스타일로 실행 상태를 구분하므로, 성공한 호출과 실패한 호출, 진행 중인 작업을 한눈에 파악할 수 있습니다.

실시간 시각화

인터랙티브 노드 그래프 렌더링, 실시간 도구 호출 추적과 분기 시각화, 멀티 세션을 탭 인터페이스로 동시 모니터링, 팬과 줌 및 클릭 상호작용으로 상세 정보 확인, 타임라인 패널로 실행 순서를 시간순 추적, 파일 어텐션 히트맵으로 에이전트가 집중하는 파일 파악

감지 및 스트리밍

Claude Code 세션 자동 감지 기능으로 워크스페이스 내 세션을 자동으로 발견합니다. 경량 HTTP 훅 서버가 이벤트를 수신하고, Server-Sent Events 기반 제로 레이턴시 스트리밍으로 지연 없이 브라우저에 전달합니다. JSONL 로그 파일을 테일링하여 과거 세션도 리플레이할 수 있습니다.

다양한 데이터 소스

라이브 Claude Code 훅 통합을 기본으로 지원하며, 히스토리컬 JSONL 이벤트 로그 파일을 불러와 과거 세션을 분석할 수 있습니다. 다이렉트 이벤트 릴레이 스트림을 통해 커스텀 소스로부터의 이벤트도 처리 가능합니다.

에이전트의 실행 경로가 노드 그래프로 실시간 시각화된다

▲ 에이전트의 실행 경로가 노드 그래프로 실시간 시각화된다

타임라인 패널은 에이전트의 모든 행동을 시간순으로 정렬하여 보여줍니다. 각 이벤트의 시작 시간과 소요 시간이 표시되어 성능 프로파일링에 활용할 수 있습니다. 분기 시각화 기능은 에이전트가 조건부 로직에 따라 다른 경로를 선택할 때 그 분기점을 명확하게 보여줍니다. 파일 어텐션 히트맵은 에이전트가 세션 동안 어떤 파일에 가장 많이 접근했는지를 시각적으로 표현하여, 에이전트의 관심이 집중되는 코드 영역을 파악할 수 있게 해줍니다.

4. 설치 방법 세 가지

Agent Flow는 사용자의 환경과 필요에 따라 세 가지 설치 방법을 제공합니다. 가장 빠른 방법은 npx를 사용하는 것입니다. 터미널에서 npx agent-flow-app 한 줄만 입력하면 즉시 실행됩니다. 별도의 클론이나 빌드 과정 없이 최신 버전이 자동으로 다운로드되고 실행됩니다. 포트 변경이 필요하면 --port 4000 옵션을, 브라우저 자동 열기를 비활성화하려면 --no-open 옵션을 추가할 수 있습니다.

소스 코드를 직접 클론하여 개발 환경을 구축하는 과정

▲ 소스 코드를 직접 클론하여 개발 환경을 구축하는 과정

두 번째 방법은 소스 코드를 직접 클론하여 빌드하는 것입니다. 이 방법은 Agent Flow의 코드를 직접 수정하거나 확장 기능을 개발하고 싶은 사용자에게 적합합니다. 먼저 GitHub 저장소를 클론한 후 pnpm으로 의존성을 설치합니다. 그 다음 pnpm run setup 명령으로 Claude Code 훅을 자동 구성하고, pnpm run dev로 개발 서버를 시작합니다. Node.js 20 이상의 LTS 버전이 필요하며, pnpm 패키지 매니저가 사전에 설치되어 있어야 합니다.

VS Code 확장 프로그램으로 설치하기

세 번째 방법은 VS Code 확장 프로그램을 설치하는 것입니다. 마켓플레이스에서 Agent Flow를 검색하여 설치하면, VS Code 내에서 직접 시각화 패널을 열 수 있습니다. 확장 프로그램은 첫 사용 시 자동으로 세션을 감지하고 훅을 구성해주기 때문에 별도의 설정이 거의 필요 없습니다. 커맨드 팔레트에서 Agent Flow 관련 명령을 실행하거나, 키보드 단축키로 빠르게 접근할 수 있습니다.

VS Code 확장 프로그램의 명령어와 설정 옵션 상세

▲ VS Code 확장 프로그램의 명령어와 설정 옵션 상세

⚠ 주의: 소스 빌드 설치 시 Node.js 20 이상과 pnpm 패키지 매니저가 필수입니다. npm이나 yarn으로는 워크스페이스 구조가 올바르게 동작하지 않을 수 있으므로, 반드시 pnpm을 사용해주세요.

5. 실전 사용 가이드

Agent Flow를 설치한 후 실제로 사용하는 과정을 단계별로 살펴보겠습니다. 먼저 Agent Flow를 시작합니다. npx 방식이라면 터미널에서 npx agent-flow-app을 실행하고, 소스 빌드 방식이라면 pnpm run dev를 실행합니다. 브라우저에서 localhost:3000에 접속하면 대시보드가 표시됩니다. 이 상태에서 별도의 터미널을 열고 Claude Code로 작업을 시작하면, Agent Flow가 자동으로 세션을 감지하고 이벤트를 수신하기 시작합니다.

멀티 세션 모니터링 — 여러 에이전트를 동시에 추적하는 화면

▲ 멀티 세션 모니터링 — 여러 에이전트를 동시에 추적하는 화면

대시보드에는 현재 활성화된 세션이 탭으로 표시됩니다. 각 탭을 클릭하면 해당 세션의 노드 그래프로 전환됩니다. 그래프에서 노드를 클릭하면 우측 패널에 해당 도구 호출의 상세 정보가 표시됩니다. 어떤 인자로 도구를 호출했는지, 반환된 결과는 무엇인지, 소요 시간은 얼마인지 등을 확인할 수 있습니다. 줌 인과 줌 아웃으로 전체 흐름과 세부 사항을 자유롭게 전환할 수 있고, 드래그로 그래프를 이동하여 원하는 영역을 탐색할 수 있습니다.

멀티 세션 모니터링은 Agent Flow의 강력한 기능 중 하나입니다. 여러 개의 Claude Code 세션을 동시에 실행하고 있을 때, 각 세션의 진행 상황을 탭을 전환하며 확인할 수 있습니다. 예를 들어 하나의 에이전트가 백엔드 리팩토링을 진행하고, 다른 에이전트가 프론트엔드 테스트를 작성하고 있다면, 두 작업의 진행 상황을 하나의 인터페이스에서 동시에 모니터링할 수 있습니다. 타임라인 패널에서는 모든 이벤트의 시간순 목록을 확인할 수 있어, 에이전트가 어떤 순서로 도구를 호출했는지 추적하기에 편리합니다.

파일 어텐션 히트맵도 실전에서 매우 유용한 기능입니다. 에이전트가 세션 동안 어떤 파일에 가장 많이 접근했는지를 시각적 막대 그래프로 보여줍니다. 에이전트가 특정 파일을 과도하게 반복 읽기하고 있다면, 프롬프트를 개선하여 불필요한 반복을 줄일 수 있는 단서가 됩니다. 반대로 에이전트가 중요한 파일을 아예 읽지 않았다면, 프롬프트에 해당 파일에 대한 명시적 언급을 추가하여 더 정확한 결과를 얻을 수 있습니다.

6. 아키텍처와 동작 원리

Agent Flow의 아키텍처는 이벤트 주도 파이프라인 구조를 따릅니다. 전체 흐름은 다섯 단계로 이루어집니다. 첫째, 사용자가 Claude Code를 실행하면 에이전트가 각 도구를 호출할 때마다 HTTP 훅 이벤트가 발생합니다. 둘째, 이 이벤트는 Agent Flow의 경량 HTTP 훅 서버로 전송됩니다. 셋째, 이벤트 릴레이 서버가 수신한 이벤트를 처리하고 구조화합니다. 넷째, Server-Sent Events 프로토콜을 통해 제로 레이턴시로 브라우저에 스트리밍됩니다. 다섯째, 웹 프론트엔드가 수신한 이벤트를 인터랙티브 노드 그래프로 렌더링하여 실시간 업데이트합니다.

이벤트가 Claude Code에서 브라우저까지 전달되는 전체 파이프라인

▲ 이벤트가 Claude Code에서 브라우저까지 전달되는 전체 파이프라인

이 아키텍처에서 주목할 점은 폴링 방식이 아닌 Server-Sent Events를 사용한다는 것입니다. 폴링 방식은 클라이언트가 주기적으로 서버에 새 이벤트가 있는지 확인하는 구조여서, 확인 주기에 따라 지연이 발생합니다. 반면 SSE는 서버가 이벤트가 발생할 때 즉시 클라이언트에 푸시하는 구조이므로, 실질적으로 제로 레이턴시에 가까운 실시간 업데이트가 가능합니다. 이 덕분에 에이전트가 도구를 호출하는 순간 화면에서 새로운 노드가 나타나는 것을 거의 동시에 확인할 수 있습니다.

이벤트는 구조화된 JSON 객체 형태로 전달됩니다. 프론트엔드는 이 JSON 이벤트를 파싱하여 에이전트, 도구 호출, 반환 흐름을 나타내는 그래프 노드로 변환합니다. 타임라인 재구성 엔진은 실시간 시청과 과거 리플레이를 모두 지원하도록 설계되어 있어, 라이브 모니터링과 사후 분석이 같은 인터페이스에서 원활하게 이루어집니다.

7. VS Code 확장 활용법

VS Code 확장 프로그램은 브라우저 없이도 에디터 안에서 직접 에이전트 시각화를 활용할 수 있게 해줍니다. 설치 후 커맨드 팔레트에서 사용할 수 있는 주요 명령은 네 가지입니다. "Agent Flow: Open Agent Flow"는 에디터 내에 전체 시각화 패널을 엽니다. "Agent Flow: Open Agent Flow to Side"는 사이드 컬럼에 패널을 열어, 코드 편집과 에이전트 모니터링을 동시에 할 수 있게 합니다. "Agent Flow: Connect to Running Agent"는 자동 감지가 되지 않는 세션에 수동으로 연결할 때 사용합니다. "Agent Flow: Configure Claude Code Hooks"는 훅 구성을 다시 실행해야 할 때 사용합니다.

키보드 단축키도 제공됩니다. macOS에서는 Cmd+Alt+A, Windows와 Linux에서는 Ctrl+Alt+A로 빠르게 패널을 열 수 있습니다. 설정 옵션으로는 devServerPort로 개발 서버 포트를 지정할 수 있고, eventLogPath에 JSONL 파일 경로를 입력하면 과거 로그를 자동으로 시각화합니다. autoOpen 옵션을 활성화하면 Claude Code 세션이 시작될 때 자동으로 시각화 패널이 열립니다. 작업 흐름을 방해받지 않으면서도 에이전트의 상태를 항상 확인할 수 있는 매우 편리한 기능입니다.

Claude Code 훅 자동 구성 과정 — 이벤트 훅 등록과 연결 테스트

▲ Claude Code 훅 자동 구성 과정 — 이벤트 훅 등록과 연결 테스트

8. JSONL 로그 리플레이

Agent Flow는 라이브 모니터링뿐만 아니라 과거 세션의 리플레이도 지원합니다. Claude Code 세션에서 발생하는 모든 이벤트는 JSONL 형식으로 로그 파일에 저장될 수 있습니다. 이 로그 파일을 Agent Flow에 로드하면, 과거 세션의 전체 실행 과정을 시간순으로 재생할 수 있습니다. 이 기능은 여러 상황에서 매우 유용합니다.

JSONL 이벤트 로그 파일을 사용한 과거 세션 리플레이

▲ JSONL 이벤트 로그 파일을 사용한 과거 세션 리플레이

첫째, 팀 내 지식 공유에 활용할 수 있습니다. 특정 에이전트 세션에서 흥미로운 패턴을 발견했다면, 해당 JSONL 파일을 팀원들과 공유하여 같은 시각화를 재현할 수 있습니다. 둘째, 사후 분석에 유용합니다. 에이전트가 예상과 다른 결과를 출력했을 때, 로그를 리플레이하여 어디서 잘못된 분기가 발생했는지 정확히 추적할 수 있습니다. 셋째, 프롬프트 최적화에 활용할 수 있습니다. 같은 작업을 다른 프롬프트로 실행한 후 각각의 로그를 비교 분석하면, 어떤 프롬프트가 더 효율적인 실행 경로를 유도하는지 객관적으로 판단할 수 있습니다.

VS Code 확장에서는 설정의 eventLogPath 항목에 JSONL 파일 경로를 입력하면 자동으로 해당 파일을 테일링하여 실시간 추적합니다. 새로운 이벤트가 파일에 추가될 때마다 즉시 시각화가 업데이트되므로, 로그 파일을 직접 생성하는 커스텀 에이전트와의 통합도 가능합니다. 이벤트 필터링과 검색 기능도 지원되어, 대량의 이벤트 중에서 특정 도구 호출이나 에러만 골라서 확인할 수 있습니다.

9. 성능 분석과 디버깅

Agent Flow의 가장 실용적인 활용 방법 중 하나는 에이전트의 성능을 분석하고 병목 지점을 찾아내는 것입니다. 각 도구 호출의 소요 시간이 타임라인에 기록되므로, 어떤 도구가 가장 많은 시간을 소비하는지 한눈에 파악할 수 있습니다. 예를 들어 Bash 명령 실행이 전체 시간의 대부분을 차지한다면, 빌드 캐싱이나 테스트 범위 축소 등의 최적화를 고려할 수 있습니다. 서브에이전트 호출이 병목이라면, 프롬프트를 더 구체적으로 작성하여 서브에이전트의 탐색 시간을 줄일 수 있습니다.

도구별 실행 시간 분석으로 병목 지점을 정확히 파악할 수 있다

▲ 도구별 실행 시간 분석으로 병목 지점을 정확히 파악할 수 있다

디버깅 측면에서도 Agent Flow는 강력합니다. 에이전트가 에러를 만나고 자동으로 복구하는 과정이 노드 그래프에 명확하게 표시됩니다. 에러가 발생한 노드는 빨간색으로 강조되고, 에이전트가 재시도하는 경로가 별도의 분기로 나타납니다. 이를 통해 에이전트가 에러를 어떻게 처리하는지, 재시도 전략이 효과적인지 등을 평가할 수 있습니다. 특히 복잡한 멀티 에이전트 시나리오에서는 어떤 서브에이전트가 실패했고, 메인 에이전트가 이를 어떻게 보상했는지를 추적하는 것이 매우 중요합니다.

에러 발생과 자동 복구 과정이 시각적으로 추적되는 모습

▲ 에러 발생과 자동 복구 과정이 시각적으로 추적되는 모습

프롬프트 최적화에도 성능 분석 데이터를 적극 활용할 수 있습니다. 같은 작업에 대해 서로 다른 프롬프트를 사용한 세션의 로그를 비교하면, 도구 호출 횟수와 총 소요 시간, 에러 발생 빈도 등을 객관적으로 비교할 수 있습니다. 이런 데이터를 기반으로 프롬프트를 반복 개선하면, 에이전트의 효율성을 체계적으로 향상시킬 수 있습니다. Agent Flow를 통해 관찰하고 학습한 에이전트 행동 패턴은 더 나은 프롬프트 엔지니어링을 위한 귀중한 자산이 됩니다.

10. 기존 방식과의 비교

Agent Flow를 사용하기 전과 후의 차이를 구체적으로 비교해보겠습니다. 기존 방식에서는 에이전트의 실행 경로를 확인하려면 최종 출력 결과만으로 역추론해야 했습니다. 도구 호출 추적은 터미널 로그를 수동으로 분석해야 했고, 성능 분석은 시작 시간과 종료 시간의 차이를 직접 계산하는 수준에 그쳤습니다. 여러 세션을 동시에 모니터링하는 것은 사실상 불가능했으며, 과거 세션의 재현도 매우 어려웠습니다.

Agent Flow 도입 전후의 개발 경험 비교표

▲ Agent Flow 도입 전후의 개발 경험 비교표

Agent Flow를 도입하면 이 모든 것이 달라집니다. 실행 경로 전체가 실시간 인터랙티브 그래프로 시각화되어, 에이전트의 모든 판단과 행동을 투명하게 관찰할 수 있습니다. 도구 호출은 노드 그래프에서 클릭 한 번으로 상세 정보를 확인할 수 있고, 성능 프로파일링은 자동으로 수행됩니다. 탭 기반 인터페이스로 여러 세션을 동시에 모니터링할 수 있으며, JSONL 리플레이로 과거 세션도 완벽하게 재현할 수 있습니다. 무엇보다 설정의 난이도가 극히 낮아서 npx 한 줄이면 시작할 수 있다는 점이 매력적입니다.

11. 프로젝트 구조 살펴보기

Agent Flow의 소스 코드 구조를 살펴보면 프로젝트의 아키텍처를 더 깊이 이해할 수 있습니다. 전체 코드베이스는 TypeScript가 95.1 퍼센트를 차지하며, 나머지는 JavaScript 3.8 퍼센트와 CSS 1.1 퍼센트로 구성됩니다. 프로젝트는 pnpm 워크스페이스 구조를 채택하여, app과 extension과 web이라는 세 개의 주요 패키지로 분리되어 있습니다.

Agent Flow 프로젝트의 디렉토리 구조와 각 모듈의 역할

▲ Agent Flow 프로젝트의 디렉토리 구조와 각 모듈의 역할

app 디렉토리에는 이벤트 릴레이 백엔드가 위치합니다. HTTP 훅 서버가 Claude Code로부터 이벤트를 수신하고, SSE 스트리밍 모듈이 이를 브라우저로 전달하는 역할을 합니다. extension 디렉토리는 VS Code 확장 프로그램의 소스 코드를 포함합니다. 확장 코어 로직과 웹뷰 에셋이 분리되어 있어, 확장 기능의 유지보수성이 높습니다. web 디렉토리는 Next.js 기반의 웹 애플리케이션으로, 노드 그래프와 타임라인과 히트맵 등 모든 시각화 컴포넌트가 이곳에 있습니다. scripts 디렉토리에는 훅 자동 구성 스크립트를 비롯한 유틸리티가 포함되어 있습니다.

개발에 참여하고 싶다면, pnpm run dev:demo로 목 데이터와 함께 개발 환경을 시작할 수 있습니다. pnpm run dev:relay는 이벤트 릴레이만 독립적으로 실행하고, pnpm run dev:extension은 확장 프로그램의 워치 빌드를 시작합니다. 프로덕션 빌드는 pnpm run build:all로 웹뷰와 확장을 한번에 빌드하거나, pnpm run build:web과 pnpm run build:extension으로 개별 빌드할 수 있습니다.

12. 자주 묻는 질문

Q1. Agent Flow는 무료인가요?+

네, Agent Flow는 Apache 2.0 라이선스로 공개된 완전한 오픈소스 프로젝트입니다. 개인 사용과 상업적 사용 모두 무료로 가능합니다. 다만 "Agent Flow"라는 이름과 로고는 Simon Patole의 트레이드마크이므로, 포크 프로젝트에서 동일한 이름을 사용할 때는 TRADEMARK.md 파일의 가이드라인을 확인해주세요.

Q2. Claude Code 외에 다른 에이전트도 지원하나요?+

현재 Agent Flow는 Claude Code 에이전트를 주요 타겟으로 설계되었습니다. Claude Code의 HTTP 훅 시스템을 활용하여 이벤트를 캡처하기 때문에, 다른 에이전트 프레임워크를 직접 지원하지는 않습니다. 다만 JSONL 이벤트 로그 인터페이스를 통해 구조화된 JSON 이벤트를 생성할 수 있는 모든 시스템과 간접적으로 통합할 수 있는 확장성을 갖추고 있습니다.

Q3. 성능에 영향을 주지 않나요?+

Agent Flow의 HTTP 훅 서버는 매우 경량으로 설계되어 있습니다. 이벤트 수신 시 응답 시간은 수 밀리초 수준이며, 에이전트의 실제 실행 성능에 미치는 영향은 무시할 수 있을 정도로 작습니다. 훅은 비동기적으로 동작하므로, 에이전트의 도구 호출이 훅 전송을 기다리지 않습니다. 다만 매우 빈번한 도구 호출이 발생하는 극단적인 상황에서는 브라우저 측의 렌더링 부하가 늘어날 수 있으므로, 이 경우 이벤트 필터링을 활용하시는 것을 권장합니다.

Q4. 팀원들과 시각화를 공유할 수 있나요?+

네, 가능합니다. 가장 간단한 방법은 JSONL 이벤트 로그 파일을 공유하는 것입니다. 팀원이 동일한 Agent Flow 환경을 구성한 후 공유받은 JSONL 파일을 로드하면, 원본 세션과 동일한 시각화를 재현할 수 있습니다. 이 방식은 코드 리뷰에서 에이전트의 행동을 설명하거나, 특정 에이전트 패턴을 팀 내에서 논의할 때 특히 유용합니다.

Q5. 설치 중 문제가 발생하면 어떻게 하나요?+

가장 흔한 문제는 Node.js 버전이 20 미만인 경우입니다. node --version으로 버전을 확인하고, 필요하면 nvm이나 fnm으로 최신 LTS 버전을 설치해주세요. pnpm이 설치되지 않은 경우에는 corepack enable 명령으로 활성화할 수 있습니다. 훅 연결이 되지 않는 경우에는 pnpm run setup을 다시 실행하거나, VS Code 확장의 "Configure Claude Code Hooks" 명령으로 훅을 재구성해보세요. GitHub Issues에 현재 3개의 오픈 이슈가 있으니, 동일한 문제가 보고되었는지 확인하는 것도 좋은 방법입니다.

에이전트의 사고를 시각화하세요

Agent Flow와 함께라면 Claude Code 에이전트의 블랙박스가 투명한 유리 상자로 변합니다.
설치부터 활용까지, 지금 바로 시작해보세요.

GitHub 저장소 바로가기

이 글은 2026년 4월 기준으로 작성되었습니다. 최신 정보는 공식 GitHub 저장소를 확인해주세요.

반응형
소개 | 개인정보처리방침 | 문의

Categories