목록으로
기술

OpenTelemetry를 사용하여 Koog 에이전트를 Langfuse로 추적

·3분 읽기
#Koog#JetBrains#AI Agent#Kotlin#Java#JVM

원문: Koog Documentation — Langfuse 이 글은 Koog 공식 문서의 Langfuse 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

OpenTelemetry를 사용하여 Koog 에이전트를 Langfuse로 추적

:material-github: Open on GitHub{ .md-button .md-button--기본 } :material-download: Download .ipynb{ .md-버튼 }

이 노트북은 OpenTelemetry를 사용하여 Koog 에이전트 추적을 Langfuse 인스턴스로 내보내는 방법을 보여줍니다. 환경 변수를 설정하고 간단한 에이전트를 실행한 다음 Langfuse에서 범위와 추적을 검사합니다.

무엇을 배울 것인가

  • Koog가 OpenTelemetry와 통합하여 추적을 내보내는 방법
  • 환경 변수를 통해 Langfuse 내보내기를 구성하는 방법
  • Langfuse에서 에이전트를 실행하고 추적을 보는 방법

전제 조건

  • Langfuse 프로젝트(호스트 URL, 공개 키, 비밀 키)
  • LLM 실행자용 OpenAI API 키
  • 셸에 설정된 환경 변수:
1export OPENAI_API_KEY=sk-...2export LANGFUSE_HOST=https://cloud.langfuse.com # or your self-hosted URL3export LANGFUSE_PUBLIC_KEY=pk_...4export LANGFUSE_SECRET_KEY=sk_...
1%useLatestDescriptors2//%use koog
1import ai.koog.agents.core.agent.AIAgent2import ai.koog.agents.features.opentelemetry.feature.OpenTelemetry3import ai.koog.prompt.executor.clients.openai.OpenAIModels4import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor56/**7 * Example of Koog agents tracing to [Langfuse](https://langfuse.com/)8 *9 * Agent traces are exported to:10 * - Langfuse OTLP endpoint instance using [OtlpHttpSpanExporter]11 *12 * To run this example:13 *  1. Set up a Langfuse project and credentials as described [here](https://langfuse.com/docs/get-started#create-new-project-in-langfuse)14 *  2. Get Langfuse credentials as described [here](https://langfuse.com/faq/all/where-are-langfuse-api-keys)15 *  3. Set `LANGFUSE_HOST`, `LANGFUSE_PUBLIC_KEY`, and `LANGFUSE_SECRET_KEY` environment variables16 *17 * @see <a href="https://langfuse.com/docs/opentelemetry/get-started#opentelemetry-endpoint">Langfuse OpenTelemetry Docs</a>18 */19val agent = AIAgent(20    executor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),21    llmModel = OpenAIModels.Chat.GPT4oMini,22    systemPrompt = "You are a code assistant. Provide concise code examples."23) {24    install(OpenTelemetry) {25        addLangfuseExporter()26    }27}

에이전트 및 Langfuse 내보내기 구성

다음 셀에서는 다음을 수행합니다.

  • OpenAI를 LLM 실행기로 사용하는 AIAgent 생성
  • OpenTelemetry 기능을 설치하고 Langfuse 내보내기 도구를 추가하세요.
  • Langfuse 구성을 위해 환경 변수에 의존

내부적으로 Koog는 에이전트 수명 주기, LLM 호출 및 도구 실행(있는 경우)에 대한 범위를 내보냅니다. Langfuse 내보내기는 OpenTelemetry 엔드포인트를 통해 해당 범위를 Langfuse 인스턴스로 전달합니다.

1import kotlinx.coroutines.runBlocking23println("Running agent with Langfuse tracing")45runBlocking {6    val result = agent.run("Tell me a joke about programming")7    "Result: $result\nSee traces on the Langfuse instance"8}9

에이전트 실행 및 추적 보기

간단한 프롬프트를 트리거하려면 다음 셀을 실행하세요. 그러면 Langfuse 프로젝트로 내보내지는 범위가 생성됩니다.

Langfuse에서 볼 수 있는 곳

  1. Langfuse 대시보드를 열고 프로젝트를 선택하세요.
  2. 추적/범위 보기로 이동
  3. 이 셀을 실행한 시점의 최근 항목을 찾습니다.
  4. 범위를 자세히 분석하여 다음을 확인하세요.
    • 에이전트 수명주기 이벤트
    • LLM 요청/응답 메타데이터
    • 오류(있는 경우)

문제 해결

  • 흔적이 안 보이나요?
    • LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY를 다시 확인하세요.
    • 네트워크가 Langfuse 엔드포인트에 대한 아웃바운드 HTTPS를 허용하는지 확인하세요.
    • Langfuse 프로젝트가 활성화되어 있고 키가 올바른 프로젝트에 속해 있는지 확인하세요.
  • 인증 오류
    • Langfuse에서 키를 재생성하고 환경 변수를 업데이트합니다.
  • OpenAI 문제
    • OPENAI_API_KEY가 설정되어 있고 유효한지 확인하세요.
#Koog#JetBrains#AI Agent#Kotlin#Java#JVM