이벤트 기록

POST /openapi/v1/events/batch로 이벤트를 한 번에 1개부터 100개까지 기록합니다. 전체 요청 본문은 1 MiB 이하여야 하며, 각 payload는 JSON 인코딩 후 256 KiB 이하여야 합니다.

이벤트 필드

필드	타입	필수	설명
`eventId`	string	예	중복 방지 키입니다. 재시도할 때도 같은 값을 사용합니다. 최대 160자입니다.
`clientId`	string	예	SDK 설치나 프로세스 그룹을 나타내는 고정 식별자입니다. 최대 120자입니다.
`runId`	string	예	한 번의 에이전트 실행입니다. 최대 255자입니다.
`sessionId`	string	아니요	하나의 대화처럼 서로 관련된 Run을 묶습니다.
`agentId`	string	아니요	외부 시스템에서 사용하는 고정 에이전트 식별자입니다.
`agentName`	string	예	사람이 읽을 수 있는 에이전트 이름입니다.
`eventType`	string	예	이벤트 종류입니다. 최대 50자입니다.
`label`	string	예	타임라인에 표시할 짧은 이름입니다. 최대 255자입니다.
`timestamp`	integer	예	밀리초 단위 Unix 시간입니다.
`payload`	object	아니요	이벤트별 데이터입니다. 기본값은 `{}`입니다.
`schemaVersion`	string	아니요	이벤트 전송 계약 버전입니다. `1.0`을 사용합니다. 기존 값 `1`도 허용하며 `1.0`으로 변환해 저장합니다.

timestamp는 현재보다 최대 30일 전, 최대 5분 후까지 허용됩니다. schemaVersion을 생략하면 서버는 1.0으로 저장합니다. 지원하지 않는 버전은 호환되지 않는 payload를 잘못 해석하지 않도록 요청 검증 단계에서 거절합니다. 선택 필드인 workspaceId는 확인용 값일 뿐입니다. API 키가 가리키는 워크스페이스와 다르면 해당 이벤트는 거절됩니다.

배치 예시

[
  {
    "eventId": "evt_llm_01",
    "clientId": "go-service",
    "runId": "run_checkout_938",
    "sessionId": "session_user_42",
    "agentId": "checkout-agent",
    "agentName": "checkout-agent",
    "eventType": "LLM_CALL",
    "label": "Choose payment action",
    "schemaVersion": "1.0",
    "timestamp": 1784808000000,
    "payload": {
      "model": "model-name",
      "latency": 420,
      "cost": 0.0021,
      "usage": {
        "promptTokens": 240,
        "completionTokens": 32,
        "totalTokens": 272
      }
    }
  }
]

한 번의 실행에서 발생한 이벤트에는 같은 runId를 사용합니다. 서로 관련된 여러 실행에는 같은 sessionId를 사용합니다.

일부 성공 응답

{
  "success": false,
  "accepted": 1,
  "retryableEventIds": ["evt_tool_02"],
  "rejectedEventIds": ["evt_invalid_03"]
}

서버는 이벤트를 각각 처리합니다.

접수된 이벤트는 로컬 큐에서 제거합니다.
retryableEventIds에 있는 이벤트만 다시 보냅니다.
rejectedEventIds는 다시 보내지 않고 로컬 진단 기록만 남깁니다.
이미 저장된 eventId를 다시 보내면 접수 성공으로 처리됩니다.

원래 배치 전체를 그대로 다시 보내지 마세요. 같은 ID를 다시 보내도 중복 저장되지는 않지만 불필요한 요청이 늘어납니다.

권장 이벤트 종류

다른 언어 SDK는 다음 종류부터 구현할 수 있습니다.

USER_INPUT
AGENT_STEP
LLM_CALL
TOOL_CALL
POLICY_DECISION
PROMPT_EXPOSURE
ERROR
SESSION_OUTCOME

SESSION_OUTCOME은 Run을 종료합니다. payload.status에는 COMPLETED, FAILED, CANCELLED 중 하나를 넣습니다. Run에서 활성 프롬프트 실험의 변형을 처음 사용할 때 PROMPT_EXPOSURE를 한 번 전송합니다. 전송 유실에 대비해 SESSION_OUTCOME에도 같은 promptExposures 배열을 포함합니다.

{
  "promptExposures": [
    {
      "experimentId": "a247c152-3277-4c91-9b22-95cb7a459d1e",
      "promptId": "72adbb57-96ad-4d3d-a2dc-8faf071673e5",
      "promptVersionId": "c1821bc3-bf1e-46ef-b210-b9376a41cd0c",
      "bucket": 42,
      "runtimeConfigRevision": "revision-1"
    }
  ]
}

assignmentKey 원문은 전송하지 않습니다. 서버는 실험, 변형, 환경, Agent 범위가 인증된 API Key와 일치하는지 확인한 뒤 노출 기록을 저장합니다. 서버는 다른 이벤트 문자열도 받을 수 있지만, 공통된 이름을 사용해야 대시보드와 실행 디버깅이 더 유용해집니다.

metadata-only 모드에서는 프롬프트 본문, 모델 응답, 도구 인자를 보내지 마세요. 모든 수집 모드에서 이벤트를 만들기 전에 인증 정보와 개인정보를 마스킹하세요.

시작하기

TypeScript SDK

OpenAPI

이벤트 기록

이벤트 필드

배치 예시

일부 성공 응답

권장 이벤트 종류

​이벤트 필드

​배치 예시

​일부 성공 응답

​권장 이벤트 종류

이벤트 필드

배치 예시

일부 성공 응답

권장 이벤트 종류