smolagents

smolagents는 도구를 호출하거나 코드를 실행하는 에이전트를 만드는 Hugging Face의 Python 라이브러리예요. init() 호출 한 번으로 smolagents를 추적할 수 있습니다. 에이전트 실행이 Observatory에 나타나서, 실행을 따라가며 그 아래의 모델·도구 호출을 살펴볼 수 있죠.

출처: 문서

본문

개요

smolagents는 도구를 호출하거나 코드를 실행하는 에이전트를 만드는 Hugging Face의 Python 라이브러리입니다. Confident AI는 init() 호출 한 번으로 smolagents를 추적할 수 있게 해 줘요 — 에이전트 실행이 Observatory에 나타나고, 실행을 따라가며 그 아래의 모델·도구 호출을 살펴볼 수 있죠.

smolagents 스팬은 실행의 구조 를 나타냅니다. confident-trace는 지원되는 프로바이더 통합도 활성화해서, 메시지·모델 상세·토큰 사용량을 담은 LLM 스팬을 포착합니다. 그 모델 호출을 담으려면 해당 프로바이더 통합을 켜 둔 채로 유지하세요.

Runtime	Requirements	Setup
Python	Python 3.10+, `smolagents` and your provider SDK	Call `init()` before running your agent
TypeScript	Not supported by this integration	—

자동 계측

EU 리전 사용자는 OTEL 엔드포인트를 EU 버전으로 설정하세요. 그렇지 않으면 트레이스가 우리 US 서버로 보내집니다.
export CONFIDENT_OTEL_ENDPOINT="https://eu.otel.confident-ai.com/v1/traces"

의존성 설치

confident-trace를 smolagents 및 에이전트가 쓰는 모델 프로바이더 SDK와 함께 설치하세요(아래 예는 OpenAI를 사용).

pip install confident-trace 'smolagents[openai]'

Confident AI 키 설정

Confident AI Project API key를 받아 환경 변수로 설정하거나, init()에 직접 전달하세요.

export CONFIDENT_API_KEY="<your-confident-api-key>"
export OPENAI_API_KEY="<your-openai-key>"

from confident_trace import init

init(api_key="<your-confident-api-key>")

smolagents 구성

시작 시, 에이전트를 실행하기 전에 init()을 한 번 호출하세요. 설치된 프레임워크는 자동으로 감지됩니다.

import os

from confident_trace import init, shutdown
from smolagents import OpenAIModel, ToolCallingAgent

init()

agent = ToolCallingAgent(
    model=OpenAIModel("gpt-4o-mini", api_key=os.environ["OPENAI_API_KEY"]),
    tools=[],
)

try:
    result = agent.run("Explain OpenTelemetry in one sentence.")
    print(result)
finally:
    shutdown()

한 번 초기화하고, 한 번 종료하세요. 장기 실행 서버에서는 시작 시 init()을, 정상 종료 시 활성 에이전트 실행이 끝난 뒤 shutdown()을 호출하세요 — 요청마다 하지 마세요. 한 번 초기화를 참고하세요.

smolagents 실행

스크립트를 실행해 에이전트를 돌려 보세요.

python main.py

완료 ✅. Confident AI 프로젝트에서 Observatory를 열어 트레이스와 자식 스팬을 확인하세요.

트레이스가 안 보이면, 거의 항상 프로그램이 트레이스를 보낼 기회가 생기기 전에 종료됐기 때문이에요. 종료 전에 반드시 shutdown()(장기 실행 프로세스에선 flush())을 호출하세요 — 트러블슈팅 페이지를 참고하세요.

무엇이 포착되나

에이전트 실행 — 작업, 최종 답변, 타이밍, 상태, 실행 계층
플래닝·단계 — ToolCallingAgent와 CodeAgent의 플래닝 작업과 실행 단계
로컬 도구 호출 — 도구 이름과 그 입출력
모델 호출 — 지원되는 프로바이더 통합의 메시지, 모델 상세, 토큰 사용량
커스텀 스팬 — 로컬 도구 안에서 만든 애플리케이션 스팬이 그 도구 아래에 중첩되어 유지

일반·스트리밍 실행을 모두 지원합니다. 스트림은 끝까지 소비하거나, 일찍 멈출 땐 닫아 주세요. 별도 샌드박스·원격 프로세스 안의 도구 실행은 로컬 도구 계측 범위 밖입니다.

포착되는 입력, 출력, 메시지는 콘텐츠 정책을 따릅니다. 지원되는 프로바이더 통합을 우회하는 모델 백엔드는 LLM 스팬을 위해 명시적 계측이 필요해요.

트레이스 스팬 속성 설정

호출이 시작되기 전에 아는 속성을 추가하려면 트레이스 컨텍스트를 사용하세요. 추가 스팬은 만들지 않아요. agent.run()이 시작한 트레이스가 태그, 메타데이터, 사용자 ID, 고객 ID를 상속받습니다.

from confident_trace import init, trace_context

init()

with trace_context(
    tags=["support"],
    metadata={"release": "2026-09"},
    user_id="user-42",
    customer_id="customer-7",
):
    result = agent.run("Explain OpenTelemetry in one sentence.")

각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 트레이스 속성과 갱신 동작은 트레이스 컨텍스트를 참고하세요.

다중 턴 계측

smolagents 엔트리포인트 호출 하나가 이미 하나의 대화 턴일 때는 turn()이 필요 없어요 — 통합이 그 턴의 트레이스를 자동으로 만들어 주거든요. 경계를 직접 정의하고 싶을 때, 예를 들어 두 번의 연속 smolagents 호출을 하나의 턴으로 묶고 싶을 때 turn()을 사용하세요. 이후 턴에서 같은 스레드 ID를 재사용해 하나의 대화로 묶으면 돼요.

from confident_trace import init, turn

init()

with turn("support-turn", thread_id="chat-42"):
    context = agent.run("Find the relevant account details.")
    answer = agent.run(f"Summarize these details: {context}")

스레드 입출력, 턴 ID, 사용자 ID는 스레드를 참고하세요.

smolagents 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. smolagents의 식별자는 Python에서 "smolagents"이고, 이를 빼면 이 통합이 비활성화돼요. 빈 목록은 모든 자동 계측을 비활성화합니다.

from confident_trace import init
init(instrumentations=())
# Use ("smolagents",) to opt in; omit "smolagents" to disable it.

이렇게 하면 Confident AI의 자동 계측이 꺼지고, 초기화 이후의 호출은 이 통합으로 계측되지 않아요.

다음 단계

에이전트를 추적했으니, 더 깊이 들어가 볼까요.

Online Evals

트레이스와 스팬이 Confident AI로 수집되는 실시간으로 평가를 돌려 에이전트 품질을 모니터링하세요.

Threads

같은 대화의 에이전트 실행을 스레드로 묶고, 전체 대화를 하나의 단위로 평가하세요.

더 알아보기

Hugging Face — smolagents 공식 문서
Online Evals — 실시간 트레이스·스팬 평가
Threads — 대화를 스레드로 묶어 평가