# Agent Traces

Claude Code, Codex, Pi, Hermes Agent, Factory Droid의 Agent traces는 Hugging Face Hub에서 네이티브로 지원됩니다. 원본 JSONL 세션을 [Dataset](https://huggingface.co/datasets?format=format%3Aagent-traces) 또는 [Storage Bucket](./storage-buckets)에 업로드하면 전용 trace viewer에서 열 수 있습니다. Dataset은 Data Studio에서 traces를 표시하고, bucket은 개별 `.jsonl` 파일을 직접 열 수 있습니다.

## 를 찾아보세요

대부분의 지원되는 에이전트는 JSONL 세션을 로컬 디렉토리에 기록합니다:

| 에이전트         | 로컬 세션 디렉터리      |
| ------------- | ---------------------------- |
| Claude Code   | `~/.claude/projects`         |
| Codex         | `~/.codex/sessions`          |
| Codex 아카이브 | `~/.codex/archived_sessions` |
| Factory/Droid | `~/.factory/sessions`        |
| Pi            | `~/.pi/agent/sessions`       |

이러한 trace 파일은 기본적으로 지원되므로, 수정하거나 변환하지 않고 바로 업로드할 수 있습니다.

Hermes Agent는 현재 세션을 세션 데이터베이스에 저장합니다. 업로드하기 전에 공유하려는 세션을 JSONL로 내보내세요:

```bash
hermes sessions export session.jsonl --session-id <session_id>
```

직접 harness를 구축하고 계신가요? 위 목록에 없는 에이전트라면 [Session Traces Format](./session-traces-format)을 출력하여 trace viewer에서 해당 세션을 렌더링할 수 있습니다.

Trace 파일에는 프롬프트, 도구 입력값, 명령 출력, 로컬 경로, 스크린샷, 시크릿, 비공개 코드, 개인 데이터가 포함될 수 있습니다. 공개적으로 게시하기 전에 trace를 검토하고 민감한 부분을 삭제하거나, 파일의 내용이 불분명한 경우 데이터셋 또는 버킷을 비공개로 유지하세요.

Pi Agent 세션의 경우, [`pi-share-hf`](https://github.com/badlogic/pi-share-hf)를 사용하면 프로젝트 세션을 수집하고 알려진 시크릿을 마스킹한 뒤 TruffleHog 및 LLM 리뷰를 실행하여 검사에 통과한 세션만 업로드할 수 있습니다.

가장 쉬운 업로드 방법은 에이전트 자체에게 요청하는 것입니다. 위에서 언급한 디렉터리 또는 내보낸 JSONL 파일을 가리키며 `.jsonl` 파일을 Hub 데이터셋 또는 버킷에 업로드하도록 지시하세요.

새 세션이 계속 들어오는 동안 트레이스를 지속적으로 동기화하려면 버킷이 특히 유용합니다.

## 를 업로드하세요

데이터셋 또는 버킷을 생성한 후, [권장 스탠드얼론 설치 프로그램](/docs/huggingface_hub/guides/cli#getting-started)을 사용하여 `hf` CLI를 설치하고 로그인하세요. 설치 프로그램은 [Hugging Face CLI Skill](./agents-cli)도 설정하므로, 코딩 에이전트가 대신 `hf` 명령을 실행할 수 있습니다.

```bash
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`를 에이전트에 해당하는 세션 디렉터리로, 또는 Hermes Agent에서 내보낸 JSONL 파일을 포함하는 디렉터리로 교체하세요. 데이터셋에는 `hf upload`를, 새 트레이스가 기록될 때마다 업데이트하려는 버킷에는 `hf buckets sync`를 사용하세요. 더 짧은 `hf sync` 명령은 `hf buckets sync`의 별칭입니다.

## 트레이스를 확인하세요

데이터셋에 트레이스가 있으면 Data Studio를 열고 행을 클릭합니다. Storage Bucket에 있는 트레이스의 경우, 검사하려는 `.jsonl` 파일로 이동하여 파일을 엽니다. 트레이스 뷰어에는 세션 타임라인, 프롬프트, 어시스턴트 메시지, 도구 호출, 셸 출력, 추론 블록, 결과가 표시됩니다.

공개 예시로 [`TeichAI/DeepSeek-v4-Pro-Agent`](https://huggingface.co/datasets/TeichAI/DeepSeek-v4-Pro-Agent)을 열 수 있습니다. 또한 [`traces`](https://huggingface.co/datasets?format=format%3Aagent-traces) 태그가 지정된 더 많은 데이터셋을 탐색할 수도 있습니다.