트레이싱

트레이싱 (Tracing)

**세션(session)**은 에이전트의 대화와 작업을 함께 유지해요. 세션은 여러 **턴(turn)**을 포함할 수 있고, 각 턴은 한 차례의 작업 주기예요. **트레이스(trace)**는 한 턴 안의 단계들, 즉 모델 응답, 도구 호출, 다른 에이전트에 위임된 작업을 보여 줘요.

출처: 문서

본문

트레이싱 대시보드는 에이전트가 무엇을 했는지, 각 단계의 기록된 입력, 출력, 지속 시간, 상태를 보여 줘요.

API를 통한 세션 상태, 실시간 이벤트, 저장된 출력, 사용량은 Observability부터 시작하세요.

트레이싱은 새 세션에서 기본적으로 활성화돼요. 대시보드에서 트레이스를 검사하거나 API로 내보낼 수 있어요.

트레이스 열기 (Open a trace)

Logs → Agents를 열고 에이전트를 실행한 프로젝트를 선택하세요.
Search logs로 세션을 찾으세요. Add filter로 모델, 상태, 날짜별로 필터링할 수 있어요.
세션을 선택해 타임라인과 턴 목록을 여세요.
턴을 펼친 다음 타임라인이나 이벤트 목록에서 단계를 선택해 세부 정보를 보세요.

세션 요약은 상태, 모델, 시작 시간, 마지막 활동, 턴 수, 기록된 토큰 사용량을 보여 줘요.

트레이스 읽기 (Read a trace)

세션부터 시작해 한 턴 안으로 들어가 보세요:

Session: Logs → Agents의 각 항목은 세션입니다. 열어서 타임라인과 턴 목록을 보세요. 예를 들어 사용자가 주문에 대해 물어본 뒤 같은 세션에서 후속 질문을 할 수 있어요.
Turn: 턴을 펼쳐 그 주기 동안의 작업을 보세요. 한 턴에는 여러 모델 응답과 도구 호출이 포함될 수 있어요. 턴이 끝난 뒤 보낸 후속 메시지는 같은 세션에서 새 턴을 시작해요.
Steps within the turn: 트레이스는 모델 응답과 도구 호출을 그것을 수행한 루트 에이전트 또는 서브에이전트 아래에 묶어요. 기록된 각 단계를 **스팬(span)**이라고 해요.

스팬을 선택하면 상태, 지속 시간, 시작·종료 시간, 기록된 데이터를 볼 수 있어요:

선택	검사할 수 있는 것
Agent	에이전트의 세부 정보, 지시사항, 기록된 토큰 사용량
Generation (모델 응답)	모델 응답에 대한 기록된 입력과 출력
Tool	어떤 도구가 호출됐는지, 보낸 인자, 가능할 때의 결과

Agent

에이전트 스팬은 루트 에이전트 또는 서브에이전트(과제 일부를 처리하도록 요청받은 다른 에이전트)가 수행한 작업을 묶어요. 모델 응답과 도구 호출은 그것을 수행한 에이전트 아래에 나타나요.

세부 정보 패널이 보여 주는 것:

Agent type: 루트 에이전트(root) 또는 서브에이전트(subagent).
Agent: 기록될 때의 ID, 이름, 모델, 지시사항.
Usage: 그 에이전트의 기록된 토큰 수. 이 수치는 에이전트 자체만 다루고 서브에이전트는 포함하지 않아요.
Duration 및 Outcome status: 기록된 작업이 얼마나 걸렸는지, 완료·실패·미완료 중 어느 상태인지.

Generation

generation 스팬은 기록된 모델 입력과 출력을 묶어요. 각 턴에는 여러 generation이 있을 수 있어요.

모델 추론 중에 모델이 입력을 읽고 응답을 만들어요. 그 응답이 도구를 요청할 수 있어요. 도구가 반환되면 모델이 새 generation에서 또 다른 응답을 만들 수 있어요.

Input: 그 응답과 관련된 기록된 입력(예: 사용자 메시지 또는 도구 결과).
Output: 모델이 만든 기록된 항목(예: 답변 텍스트 또는 도구 호출).
Model: 기록될 때 응답에 사용된 모델.

Tool

tool 스팬은 도구 호출과 그 기록된 결과를 설명해요.

tool 스팬에는 함수에 대한 호출과 MCP(Model Context Protocol) 서버의 도구 호출이 포함돼요. 웹 검색과 명령 실행도 tool 스팬으로 나타날 수 있어요.

Call: 도구 이름과 인자를 포함한 도구 요청(있을 때).
Result: 가능할 때 도구의 기록된 응답.
Outcome status 및 Error: 있을 때 기록된 결과와 오류 세부 정보.

MCP 도구 호출의 Call은 서버 라벨(server_label), 도구 이름(name), 인자(arguments)를 포함해요. 그 응답과 오류는 있을 때 output과 error로 거기에 기록돼요. 별도의 Result 패널은 MCP 응답이 Call에 저장되므로 비어 있을 수 있어요.

타이밍과 상태 (Timing and status)

타임라인은 단계들의 순서와 어떤 것이 겹치는지 보여 줘요. Zoom in은 더 짧은 단계를 더 자세히 보여 주고, Fit timeline은 전체 세션을 보여 줘요.

각 스팬은 지속 시간과 결과 상태를 보여 줘요. 실패한 스팬은 기록된 오류 세부 정보도 포함할 수 있어요.

에이전트 스팬의 지속 시간에는 하위 단계가 포함돼요. 단계는 겹칠 수 있어요. 두 서브에이전트가 10초 동안 함께 실행되면 경과 시간 약 10초를 차지해요.

토큰 사용량 (Token usage)

세션 요약의 Tokens는 세션 사용량을 보여 줘요. 에이전트 스팬의 Usage는 그 에이전트의 기록된 토큰 수를 보여 줘요.

사용량은 턴이 끝난 뒤 도착할 수 있어요. 빈 값 또는 null은 수치를 알 수 없다는 뜻이에요. 에이전트가 0 토큰을 사용했다는 뜻이 아니에요. 더 많은 사용량이 가능해지면 수치가 바뀔 수 있고 최종 청구서가 아니에요.

트레이스가 준비되는 시점 (When traces are ready)

트레이스는 턴이 끝난 뒤 만들어져요. 에이전트의 답이 그 트레이스나 토큰 사용량보다 먼저 나타날 수 있어요.

실시간 세션 이벤트는 에이전트가 아직 작업하는 동안 진행 상황을 보여 줘요.

세션 트레이스 내보내기 (Export session traces)

세션 트레이스를 다운로드해 다른 트레이싱 도구에서 검사해 보세요. GET /v1/agents/sessions/{session_id}/traces 엔드포인트는 OpenTelemetry Protocol(OTLP) JSON을 포함한 트레이스 페이지를 반환해요.

조직에 트레이스 내보내기가 활성화돼 있어야 해요. 세션 프로젝트의 API 키에 트레이스 읽기 권한(api.traces.read) 또는 더 넓은 에이전트 읽기 권한(api.agents.read)을 사용하세요.

OPENAI_API_KEY를 설정하고 sess_123을 세션 ID로 바꾸세요. 이 예시는 cURL과 jq를 사용해 한 페이지를 traces.otlp.json으로 저장해요:

세션 트레이스 한 페이지 다운로드하기

curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc" \
  -H "Authorization: Bearer ***" \
  -H "OpenAI-Beta: agents=v1" \
  --output trace-page.json && \
jq '{resourceSpans: [.data[].otlp.resourceSpans[]]}' trace-page.json > traces.otlp.json

이 명령은 그 페이지의 트레이스를 하나의 OTLP 페이로드로 합쳐요. 프로바이더의 인증을 사용해 트레이싱 프로바이더의 OTLP/HTTP 엔드포인트로 보내세요.

전체 세션을 내보내려면 trace-page.json을 확인하세요. has_more가 true일 때 같은 order를 유지하고 last_id를 after로 사용해 다음 페이지를 요청하세요. 다음 페이지를 가져오기 전에 각 페이지를 저장하거나 업로드하고, has_more가 false가 될 때까지 반복하세요.

내보내기는 각 요청 시점에 사용 가능한 트레이스만 포함해요. 과거 내보내기에는 세션의 턴이 끝날 때까지 기다리고 트레이스가 나타날 시간을 두세요. 내보내기가 미래 트레이스의 자동 전달을 설정하지는 않아요.

에이전트용 트레이스 내보내기 (Export traces for an agent)

에이전트의 세션에 걸친 트레이스를 내보내려면 먼저 agent_id 필터로 세션을 나열하세요. agent_123을 에이전트 ID로 바꾸세요:

에이전트의 세션 찾기

curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions?agent_id=agent_123&limit=100&order=asc" \
  -H "Authorization: Bearer ***" \
  -H "OpenAI-Beta: agents=v1"

data의 각 세션에 대해 그 id를 사용해 위에서 설명한 대로 세션 트레이스의 모든 페이지를 내보내세요.
세션 목록에 has_more: true가 있으면 그 목록의 last_id를 after로 전달해 다음 페이지를 가져오세요. 같은 agent_id와 order를 유지하세요.
세션 목록에 has_more: false가 있을 때까지 반복하세요.

필터는 세션의 루트 에이전트와 일치해요. 세션 목록 커서를 각 세션의 트레이스 커서와 별도로 유지하세요.

예시: 서브에이전트 두 개가 있는 한 턴 (Example: One turn with two subagents)

이 예시는 기록된 세션을 바탕으로 해요. 루트 에이전트가 MCP 도구를 호출하는 동안 두 서브에이전트가 명령을 실행하고 문서를 가져와요. 서브에이전트 이름은 아래에서 단순화했고, 수치와 지속 시간은 기록된 트레이스에서 나온 것이에요.

세션과 턴 (Session and turn)

세션 헤더는 1 turn, 10 tool calls, 252,468 tokens를 보여 줘요. 세션 상태는 Idle이고, Turn 1은 Completed이며 지속 시간은 1m 37s예요.

턴을 펼치면 루트 에이전트와 그 하위 단계가 보여요. 트레이스에는 3개의 agent span(루트와 서브에이전트 둘), 11개의 generation span, 10개의 tool span이 있어요.

이 트리는 반복된 generation과 도구 호출을 함께 묶어요. 부모 관계를 보여 주고, 타임라인은 각 단계가 언제 실행됐는지 보여 줘요.

Session: Idle
└── Turn 1: Completed                              1m 37s
    └── Root agent                                1m 37s
        ├── 6 generations
        ├── 2 tools: spawn_agent_call
        ├── Subagent A                               24s
        │   ├── 2 generations
        │   └── Tool: command_execution               2s
        ├── Subagent B                               21s
        │   ├── 3 generations
        │   ├── 2 tools: notion.fetch              2s each
        │   └── Tool: send_input_call                 0ms
        ├── Tool: demo_capability_probe              87ms
        └── 3 tools: wait_for_agents_call

모델 작업과 위임 (Model work and delegation)

루트 에이전트의 첫 번째 Generation은 Input에 사용자 메시지를 포함해요. 그 Output은 메시지와 두 개의 spawn_agent_call 항목을 포함해요. 그 호출들도 Tool 스팬으로 나타나고, 결과로 생긴 서브에이전트는 루트 아래 Agent 스팬으로 나타나요.

Subagent A는 자체 generation과 command_execution 도구 호출이 있어요. Subagent B는 세 개의 generation, 두 개의 notion.fetch MCP 호출, 하나의 send_input_call이 있어요. 그들의 모델 응답과 도구는 각자의 서브에이전트 스팬에 속해요.

루트 에이전트는 세 개의 wait_for_agents_call tool 스팬도 있어요. 그 최종 generation은 메시지를 포함하고 기록된 지속 시간은 6s예요.

MCP 도구 호출 (An MCP tool call)

루트 에이전트의 demo_capability_probe 스팬은 지속 시간 87ms의 완료된 Tool 스팬이에요. 그 Tool type은 mcp_call이에요.

Call 패널은 이런 필드를 포함해요:

{
  "type": "mcp_call",
  "server_label": "demo_local",
  "name": "demo_capability_probe",
  "status": "completed"
}

이 발췌는 기록된 호출의 일부를 보여 줘요. 같은 패널에 arguments와 output의 MCP 응답이 포함돼요. 별도의 Result 패널은 null이에요. 스팬의 Parent span은 루트 에이전트를 가리켜요.

Subagent B의 두 notion.fetch 스팬도 같은 구조예요: 도구 유형 mcp_call, Call 안의 MCP 응답, 부모가 해당 서브에이전트.

이 세션의 타이밍과 사용량 (Timing and usage in this session)

두 서브에이전트 스팬은 타임라인에서 겹쳐요. Subagent A는 24s, Subagent B는 21s가 걸리고, 둘 다 루트 에이전트의 1m 37s 스팬 안에 들어요. 대시보드는 표시된 지속 시간을 반올림해요.

각 에이전트 스팬의 Usage 패널은 자체 기록된 토큰 수를 보여 줘요:

Agent	Input tokens	Output tokens	Total tokens
Root agent	126,390	1,567	127,957
Subagent A	34,075	465	34,540
Subagent B	89,304	667	89,971

이 기록된 세션에서 세 에이전트 합계를 더하면 세션 헤더의 252,468 tokens가 돼요.

더 알아보기 (Learn more)

Observability에서 API를 통한 세션 상태와 사용량을 확인하세요.
Multi-agent에서 서브에이전트 위임을 확인하세요.