AI 에이전트, 이제 '블랙박스'가 아니에요
에이전트를 만들어 배포하고 나면 늘 이런 질문이 남아요. "얘가 왜 이 답을 했지?"
프롬프트는 멀쩡했는데 결과가 이상하거나, 툴 호출이 엉뚱한 곳에서 실패하거나, 토큰이 갑자기 폭발하는 경우 말이죠. 로그를 뒤져도 reasoning 과정은 안 보이고, tool call 순서는 어디에도 안 남아 있어서 사실상 눈 감고 디버깅하는 느낌이었어요.
Vercel이 이 문제를 정면으로 건드렸어요. eve라는 오픈소스 에이전트 프레임워크를 Vercel에 배포하면, 실행 트레이스(trace)가 자동으로 Agent Runs로 수집되고, 이걸 MCP 도구와 Vercel CLI로 조회할 수 있게 됐습니다.
핵심은 세 가지예요.
- 에이전트 실행 이력을 프로젝트 단위로 검색
- 각 run의 reasoning, tool call, 토큰 사용량 전체 조회
- MCP가 없는 코딩 에이전트도 CLI로 직접 자기 run을 디버깅
이 글은 Vercel 공식 체인지로그를 근거자료로 정리했어요. (하단 링크 참고)
MCP 도구 4종 + CLI 명령어 4종, 이게 전부예요
MCP 도구
에이전트가 MCP를 지원한다면 아래 4개 도구를 바로 쓸 수 있어요.
| 도구 | 역할 |
|---|---|
list_agent_run_projects | 팀 내에서 Agent Runs 활동이 있는 프로젝트 검색 |
list_agent_runs | 특정 프로젝트의 최근 run 목록 조회 |
get_agent_run | 메타데이터, 라이프사이클 이벤트, 사용량, 서브에이전트 데이터 조회 |
get_agent_run_trace | turn, message, reasoning, tool call, 토큰 사용량, tool 입출력 포함 전체 trace 조회 |
CLI 명령어
# MCP 설치
npx add-mcp https://mcp.vercel.com
# 또는 CLI 최신 버전으로 업그레이드
npm i -g vercel@latest
# Agent Runs 관련 명령어
vercel agent-runs projects # run이 있는 프로젝트 목록
vercel agent-runs list # 최근 run 목록
vercel agent-runs inspect # 특정 run 상세 조회
vercel agent-runs trace # run의 전체 trace 조회
실무에서 바로 쓰는 팁
모든 CLI 서브커맨드가 --json 플래그를 지원해요. 머신 리더블 출력이 필요할 때 유용하죠.
# JSON으로 파싱해서 다른 도구에 넘기기
vercel agent-runs list --json | jq '.[] | {id, status, tokens}'
# 파이프로 넘기면 trace가 markdown으로 렌더링됨
vercel agent-runs trace <run-id> | less
특히 마지막이 재밌는 포인트예요. MCP 접근 권한이 없는 코딩 에이전트도 CLI를 직접 호출해서 자기 run을 스스로 디버깅할 수 있다는 뜻이거든요. 예를 들어 Claude Code한테 이렇게 시킬 수 있어요.
"내 프로젝트의 최신 프로덕션 Agent Runs 보여줘" "최근 run들을 기반으로 스킬 업데이트해줘"
에이전트가 자기 실행 로그를 읽고 스스로 개선하는 루프가 CLI 하나로 열린 셈이에요.
반가운 소식이지만, 그냥 '로그 뷰어'는 아니에요
좋은 점
- 자동 수집: Vercel에 배포만 하면 trace가 자동으로 ingest돼요. 별도 SDK 연동이나 설정이 필요 없어요.
- reasoning까지 노출: 단순 입출력 로그가 아니라 모델이 어떤 사고 과정을 거쳤는지까지 남아요. 환각(hallucination) 원인 추적에 특히 유용합니다.
- 토큰 사용량 추적: run별 토큰 소비를 볼 수 있어서 비용 최적화의 출발점이 돼요.
- 에이전트 자기 디버깅: CLI + markdown 파이프 조합은 MCP 없는 환경에서 특히 강력해요.
주의할 점
- Vercel 종속성: Agent Runs는 Vercel 배포 환경에서 자동 ingest되는 구조예요. 다른 클라우드나 온프레미스에서 돌리는 에이전트는 이 혜택을 못 받아요.
- eve 프레임워크 전제: 지금 설명된 흐름은 eve 에이전트 프레임워크 기준이에요. LangChain, CrewAI 등 다른 프레임워크를 쓴다면 별도 연동이 필요할 수 있어요.
- trace 데이터 양: reasoning과 tool 입출력까지 전부 저장하면 데이터가 상당히 커져요. 장기 보관 정책과 비용을 미리 확인해두는 게 좋아요.
- 민감정보 노출 위험: tool 입출력이 그대로 trace에 남기 때문에, API 키나 개인정보가 tool 인자로 들어가면 그대로 기록될 수 있어요. 마스킹 정책을 반드시 점검하세요.
국내 개발 생태계에서의 적용 맥락
국내에서는 아직 Vercel을 메인 배포 플랫폼으로 쓰는 팀이 많지 않지만, AI 에이전트 PoC를 빠르게 돌리는 팀이라면 얘기가 달라요. 특히 사내망이 막혀 MCP 서버를 못 띄우는 환경에서도 CLI만으로 trace 조회가 가능하다는 점은 꽤 실용적이에요. 폐쇄망에서 돌아가는 코딩 에이전트에게 vercel agent-runs trace --json을 시키는 식의 활용이 가능하니까요.
다만 국내 SI/금융권처럼 데이터 외부 반출이 민감한 조직에서는 trace에 reasoning과 tool 입출력이 통째로 남는다는 사실을 반드시 사전에 공유해야 해요. "에이전트가 뭘 했는지 다 보인다"는 건 양날의 검이거든요.
정리하면
Vercel Agent Runs는 **"에이전트를 만들었는데 왜 이러는지 모르겠다"**는 개발자들의 오랜 불만을 정면으로 해결하는 기능이에요. MCP 도구 4종과 CLI 명령어 4종, 그리고 --json/markdown 파이프 조합만 기억하면 됩니다.
다음 단계 학습 방향
- eve 프레임워크 템플릿으로 시작 — 템플릿 하나 골라서 배포하고, 첫 run부터 trace를 뜯어보세요.
- MCP 도구를 코딩 에이전트에 연결 —
npx add-mcp https://mcp.vercel.com한 줄이면 됩니다. - CLI 자기 디버깅 루프 실험 — 에이전트에게 자기 run을 분석시켜 스킬을 개선하는 워크플로를 만들어보세요.
- 토큰 사용량 대시보드화 —
--json출력을 모아서 run별 비용을 추적하면 최적화 포인트가 보여요.
함께 보면 좋은 글
- AI 시대, "될까요?" 말고 "얼마나 될까요?"를 물어야 하는 이유 — 확률적 시스템을 다루는 관점에서 에이전트 디버깅을 다시 생각해볼 수 있어요.
- 파이썬 3.14.3 출시! 알아둬야 할 주요 변화와 실무 영향 — 에이전트 백엔드를 파이썬으로 짠다면 함께 체크해두세요.