> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynxops.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 이벤트 기록

> 언어와 관계없이 에이전트 이벤트를 안전하게 묶어서 전송합니다.

`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 키가 가리키는 워크스페이스와 다르면 해당 이벤트는 거절됩니다.

## 배치 예시

```json theme={null}
[
  {
    "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`를 사용합니다.

## 일부 성공 응답

```json theme={null}
{
  "success": false,
  "accepted": 1,
  "retryableEventIds": ["evt_tool_02"],
  "rejectedEventIds": ["evt_invalid_03"]
}
```

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

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

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

## 권장 이벤트 종류

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

```text theme={null}
USER_INPUT
AGENT_STEP
LLM_CALL
TOOL_CALL
POLICY_DECISION
ERROR
SESSION_OUTCOME
```

`SESSION_OUTCOME`은 Run을 종료합니다. `payload.status`에는 `COMPLETED`, `FAILED`, `CANCELLED` 중 하나를 넣습니다.

서버는 다른 이벤트 문자열도 받을 수 있지만, 공통된 이름을 사용해야 대시보드와 실행 디버깅이 더 유용해집니다.

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