트레이싱

세션에는 에이전트와 나눈 대화와 에이전트가 수행한 작업이 함께 기록됩니다. 한 세션에는 여러 턴이 있을 수 있으며, 각 턴은 한 차례의 작업 주기입니다. 트레이스는 한 턴에서 어떤 단계를 거쳤는지 보여 줍니다. 여기에는 모델 응답, 도구 호출, 다른 에이전트에 위임한 작업이 포함됩니다.

트레이싱 대시보드에서 에이전트가 수행한 작업과 각 단계에 기록된 입력, 출력, 소요 시간, 상태를 확인할 수 있습니다.

API로 세션 상태, 실시간 이벤트, 저장된 출력, 사용량을 확인하려면 관측 가능성 가이드부터 살펴보세요.

새 세션에서는 트레이싱이 기본으로 활성화됩니다. 대시보드에서 트레이스를 확인하거나 API로 내보낼 수 있습니다.

트레이스 열기

1. 로그 → 에이전트를 열고 에이전트를 실행한 프로젝트를 선택하세요.
2. 로그 검색에서 세션을 찾으세요. 필터 추가에서 모델, 상태 또는 날짜로 검색 결과를 좁히세요.
3. 세션을 선택해 타임라인과 턴 목록을 여세요.
4. 턴을 펼친 다음 타임라인이나 이벤트 목록에서 단계를 선택해 세부 정보를 확인하세요.

세션 요약에는 상태, 모델, 시작 시각, 마지막 활동, 턴 수, 기록된 토큰 사용량이 표시됩니다.

트레이스 읽기

먼저 세션을 열고 턴 안의 단계를 차례로 살펴보세요.

1. 세션: 로그 → 에이전트의 각 항목은 하나의 세션입니다. 세션을 열면 타임라인과 턴 목록이 표시됩니다. 예를 들어 사용자는 주문에 관해 문의한 뒤 같은 세션에서 추가 질문을 할 수 있습니다.
2. 턴: 턴을 펼치면 해당 주기에 수행한 작업이 표시됩니다. 한 턴에는 모델 응답과 도구 호출이 여러 개 포함될 수 있습니다. 턴이 끝난 뒤 후속 메시지를 보내면 같은 세션에서 새 턴이 시작됩니다.
3. 턴 안의 단계: 트레이스에서는 모델 응답과 도구 호출을 해당 작업을 수행한 루트 에이전트나 하위 에이전트 아래에 묶어 표시합니다. 이렇게 기록된 각 단계를 스팬이라고 합니다.

스팬을 선택하면 상태, 소요 시간, 시작 및 종료 시각, 기록된 데이터를 확인할 수 있습니다.

에이전트

에이전트 스팬은 루트 에이전트 또는 하위 에이전트가 수행한 작업을 묶어 보여 줍니다. 하위 에이전트는 작업의 일부를 위임받은 다른 에이전트입니다. 모델 응답과 도구 호출은 이를 수행한 에이전트 아래에 표시됩니다.

세부 정보 패널에는 다음 항목이 표시됩니다.

• 에이전트 유형: 루트 에이전트(root) 또는 하위 에이전트(subagent).
• 에이전트: 에이전트의 ID, 이름, 모델, 지침 중 기록된 정보를 표시합니다.
• 사용량: 해당 에이전트에 기록된 토큰 수입니다. 에이전트 자체의 사용량만 집계하며 하위 에이전트의 사용량은 제외합니다.
• 소요 시간 및 결과 상태: 기록된 작업에 걸린 시간과 작업의 완료, 실패 또는 미완료 여부를 표시합니다.

생성

생성 스팬은 기록된 모델 입력과 출력을 묶어 보여 줍니다. 한 턴에서 생성이 여러 번 이루어질 수 있습니다.

추론 과정에서 모델은 입력을 읽고 응답을 생성합니다. 이 응답에서 도구 호출을 요청할 수 있습니다. 도구가 결과를 반환하면 모델은 새 생성 단계에서 다시 응답할 수 있습니다.

• 입력: 사용자 메시지나 도구 결과처럼 해당 응답과 관련해 기록된 입력입니다.
• 출력: 답변 텍스트나 도구 호출처럼 모델이 생성한 항목 중 기록된 내용입니다.
• 모델: 응답 생성에 사용한 모델 정보가 기록되어 있으면 표시합니다.

도구

도구 스팬은 도구 호출과 기록된 결과를 보여 줍니다.

도구 스팬에는 직접 정의한 함수 호출과 MCP(Model Context Protocol) 서버의 도구 호출이 포함됩니다. 웹 검색과 명령어 실행도 도구 스팬으로 표시될 수 있습니다.

• 호출: 도구에 보낸 요청입니다. 도구 이름과 인수가 있으면 함께 표시합니다.
• 결과: 기록된 도구 응답이 있으면 표시합니다.
• 결과 상태 및 오류: 기록된 결과 상태와 오류 세부 정보가 있으면 표시합니다.

MCP 도구 호출의 호출 패널에는 서버 레이블(server_label), 도구 이름(name), 인수(arguments)가 포함됩니다. 응답과 오류가 있으면 같은 패널에 각각 output과 error로 기록됩니다. 별도의 결과 패널은 비어 있을 수 있습니다. MCP 응답이 호출 패널에 저장되기 때문입니다.

실행 시간과 상태

타임라인에서는 각 단계의 실행 순서와 동시에 실행된 단계를 확인할 수 있습니다. 확대를 선택하면 짧은 단계를 자세히 볼 수 있습니다. 타임라인 맞춤을 선택하면 세션 전체가 한눈에 보입니다.

각 스팬에는 소요 시간과 결과 상태가 표시됩니다. 실패한 스팬에는 기록된 오류 세부 정보도 포함될 수 있습니다.

에이전트 스팬의 소요 시간에는 하위 단계의 실행 시간이 포함됩니다. 여러 단계가 겹칠 수 있으므로 두 하위 에이전트가 10초 동안 동시에 실행되면 실제 경과 시간은 약 10초입니다.

토큰 사용량

세션 요약의 토큰 항목에는 세션 전체의 사용량이 표시됩니다. 에이전트 스팬의 사용량 항목에는 해당 에이전트에 기록된 토큰 수가 표시됩니다.

사용량 데이터는 턴이 끝난 뒤에 도착할 수 있습니다. 값이 비어 있거나 null이면 토큰 수를 아직 알 수 없다는 뜻입니다. 에이전트가 토큰을 0개 사용했다는 뜻은 아닙니다. 사용량 데이터가 추가되면 토큰 수가 달라질 수 있으며, 이 수치는 최종 청구 내역이 아닙니다.

트레이스를 확인할 수 있는 시점

트레이스는 턴이 끝난 뒤 생성됩니다. 트레이스나 토큰 사용량을 확인할 수 있게 되기 전에 에이전트의 답변이 먼저 표시될 수 있습니다.

에이전트가 작업하는 동안에는 실시간 세션 이벤트에서 진행 상황을 확인할 수 있습니다.

세션 트레이스 내보내기

세션 트레이스를 다운로드하면 다른 트레이싱 도구에서 살펴볼 수 있습니다. GET /v1/agents/sessions/{session_id}/traces 엔드포인트는 OpenTelemetry Protocol(OTLP) JSON 형식의 트레이스를 한 페이지씩 반환합니다.

OPENAI_API_KEY를 설정하고 sess_123을 실제 세션 ID로 바꾸세요. 다음 예시에서는 cURL과 jq를 사용해 한 페이지를 traces.otlp.json으로 저장합니다.

1
2
3
4
5
6curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -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이면 last_id를 after 값으로 전달하고 order는 그대로 유지해 다음 페이지를 요청하세요. 다음 페이지를 가져오기 전에 현재 페이지를 저장하거나 업로드하세요. has_more가 false가 될 때까지 반복하세요.

각 요청에서는 요청 시점에 준비된 트레이스만 내보냅니다. 과거 세션의 기록을 내보내려면 세션의 턴이 모두 끝나고 트레이스가 표시될 때까지 기다리세요. 트레이스를 내보내도 이후의 트레이스가 자동으로 전송되지는 않습니다.

에이전트의 트레이스 내보내기

한 에이전트의 여러 세션에서 트레이스를 내보내려면 먼저 세션 목록을 조회할 때 agent_id 필터를 사용하세요. agent_123을 실제 에이전트 ID로 바꾸세요.

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

1. data에 있는 각 세션의 id를 사용해 앞에서 설명한 방법으로 해당 세션의 트레이스를 마지막 페이지까지 내보내세요.
2. 세션 목록에 has_more: true가 있으면 목록의 last_id를 after 값으로 전달해 다음 페이지를 가져오세요. agent_id와 order는 그대로 유지하세요.
3. 세션 목록에 has_more: false가 표시될 때까지 반복하세요.

이 필터는 세션의 루트 에이전트를 기준으로 세션을 찾습니다. 세션 목록의 커서와 각 세션의 트레이스 커서는 별도로 관리하세요.

예시: 하위 에이전트 두 개가 참여한 턴

다음은 실제로 기록된 세션을 바탕으로 한 예시입니다. 루트 에이전트가 MCP 도구를 호출하는 동안 두 하위 에이전트는 각각 명령어를 실행하고 문서를 가져옵니다. 아래에서는 하위 에이전트 이름을 간략하게 표기했으며, 횟수와 소요 시간은 기록된 트레이스의 값을 사용했습니다.

세션과 턴

세션 헤더에는 턴 1개, 도구 호출 10회, 토큰 252,468개가 표시됩니다. 세션 상태는 유휴이며, 턴 1의 상태는 완료, 소요 시간은 1분 37초입니다.

턴을 펼치면 루트 에이전트와 그 하위 단계가 표시됩니다. 트레이스에는 에이전트 스팬 3개(루트 에이전트와 하위 에이전트 두 개), 생성 스팬 11개, 도구 스팬 10개가 있습니다.

아래 트리는 반복된 생성과 도구 호출을 묶어 상위 단계와 하위 단계의 관계를 보여 줍니다. 각 단계가 실행된 시점은 타임라인에서 확인할 수 있습니다.

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

모델 작업과 위임

루트 에이전트의 첫 번째 생성 스팬에서 입력 항목에는 사용자 메시지가 있습니다. 출력 항목에는 메시지와 spawn_agent_call 항목 두 개가 있습니다. 이 호출들은 도구 스팬으로도 표시되며, 호출로 생성된 하위 에이전트들은 루트 에이전트 아래에 에이전트 스팬으로 표시됩니다.

하위 에이전트 A에는 자체 생성 단계와 command_execution 도구 호출이 있습니다. 하위 에이전트 B에는 생성 단계 세 개, notion.fetch MCP 호출 두 번, send_input_call 호출 한 번이 있습니다. 각 에이전트의 모델 응답과 도구 호출은 해당 하위 에이전트의 스팬에 속합니다.

루트 에이전트에는 wait_for_agents_call 도구 스팬도 세 개 있습니다. 마지막 생성 단계에는 메시지가 포함되어 있으며, 기록된 소요 시간은 6초입니다.

MCP 도구 호출

루트 에이전트의 demo_capability_probe 스팬은 완료된 도구 스팬이며 소요 시간은 87밀리초입니다. 도구 유형 값은 mcp_call입니다.

호출 패널에는 다음 필드가 있습니다.

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

위 예시는 기록된 호출의 일부입니다. 같은 패널에 arguments가 있으며, MCP 응답은 output에 들어 있습니다. 별도의 결과 패널 값은 null입니다. 이 스팬의 상위 스팬 항목은 루트 에이전트를 가리킵니다.

하위 에이전트 B의 notion.fetch 스팬 두 개도 구조가 같습니다. 도구 유형은 mcp_call이고, MCP 응답은 호출 패널에 있으며, 두 스팬 모두 하위 에이전트 B의 스팬에 속합니다.

이 세션의 실행 시간과 사용량

두 하위 에이전트의 스팬은 타임라인에서 겹칩니다. 하위 에이전트 A는 24초, 하위 에이전트 B는 21초 동안 실행되었으며, 두 구간 모두 루트 에이전트의 1분 37초 스팬 안에 있습니다. 대시보드는 소요 시간을 반올림해 표시합니다.

각 에이전트 스팬의 사용량 패널에는 해당 에이전트에 기록된 토큰 수가 표시됩니다.

이 세션에서 세 에이전트의 총 토큰 수를 합하면 세션 헤더에 표시된 토큰 252,468개와 일치합니다.