LLM과 도구 연결하기

SDK는 LLM 클라이언트와 도구 함수를 감싸서 각 호출을 세션 타임라인에 기록할 수 있습니다.

언제 사용하나요

다음 정보를 확인하고 싶을 때 사용합니다.

어떤 모델을 호출했는지
어떤 입력과 출력이 오갔는지
호출에 얼마나 걸렸는지
가능한 경우 토큰 사용량과 예상 비용
어떤 도구가 어떤 인자로 실행됐고 실패했는지

LLM 클라이언트 연결하기

instrumentLLM()은 원본 클라이언트와 같은 형태의 proxy를 반환합니다. SDK가 알고 있는 생성 메서드는 자동으로 기록됩니다.

import OpenAI from "openai";

const openai = lynx.instrumentLLM(
  new OpenAI({
    apiKey: process.env.OPENAI_API_KEY,
  }),
  {
    modelLabel: "openai",
  },
);

await lynx.run("SupportAgent", async () => {
  const response = await openai.chat.completions.create({
    model: "gpt-4.1-mini",
    messages: [{ role: "user", content: "이 티켓을 요약해줘" }],
  });

  lynx.decision("지원 분류를 위해 티켓을 요약했습니다");
  return response;
});

Lynx는 설정에 따라 입력과 출력, 모델 정보, 지연 시간, 가능한 경우 토큰 사용량, 실행 단계 ID, 오류를 기록합니다. 이슈 기록을 켜면 연결한 LLM에서 발생한 오류는 LLM_ERROR 후보가 됩니다. 설정한 지연 시간 기준을 연속으로 넘으면 기본 2회째에 LLM_SLOW_RESPONSE 후보를 보냅니다. 오류나 느린 응답이 예상되는 클라이언트에는 reportFailures: false, reportSlowResponses: false를 설정하거나 slowResponseThresholdMs로 해당 wrapper의 기준을 바꾸세요. streamText처럼 비동기 반복자를 반환하는 스트리밍 API는 기존 반복자 동작을 유지합니다. 스트림 소비가 끝났을 때 LLM 호출 종료를 기록하고, 소비 중 발생한 오류는 같은 실행 단계에 연결합니다. 생성한 스트림을 소비하지 않으면 시작 이벤트만 남습니다.

도구 연결하기

정책 검사 없이 도구 호출만 기록하려면 instrumentTool()을 사용합니다.

const searchOrders = lynx.instrumentTool(
  "orders.search",
  async ({ userId }: { userId: string }) => {
    return db.orders.findMany({ where: { userId } });
  },
  {
    toolVersion: "2026-06-01",
    sideEffect: false,
    riskLevel: "LOW",
    timeoutMs: 5000,
  },
);

await lynx.run("SupportAgent", async () => {
  const orders = await searchOrders({ userId: "usr_123" });
  lynx.context("orders", orders);
});

도구 실패를 이슈 생성 검토 대상으로 보내려면 SDK에서 이슈 기록을 켭니다.

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

같은 설정으로 다음 후보도 전송합니다.

루트 run() callback이 오류를 던지고 더 구체적인 도구·LLM·방화벽 탐지가 없으면 RUN_ERROR
outcome()이 기술 또는 비즈니스 결과를 실패로 기록하면 RUN_FAILED
연결한 LLM 호출이 실패하면 LLM_ERROR
설정한 횟수만큼 LLM 호출이 연속으로 느리면 LLM_SLOW_RESPONSE

도구가 오류를 던지면 TOOL_ERROR, 비동기 호출이 설정한 timeoutMs를 넘기면 TOOL_TIMEOUT 기록을 보냅니다. 서버는 오류 메시지 원문을 Fingerprint에 넣지 않고 안정적인 도구·오류 정보를 기준으로 반복 발생을 묶습니다. 이후 정상 호출이 설정한 횟수만큼 이어지면 SDK가 Recovery 기록을 보냅니다. 이 기록은 서버의 비동기 검토를 요청합니다. 최종 이슈를 즉시 만들거나 닫는 응답이 아니며, 애플리케이션의 오류 처리를 대신하지 않습니다. 오류가 정상적으로 예상되고 애플리케이션에서 처리되는 도구에는 reportFailures: false를 설정하세요. SDK wrapper의 timeout은 이미 실행 중인 작업을 취소하지 못합니다. 시간 초과 뒤 부작용까지 멈춰야 한다면 해당 도구의 AbortSignal 또는 취소 API를 함께 사용해야 합니다. 동기 작업은 timeoutMs로 중단할 수 없습니다. 도구가 실행되기 전에 정책 검사가 필요하다면 firewallTool()을 사용하세요.

커스텀 LLM 클라이언트

클라이언트가 SDK에서 기본으로 인식하는 메서드 이름을 쓰지 않는다면 custom rule을 넘길 수 있습니다.

const model = lynx.instrumentLLM(customClient, {
  modelLabel: "custom.llm",
  customRule: {
    isTargetMethod: (path) => path.join(".") === "responses.generate",
    extractInput: (args) => args[0],
    extractOutput: (result) => result.text,
    extractUsage: (result) => result.usage,
  },
});

Lynx에서 확인할 수 있는 것

LLM과 도구를 연결하면 Lynx에서 다음 정보를 볼 수 있습니다.

세션 타임라인의 LLM 호출
도구 호출과 도구 결과
실패했거나 느린 호출
재시도 패턴과 반복 호출 의심 지점
토큰 사용량, 지연 시간, 비용 신호
관련 세션과 trace 링크

보안 메모

LLM 입력, 모델 응답, 도구 인자, 도구 결과에는 민감정보가 들어갈 수 있습니다. 필요하면 metadata-only, captureInput: false, captureOutput: false를 사용하거나 애플리케이션에서 먼저 마스킹하세요.

다음 단계

LLM 입력과 출력을 정책으로 검사하기

기록뿐 아니라 모델 호출 전후에 방화벽 정책을 적용하려면 guardLLM()을 사용합니다.

const guardedOpenAI = lynx.guardLLM(openai, {
  modelLabel: "support-model",
  firewall: {
    input: {
      select: (request) => request.messages,
      riskLevel: "HIGH",
    },
    output: {
      select: (response) => response.output_text,
      riskLevel: "HIGH",
    },
  },
});

비동기 반복자 스트림은 각 chunk를 사용자 코드에 넘기기 전에 검사합니다. 인접한 chunk 사이에 나뉜 문자열도 제한된 크기의 누적 버퍼로 검사합니다. 정책이 차단하면 해당 chunk를 반환하기 전에 LynxPolicyError를 던집니다.

시작하기

TypeScript SDK

OpenAPI

LLM과 도구 연결하기

언제 사용하나요

LLM 클라이언트 연결하기

도구 연결하기

커스텀 LLM 클라이언트

Lynx에서 확인할 수 있는 것

보안 메모

다음 단계

LLM 입력과 출력을 정책으로 검사하기

​언제 사용하나요

​LLM 클라이언트 연결하기

​도구 연결하기

​커스텀 LLM 클라이언트

​Lynx에서 확인할 수 있는 것

​보안 메모

​다음 단계

​LLM 입력과 출력을 정책으로 검사하기

언제 사용하나요

LLM 클라이언트 연결하기

도구 연결하기

커스텀 LLM 클라이언트

Lynx에서 확인할 수 있는 것

보안 메모

다음 단계

LLM 입력과 출력을 정책으로 검사하기