Agent Traces

Claude Code, Codex, Pi Agent의 Agent trace는 Hugging Face Hub에서 네이티브로 지원돼요. 원시 JSONL 세션을 Dataset이나 Storage Bucket에 업로드하면 전용 trace 뷰어에서 열 수 있어요. Dataset은 Data Studio에서 trace를 보여주고, bucket은 개별 .jsonl 파일을 직접 열 수 있게 해줘요.

출처: 문서

본문

trace 찾기

지원되는 각 에이전트는 JSONL 세션을 다음 디렉토리에 작성해요.

Agent	로컬 세션 디렉토리
Claude Code	`~/.claude/projects`
Codex	`~/.codex/sessions`
Pi	`~/.pi/agent/sessions`

이런 trace 파일은 기본 지원되므로, 먼저 수정하거나 변환하지 않고 업로드할 수 있어요.

직접 harness를 만들고 있나요? 에이전트가 위 목록에 없다면, Session Traces Format을 사용해 세션을 trace 뷰어에서 렌더링할 수 있어요.

trace 파일에는 프롬프트, 도구 입력, 명령 출력, 로컬 경로, 스크린샷, 시크릿, 비공개 코드, 개인 데이터가 포함될 수 있어요. 공개 게시 전에 trace를 검토하고 정리(redact)하거나, 안에 뭐가 있는지 확실하지 않으면 dataset이나 bucket을 비공개로 유지하세요.

Pi Agent 세션의 경우 pi-share-hf가 프로젝트 세션 수집, 알려진 시크릿 정리, TruffleHog 및 LLM 리뷰 실행, 검사를 통과한 세션만 업로드하는 것을 도와줄 수 있어요.

가장 쉬운 업로드 방법은 에이전트 자신에게 물어보는 거예요. 위 디렉토리를 가리키고 .jsonl 파일을 Hub dataset이나 bucket에 업로드하라고 지시하면 돼요.

새 세션이 생길 때마다 계속 동기화하고 싶다면 bucket이 특히 유용해요.

trace 업로드

dataset이나 bucket을 만든 뒤, 권장 독립형 인스톨러로 hf CLI를 설치하고 로그인하세요. 인스톨러는 Hugging Face CLI Skill도 설정하므로, 코딩 에이전트가 hf 명령을 대신 실행할 수 있어요.

curl -LsSf https://hf.co/cli/install.sh | bash
hf auth login

hf upload <username>/<dataset-name> ~/.codex/sessions . --repo-type dataset
hf buckets sync ~/.codex/sessions hf://buckets/<username>/<bucket-name>/codex

~/.codex/sessions를 에이전트에 맞는 세션 디렉토리로 바꾸세요. dataset에는 hf upload를, 새 trace가 작성될 때마다 업데이트할 bucket에는 hf buckets sync를 사용해요. 더 짧은 hf sync 명령은 hf buckets sync의 별칭이에요.

trace 보기

dataset에 trace가 있으면 Data Studio를 열고 행을 클릭하세요. Storage Bucket의 trace는 검사하려는 .jsonl 파일로 이동해 열어요. trace 뷰어는 세션 타임라인, 프롬프트, 어시스턴트 메시지, 도구 호출, 결과를 보여줘요.

공개 예시로 TeichAI/DeepSeek-v4-Pro-Agent를 열어보세요. traces로 태그된 더 많은 dataset도 둘러볼 수 있어요.

더 알아보기 (Learn more)

Claude Code·Codex·Pi의 JSONL 세션을 변환 없이 그대로 dataset이나 bucket에 업로드하면 전용 trace 뷰어에서 열 수 있어요. 공개 전에 trace 안의 시크릿·개인 데이터를 꼭 정리하고, 지속 동기화가 필요하면 hf buckets sync를 쓰세요.