시작하기 전에
다음 항목이 필요합니다.config:read와policies:read권한이 모두 있는 워크스페이스 API key- 불변 버전으로 확정한 프롬프트 초안
- API key와 같은 환경에 있는 활성 배포
- 특정 Agent에만 배포했다면 tracer에 설정한
agentId
API key가 실행 설정을 조회할 워크스페이스와 배포 환경을 결정합니다. 엄격한
대상 검증을 사용할 때는 SDK의
environment도 같은 값으로 설정하세요.프롬프트 배포하기
Lynx 대시보드에서 다음 순서로 진행합니다.- 프롬프트 → 프롬프트 목록에서 프롬프트 추가를 선택합니다.
support-system처럼 계속 사용할 프롬프트 이름과 내용을 입력하고 초안을 저장합니다.- 버전 탭에서 버전 만들기를 선택합니다.
- 배포 탭을 엽니다.
- 불변 버전,
Staging또는Production, 전체 Agent 또는 특정 Agent를 선택합니다. - 배포를 선택합니다.
SDK 설정하기
agentId에는 Agent의 클라이언트 식별자를 사용합니다. 전체 Agent 배포만 사용한다면 agentId를 생략할 수 있습니다.
runtimeConfig.enabled: true를 설정하면 첫 run() 전에 프롬프트와 방화벽 정책을 불러옵니다. 파일 캐시는 선택 사항입니다. path 없이 캐시를 켜면 운영체제의 사용자 캐시 디렉터리에 마지막으로 검증한 설정을 저장합니다.
프롬프트 불러오기
getPrompt()에 프롬프트 이름을 전달합니다. run() 안에서 호출하면 실행이 끝날 때까지 선택한 버전을 고정하고, 관련 이벤트에 versionId를 연결합니다.
getPrompt()에는 프롬프트 이름 또는 UUID를 전달할 수 있습니다.
배포 대상 선택 방식
같은 프롬프트와 환경에 전체 Agent 배포와 특정 Agent 배포가 모두 있으면 특정 Agent 배포를 우선합니다.
실행 설정 요청은
new LynxTracer()에 전달한 agentId를 사용합니다. run()에만 다른 agentId를 전달해도 불러올 프롬프트 배포는 바뀌지 않습니다. 한 프로세스에서 프롬프트 배포가 서로 다른 Agent를 여러 개 실행한다면 Agent마다 tracer를 만드세요.
갱신과 캐시 동작
SDK는 다음 순서로 동작합니다.- 이전에 검증한 캐시가 있으면 먼저 읽습니다.
- 처음 사용할 때 현재 실행 설정을 불러옵니다.
- 기본적으로 60초마다 변경 사항을 확인합니다.
- 설정이 바뀌지 않았으면
ETag로 확인하고 본문을 다시 받지 않습니다. - 프롬프트 본문의 hash를 검증한 뒤 활성 설정을 교체합니다.
- 실행 중인
run()이 끝날 때까지 선택한 버전을 유지합니다.
refreshIntervalMs로 변경할 수 있으며 최소값은 5초입니다. 모델을 호출할 때마다 실행 설정 API를 직접 호출하지 마세요.
A/B 실험
활성 A/B 실험이 있으면 SDK는run()의 assignmentKey를 사용해 로컬에서 버전을 선택합니다.
assignmentKey를 생략하면 SDK는 sessionId를 사용합니다.
프롬프트를 불러오지 못했을 때
자동 시작 갱신은 Lynx 장애가 애플리케이션의 다른 작업을 막지 않도록 실패를 허용합니다. 하지만 유효한 캐시가 없거나 프롬프트가 배포되지 않았다면 명시적인getPrompt() 호출은 오류를 냅니다.
Lynx에 연결할 수 없어도 애플리케이션이 계속 동작해야 한다면 로컬 기본값을 준비하세요.
보안 메모
프롬프트에는 외부에 공개하면 안 되는 지침이 포함될 수 있습니다.prompt.content, API key, .lynxconf 내용을 애플리케이션 로그에 남기지 마세요. 로컬 캐시는 애플리케이션 설정과 같은 수준으로 보호하세요.