OpenTelemetry로 런 실행 살펴보기(Inspecting runs with OpenTelemetry)

[!TIP] 에이전트 구축이 처음이라면 에이전트 소개와 smolagents Guided tour를 먼저 읽어보세요.

왜 에이전트 런을 로깅할까요?

에이전트 런은 디버깅하기 어려워요. 런이 제대로 진행됐는지 검증하기도 힘들고, 살펴보는 것도 힘들어요.

에이전트 워크플로우는 설계상 예측이 불가능하거든요 (예측 가능했다면 그냥 일반 코드를 썼을 거예요). 게다가 멀티스텝 에이전트는 콘솔을 로그로 금방 채우고, 대부분의 오류도 다음 스텝에서 더 나은 코드나 도구 호출을 쓰며 LLM이 스스로 고쳐버리는 'LLM이 멍청했던' 류의 오류예요.

그래서 프로덕션에서는 나중에 살펴보고 모니터링하기 위해 계측(instrumentation)으로 에이전트 런을 기록하는 게 꼭 필요해요!

우리는 에이전트 런을 계측하기 위해 OpenTelemetry 표준을 채택했어요. 즉 계측 코드를 조금 실행하고 나서 에이전트를 평소처럼 돌리면, 모든 것이 플랫폼에 로그로 기록된다는 뜻이에요. 아래에서 서로 다른 OpenTelemetry 백엔드로 이걸 하는 예시를 보여드릴게요.

플랫폼에서는 이렇게 보여요.

Arize AI Phoenix로 텔레메트리 설정하기

먼저 필요한 패키지를 설치해요. 여기서는 로그를 수집하고 살펴보기 좋은 솔루션인 Phoenix by Arize AI를 설치하는데, 이 수집·검사 부분에 쓸 수 있는 다른 OpenTelemetry 호환 플랫폼도 있어요.

pip install 'smolagents[telemetry,toolkit]'

그다음 컬렉터를 백그라운드로 실행해요.

python -m phoenix.server.main serve

마지막으로 SmolagentsInstrumentor를 설정해 에이전트를 추적하고 Phoenix 기본 엔드포인트로 트레이스를 보내요.

from phoenix.otel import register
from openinference.instrumentation.smolagents import SmolagentsInstrumentor

register()
SmolagentsInstrumentor().instrument()

이제 에이전트를 실행하면 돼요!

from smolagents import (
    CodeAgent,
    ToolCallingAgent,
    WebSearchTool,
    VisitWebpageTool,
    InferenceClientModel,
)

model = InferenceClientModel()

search_agent = ToolCallingAgent(
    tools=[WebSearchTool(), VisitWebpageTool()],
    model=model,
    name="search_agent",
    description="This is an agent that can do web search.",
)

manager_agent = CodeAgent(
    tools=[],
    model=model,
    managed_agents=[search_agent],
)
manager_agent.run(
    "If the US keeps its 2024 growth rate, how many years will it take for the GDP to double?"
)

됐어요! 이제 http://0.0.0.0:6006/projects/로 가서 런을 살펴보면 돼요.

CodeAgent가 관리하는 ToolCallingAgent(참고로 관리 에이전트는 CodeAgent일 수도 있어요)를 불러 미국 2024 성장률에 대한 웹 검색을 시켰고, 관리 에이전트가 보고서를 돌려주면 매니저 에이전트가 그걸 바탕으로 경제가 두 배가 되는 시간을 계산했어요. 멋지죠?

MLflow로 텔레메트리 설정하기

MLflow는 Smolagents용 원라인 자동 로깅을 제공해요. 런, 스팬, 입력/출력, 토큰 사용량을 MLflow UI에서 추적하죠.

MLflow를 설치하고 자동 로깅을 켠 뒤, 도구 몇 개와 함께 에이전트를 실행해요.

%pip install mlflow smolagents

import mlflow
from smolagents import CodeAgent, ToolCallingAgent, WebSearchTool, VisitWebpageTool, InferenceClientModel

mlflow.smolagents.autolog()  # start tracing everything below

model = InferenceClientModel()
browser = ToolCallingAgent(
    tools=[WebSearchTool(), VisitWebpageTool()],
    model=model,
    name="search_agent",
    description="Web search helper",
)
manager = CodeAgent(model=model, managed_agents=[browser])
manager.run("Find the latest US GDP growth rate and estimate when it would double.")

UI를 시작해 트레이스를 살펴본 뒤, 브라우저에서 Traces 뷰를 열어요.

mlflow server --port 5000

🪢 Langfuse로 텔레메트리 설정하기

이 부분에서는 SmolagentsInstrumentor를 사용해 Hugging Face smolagents를 Langfuse로 모니터링하고 디버깅하는 방법을 보여드릴게요.

Langfuse가 뭔가요? Langfuse는 LLM 엔지니어링을 위한 오픈소스 플랫폼이에요. AI 에이전트에 대한 추적과 모니터링을 제공해서, 개발자가 제품을 디버깅·분석·최적화하는 데 도움을 줘요. Langfuse는 네이티브 통합, OpenTelemetry, SDK를 통해 다양한 도구·프레임워크와 연동돼요.

1단계: 의존성 설치

%pip install langfuse 'smolagents[telemetry]' openinference-instrumentation-smolagents

2단계: 환경 변수 설정

Langfuse API 키를 설정하고, 트레이스를 Langfuse로 보낼 OpenTelemetry 엔드포인트를 구성해요. Langfuse API 키는 Langfuse Cloud에 가입하거나 Langfuse 셀프호스팅으로 얻을 수 있어요.

또한 Hugging Face 토큰(HF_TOKEN)을 환경 변수로 추가해요.

import os
# Get keys for your project from the project settings page: https://cloud.langfuse.com
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." 
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." 
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 EU region
# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region
 
# your Hugging Face token
os.environ["HF_TOKEN"] = "hf_..."

환경 변수가 설정되면 Langfuse 클라이언트를 초기화할 수 있어요. get_client()는 환경 변수에 담긴 자격 증명으로 Langfuse 클라이언트를 초기화해요.

from langfuse import get_client
 
langfuse = get_client()
 
# Verify connection
if langfuse.auth_check():
    print("Langfuse client is authenticated and ready!")
else:
    print("Authentication failed. Please check your credentials and host.")

3단계: `SmolagentsInstrumentor` 초기화

애플리케이션 코드보다 먼저 SmolagentsInstrumentor를 초기화해요.

from openinference.instrumentation.smolagents import SmolagentsInstrumentor
 
SmolagentsInstrumentor().instrument()

4단계: smolagent 실행

from smolagents import (
    CodeAgent,
    ToolCallingAgent,
    WebSearchTool,
    VisitWebpageTool,
    InferenceClientModel,
)

model = InferenceClientModel(
    model_id="deepseek-ai/DeepSeek-R1-Distill-Qwen-32B"
)

search_agent = ToolCallingAgent(
    tools=[WebSearchTool(), VisitWebpageTool()],
    model=model,
    name="search_agent",
    description="This is an agent that can do web search.",
)

manager_agent = CodeAgent(
    tools=[],
    model=model,
    managed_agents=[search_agent],
)
manager_agent.run(
    "How can Langfuse be used to monitor and improve the reasoning and decision-making of smolagents when they execute multi-step tasks, like dynamically adjusting a recipe based on user feedback or available ingredients?"
)

5단계: Langfuse에서 트레이스 보기

에이전트를 실행한 뒤, Langfuse에서 smolagents 애플리케이션이 생성한 트레이스를 볼 수 있어요. LLM 상호작용의 상세한 스텝이 보일 거예요. AI 에이전트를 디버깅하고 최적화하는 데 도움이 되죠.

Langfuse의 공개 예제 트레이스

출처: 공식문서

OpenTelemetry로 런 실행 살펴보기(Inspecting runs with OpenTelemetry)