콘텐츠로 이동

smolagents - 코드 우선 AI 에이전트 치트시트

smolagents - 코드 우선 AI 에이전트 치트시트

smolagents는 Hugging Face의 최소한의 코드 우선 에이전트 라이브러리다. 그 중심 아이디어: 모델이 JSON 블롭으로 도구 호출을 내보내는 대신, CodeAgent는 Python 코드를 직접 작성하고 실행한다. 동작을 코드로 표현하면 단일 단계가 여러 도구를 호출하고, 루프와 변수를 사용하며, 논리를 연결할 수 있다 — 이는 LLM 왕복 횟수 (대략 ~30% 감소)를 줄이고 복잡한 작업의 성능을 개선한다. 모델 불가지론적이며, 샌드박스 실행을 지원하고, 의도적으로 작고 해킹 가능하게 유지된다.

설치

방법	명령어
pip	`pip install smolagents`
도구 익스트라 포함	`pip install "smolagents[toolkit]"`
샌드박스 익스트라	`pip install "smolagents[e2b]"` (또는 `[docker]`)
모델 키 설정	`export HF_TOKEN=...` 또는 공급자 키
확인	`python -c "import smolagents; print('ok')"`

핵심 개념

용어	의미
CodeAgent	Python 동작을 작성하는 에이전트 (기본값)
ToolCallingAgent	고전 JSON 도구 호출을 내보내는 에이전트
Tool	에이전트가 사용할 수 있는 호출 가능 (스키마 포함)
Model	LLM 백엔드 (HF, OpenAI, LiteLLM, 로컬)
Sandbox	생성된 코드가 실행되는 곳 (로컬, E2B, Docker, Modal)

최소한의 CodeAgent

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

agent = CodeAgent(
    tools=[WebSearchTool()],
    model=InferenceClientModel(),   # HF Inference API
)

agent.run("How many seconds would it take a cheetah to cross the Golden Gate Bridge?")

객체	역할
`CodeAgent(tools=[...], model=...)`	에이전트
`agent.run("task")`	끝까지 작업 실행
`WebSearchTool()`	내장 도구
`InferenceClientModel()`	HF-호스팅 모델 백엔드

모델

백엔드	클래스
HF Inference API	`InferenceClientModel`
로컬 transformers	`TransformersModel`
LiteLLM를 통한 모든 공급자	`LiteLLMModel(model_id="openai/gpt-4o")`
OpenAI 호환 서버	`OpenAIServerModel(...)`
vLLM / 로컬 엔드포인트	LiteLLM / OpenAI 호환

도구 정의

from smolagents import tool

@tool
def get_weather(city: str) -> str:
    """Return the weather for a city.

    Args:
        city: The city to look up.
    """
    return f"Sunny in {city}"

agent = CodeAgent(tools=[get_weather], model=InferenceClientModel())

메커니즘	사용
`@tool` 데코레이터	타입된 함수를 도구로 변환
`Tool` 서브클래스	스키마/동작에 대한 더 많은 제어
도구 컬렉션	도구 세트 임포트 (예: Hub에서)
MCP 도구	모델 컨텍스트 프로토콜 서버 연결

샌드박스 실행 (중요)

CodeAgents는 생성된 Python을 실행하므로, 프로덕션에서는 이를 격리한다.

샌드박스	방법
로컬 (기본값)	프로세스 내 실행 — 신뢰할 수 있는 개발용 좋음
E2B	`executor_type="e2b"` (원격 샌드박스)
Docker	`executor_type="docker"`
Modal	원격 샌드박스 실행
허용된 임포트	생성된 코드가 임포트할 수 있는 모듈 제한

agent = CodeAgent(tools=[...], model=..., executor_type="e2b")

다중 에이전트 & 검색

패턴	방법
관리되는 에이전트	한 에이전트를 다른 에이전트의 도구로 제공
검색/RAG	근거 있는 답변을 위한 검색기 도구 추가
계획	어려운 작업을 위한 정기적인 계획 단계 활성화
핸드오프	관리자 에이전트 아래 전문가 구성

일반적인 워크플로우

# 브라우징하고 코드로 계산하는 연구 에이전트
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
agent = CodeAgent(tools=[WebSearchTool()], model=InferenceClientModel(),
                  executor_type="docker")
agent.run("Compare the population growth of Tokyo and Delhi since 2000.")

smolagents vs 다른 에이전트 프레임워크

측면	smolagents	LangGraph	Pydantic AI
동작 형식	Python 코드	그래프/상태 머신	타입된 도구 호출
크기/철학	최소, 해킹 가능	전체 상태 오케스트레이션	타입 안전, FastAPI-스타일
LLM 효율성	더 적은 호출 (코드)	의존함	표준
최고	단일 에이전트 코드 루프	내구 상태 에이전트	타입 안전 프로덕션 에이전트

자료