API 레퍼런스

이 문서는 주요 SDK API를 빠르게 확인하기 위한 레퍼런스입니다. 자세한 예시는 각 기능 문서를 참고하세요.

`LynxTracer`

LynxTracer는 이벤트를 기록하고, 현재 실행 context를 관리하며, 이벤트 묶음을 Lynx로 전송합니다.

import { LynxTracer } from "@lynxops/sdk";

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
});

`lynx`

lynx는 환경 변수에서 설정을 읽는 기본 tracer입니다.

import { lynx } from "@lynxops/sdk";

간단한 애플리케이션에서는 이 기본 인스턴스를 사용할 수 있습니다. 프로세스, tenant, test마다 설정을 명확히 분리해야 한다면 new LynxTracer()를 사용하세요.

실행 메서드

`run(agentName, callback)`

코드를 Lynx 실행 context 안에서 실행합니다.

await lynx.run("SupportAgent", async () => {
  lynx.userInput("비밀번호를 재설정하고 싶어요");
});

`run(options, callback)`

구조화된 실행 메타데이터를 함께 넘깁니다.

await lynx.run(
  {
    agentName: "SupportAgent",
    workspaceId: "workspace_123",
    agentId: "agent_123",
    sessionId: "session_123",
  },
  async () => {
    // Agent work
  },
);

관리형 프롬프트

`getPrompt(id)`

프롬프트 이름 또는 UUID로 현재 활성 불변 버전을 반환합니다. run() 안에서 호출하면 선택한 버전을 실행이 끝날 때까지 유지하고 관련 이벤트에 versionId를 연결합니다.

await lynx.run("SupportAgent", async () => {
  const prompt = await lynx.getPrompt("support-system");
  await callModel({ instructions: prompt.content });
});

유효한 실행 설정이 없거나 API key 환경과 Agent 범위에 프롬프트가 배포되지 않았다면 오류를 냅니다.

`initialize()`

관리형 프롬프트와 방화벽 정책을 바로 불러옵니다. 동시에 여러 번 호출해도 하나의 요청을 공유합니다. 일반적으로는 runtimeConfig.enabled: true를 사용하면 됩니다.

Semantic helper

Method	목적
`userInput(input, metadata?)`	사용자 입력을 기록합니다.
`decision(reasonOrDecision, options?)`	에이전트 판단을 기록합니다.
`context(labelOrData, dataOrMetadata?, metadata?)`	검색되었거나 구성된 컨텍스트를 기록합니다.
`memory(operation, data, metadata?)`	메모리 접근을 기록합니다.
`outcome(options)`	명시적인 기술 결과와 비즈니스 결과를 기록합니다. 생략하면 루트 `run()`이 기술 결과를 자동으로 기록합니다.
`setAttributes(attributes)`	현재 실행의 이후 이벤트에 공통 속성을 붙입니다.
`annotate(label, payload)`	커스텀 breadcrumb를 기록합니다.
`log(label, payload)`	커스텀 context 이벤트를 기록합니다.

LLM과 도구 helper

Method	목적
`instrumentLLM(client, options?)`	LLM 클라이언트 객체를 감쌉니다.
`guardLLM(client, options?)`	LLM 입력, 출력, 스트리밍 결과를 로컬 정책으로 검사하며 감쌉니다.
`instrumentTool(name, fn, metadata?)`	도구 함수를 감쌉니다.
`firewallTool(name, fn, options?)`	도구 함수를 로컬 정책 평가와 함께 감쌉니다.

LLM 옵션

옵션	설명
`modelLabel`	이벤트와 반복 이슈 묶기에 사용하는 고정된 모델 또는 공급자 이름입니다.
`reportFailures`	이슈 기록이 켜져 있을 때 LLM 오류를 보고합니다. 기본값은 `true`입니다.
`reportSlowResponses`	이슈 기록이 켜져 있을 때 연속 느린 LLM 호출을 보고합니다. 기본값은 `true`입니다.
`slowResponseThresholdMs`	이 wrapper에만 적용할 느린 LLM 호출 기준을 설정합니다.

도구 메타데이터

옵션	설명
`toolVersion`	도구 이벤트와 이슈 근거에 붙이는 버전입니다.
`sideEffect`	도구가 외부 상태를 바꿀 수 있는지 나타냅니다.
`riskLevel`	`LOW`, `MEDIUM`, `HIGH`, `CRITICAL` 중 하나입니다.
`externalTarget`	외부 시스템 또는 대상 이름입니다.
`timeoutMs`	비동기 호출 timeout입니다. wrapper는 거절되지만 이미 실행 중인 작업은 취소되지 않습니다.
`reportFailures`	이슈 기록이 켜져 있을 때 오류와 timeout을 보고합니다. 기본값은 `true`입니다.

전송 helper

Method	목적
`flush()`	큐에 쌓인 이벤트를 지금 전송합니다.
`shutdown(options?)`	타이머를 정리하고 종료 전 마지막 전송을 시도합니다.
`getStatus()`	이벤트 전송, 이슈 기록, 서킷 브레이커, 실행 설정 상태를 반환합니다.

`LynxPolicyError`

firewallTool()이 도구 호출을 차단하면 LynxPolicyError를 던집니다.

import { LynxPolicyError } from "@lynxops/sdk";

if (error instanceof LynxPolicyError) {
  console.log(error.action);
  console.log(error.policyId);
  console.log(error.reason);
}

설정 옵션

Option	설명
`clientId`	필수 클라이언트 또는 서비스 이름입니다.
`endpoint`	Lynx API endpoint입니다. 기본값은 `https://api.lynxops.co`입니다.
`workspaceId`	이벤트에 붙일 기본 workspace ID입니다.
`agentId`	이벤트에 붙일 기본 agent ID입니다.
`apiKey`	이벤트 전송에 사용하는 API key입니다.
`appVersion`	애플리케이션 버전 메타데이터입니다.
`deploymentId`	배포 ID 메타데이터입니다.
`environment`	실행 환경 메타데이터입니다.
`policyVersion`	기본 정책 버전 메타데이터입니다.
`sampleRate`	`0`부터 `1`까지의 기록 비율입니다.
`captureInput`	입력 필드를 기록할 수 있는지 정합니다.
`captureOutput`	출력 필드를 기록할 수 있는지 정합니다.
`captureMode`	`full`, `metadata-only`, `smart` 중 하나입니다.
`maxPayloadLength`	`smart` 모드에서 보관할 문자열 최대 길이입니다.
`runtimeConfig.enabled`	첫 `run()` 전에 관리형 프롬프트와 정책을 불러옵니다.
`runtimeConfig.refreshIntervalMs`	백그라운드 갱신 주기입니다. 기본값은 60초입니다.
`runtimeConfig.maxStaleAgeMs`	마지막으로 검증된 설정을 사용할 최대 기간입니다. 기본값은 24시간입니다.
`runtimeConfig.requireSignature`	서명되지 않은 실행 설정을 거절합니다.
`runtimeConfig.requireTargetMatch`	환경이 다르거나 Agent를 찾지 못한 설정을 거절합니다.
`runtimeConfig.cache.enabled`	마지막으로 검증한 설정을 저장합니다. 기본값은 `false`입니다.
`runtimeConfig.cache.path`	`.lynxconf` 파일의 정확한 경로입니다.
`issueReporting.enabled`	`true`이면 감지된 실패를 이슈 생성 검토 대상으로 보냅니다.
`issueReporting.reportRunFailures`	루트 Run 오류와 명시적으로 기록한 실패 결과를 보고합니다.
`issueReporting.reportLlmFailures`	연결한 LLM 호출에서 발생한 오류를 보고합니다.
`issueReporting.slowLlmThresholdMs`	느린 LLM 기준입니다. 기본값은 10초이며 `0`이면 끕니다.
`issueReporting.slowLlmConsecutiveOccurrences`	필요한 연속 느린 호출 횟수입니다. 기본값은 2회입니다.
`issueReporting.recoverySuccessThreshold`	정상화 기록을 보내기 전에 필요한 연속 정상 실행 횟수입니다.
`delivery.mode`	`BACKGROUND` 또는 `BLOCKING`입니다.
`delivery.timeoutMs`	한 번의 전송 요청 timeout입니다.
`delivery.flushOnRunEnd`	`run()` callback이 끝난 뒤 flush를 시도할지 정합니다.
`delivery.flushIntervalMs`	백그라운드 전송 주기입니다.
`delivery.batchSize`	이벤트 묶음 크기입니다.
`delivery.maxQueueSize`	메모리에 보관할 최대 이벤트 수입니다.
`delivery.overflowStrategy`	`DROP_OLDEST` 또는 `DROP_NEWEST`입니다.
`circuitBreaker.enabled`	전송용 서킷 브레이커를 사용할지 정합니다.
`circuitBreaker.failureThreshold`	서킷 브레이커를 열기 전 연속 실패 횟수입니다.
`circuitBreaker.cooldownMs`	다시 전송을 시도하기 전 대기 시간입니다.

시작하기

TypeScript SDK

OpenAPI

API 레퍼런스

`LynxTracer`

`lynx`

실행 메서드

`run(agentName, callback)`

`run(options, callback)`

관리형 프롬프트

`getPrompt(id)`

`initialize()`

Semantic helper

LLM과 도구 helper

LLM 옵션

도구 메타데이터

전송 helper

`LynxPolicyError`

설정 옵션

관련 문서

​LynxTracer

​lynx

​실행 메서드

​run(agentName, callback)

​run(options, callback)

​관리형 프롬프트

​getPrompt(id)

​initialize()

​Semantic helper

​LLM과 도구 helper

​LLM 옵션

​도구 메타데이터

​전송 helper

​LynxPolicyError

​설정 옵션

​관련 문서

`LynxTracer`

`lynx`

실행 메서드

`run(agentName, callback)`

`run(options, callback)`

관리형 프롬프트

`getPrompt(id)`

`initialize()`

Semantic helper

LLM과 도구 helper

LLM 옵션

도구 메타데이터

전송 helper

`LynxPolicyError`

설정 옵션

관련 문서