이벤트 기록

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	아니요	클라이언트 이벤트 형식의 버전입니다.

timestamp는 현재보다 최대 30일 전, 최대 5분 후까지 허용됩니다. 선택 필드인 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
ERROR
SESSION_OUTCOME

SESSION_OUTCOME은 Run을 종료합니다. payload.status에는 COMPLETED, FAILED, CANCELLED 중 하나를 넣습니다. 서버는 다른 이벤트 문자열도 받을 수 있지만, 공통된 이름을 사용해야 대시보드와 실행 디버깅이 더 유용해집니다.

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

시작하기

TypeScript SDK

OpenAPI

이벤트 기록

이벤트 필드

배치 예시

일부 성공 응답

권장 이벤트 종류

​이벤트 필드

​배치 예시

​일부 성공 응답

​권장 이벤트 종류

이벤트 필드

배치 예시

일부 성공 응답

권장 이벤트 종류