AI 에이전트 개발: smolagents의 작동 원리와 선택 기준

Python 기반 AI 에이전트가 상황에 따라 툴 호출과 계산을 조합해야 하고, 생성된 코드를 통제된 환경에서 실행할 수 있다면 smolagents가 잘 맞습니다. Hugging Face는 CodeAgent와 ToolCallingAgent라는 2가지 에이전트 클래스를 제공합니다. 모델이 다음 행동을 Python으로 표현할지, 구조화된 툴 호출로 표현할지가 선택의 기준입니다. 간결한 설계는 범위가 분명한 문제를 푸는 데 도움이 됩니다. 다만 워크플로의 상태를 안정적으로 유지하고 권한과 실행 격리를 관리하는 책임까지 사라지는 것은 아닙니다.

2026년 10월 31일 기준 Hugging Face, LangChain, OpenAI의 공식 문서를 확인했습니다. 이 글은 행동을 조합하는 방식, 워크플로 제어, 실행 경계를 기준으로 선택지를 비교합니다. 아래 권고는 성능 벤치마크가 아니라 아키텍처 관점의 판단입니다.

smolagents는 Python으로 AI 에이전트를 어떻게 움직일까요?

smolagents는 실행 가능한 코드로 에이전트의 행동을 표현할 수 있는 Hugging Face의 오픈 소스 Python 라이브러리입니다. 에이전트는 모델이 행동을 선택하고, 결과를 관찰한 뒤, 다음 행동을 결정하는 반복 구조입니다. CodeAgent는 이 행동을 Python으로, ToolCallingAgent는 구조화된 툴 호출로 표현합니다. 두 방식 모두 모델과 툴 모음을 입력받습니다. Hugging Face 에이전트 레퍼런스.

CodeAgent는 결과를 관찰하는 사이사이에 짧은 스크립트를 작성할 수 있는 연구원에 가깝습니다. 허용된 툴로 레코드를 조회하고, 반환된 데이터를 가공한 뒤, 답을 계산할 수 있습니다. 개발자가 기능과 제약을 정하면 모델이 그 기능들을 연결하는 로직의 일부를 작성합니다.

이는 검토할 코드 파일을 최종 결과물로 만들어 주는 어시스턴트와는 다릅니다. 여기서는 생성된 코드 자체가 에이전트의 다음 행동을 수행하는 수단입니다.

프레임워크를 비교할 때는 애플리케이션의 어느 부분에 유연성이 필요한지부터 살펴보면 좋습니다.

마지막 두 행은 LangGraph와 OpenAI Agents SDK가 문서에서 강조하는 부분을 정리한 것입니다. 해당 프레임워크만 할 수 있는 기능이라는 뜻은 아닙니다. 프레임워크가 어디에 구조를 제공해 주길 원하는지가 선택을 좌우합니다.

smolagents CodeAgent: 모델이 행동을 직접 조합하게 하려면

중간 처리 과정을 미리 정해 둔 호출 목록보다 Python으로 표현하는 편이 쉬울 때 CodeAgent의 가치가 드러납니다. Hugging Face 문서는 반복문, 조건문, 툴 조합을 강점으로 꼽으면서도 문법 오류, 예외, 예상하지 못한 동작에 대응해야 한다고 설명합니다. 기능 둘러보기.

재고 기록의 불일치를 조사하는 개발자를 예로 들어 보겠습니다. 읽기 전용 조회 툴이 조사할 레코드를 반환합니다. 에이전트는 이름 표기를 통일하고, 비슷한 항목끼리 묶고, 특정 필드의 합계를 구한 다음 어떤 레코드를 추가로 조회할지 판단해야 할 수 있습니다. Python은 이런 중간 작업을 자연스럽게 표현할 수 있는 언어입니다.

실행 결과는 모델이 다음 판단을 내릴 때 근거가 됩니다. 계산 실패도 에이전트가 대응할 수 있는 관찰 결과입니다. 그렇다고 스스로 문제를 해결하는 데 반드시 성공한다는 뜻은 아닙니다.

ToolCallingAgent: 정해진 작업 목록 안에서 행동하게 하려면

수행할 작업의 입력과 동작이 이미 명확하게 정해져 있다면 ToolCallingAgent부터 검토하는 편이 좋습니다. Python으로 행동 코드를 만드는 대신 툴 이름과 인수를 담은 구조화된 JSON 호출을 생성합니다. Hugging Face의 비교 설명.

주문을 조회하고 정책을 찾아 주는 고객 지원 어시스턴트라면 이 정도로 충분할 수 있습니다. 예측 가능한 데이터 변환은 일반 애플리케이션 코드에 맡기면 됩니다. 명확한 함수들로 표현할 수 있는 워크플로에 생성형 Python 코드를 도입하면 뚜렷한 이점 없이 실패 가능성만 하나 더 생깁니다.

구조화된 호출에도 권한 확인은 필요합니다. 형식이 올바른 주문 취소 요청이라도 해당 고객에게 허용되지 않는 작업일 수 있습니다. 스키마는 어떤 요청이 들어왔는지 알려 줄 뿐이며, 허용 여부는 애플리케이션이 판단해야 합니다.

툴과 모델은 별도로 선택합니다

툴의 범위는 좁게 유지하고, 모델은 독립적으로 선택합니다. 이 분리가 smolagents의 실용적인 매력입니다. 모든 업무 기능을 다시 정의하지 않고도 에이전트의 추론 방식을 바꿀 수 있습니다.

툴은 사용 규약이 명확한 함수입니다

smolagents의 툴은 함수에 이름, 설명, 입력 메타데이터, 출력 타입을 붙인 형태입니다. 타입 힌트와 유용한 docstring이 있는 단순한 함수라면 @tool 데코레이터가 적합합니다. 더 복잡한 툴은 Tool을 상속하고 forward에 실행 로직을 넣습니다. 툴 가이드.

재고 관리 어시스턴트에는 데이터베이스 전체 접근 권한보다 ‘허용된 카탈로그에서 레코드를 조회하는 기능’을 제공하는 편이 좋습니다. 테넌트 확인, 쿼리 제한, 응답량 제한은 구현 코드 안에서 처리합니다. 프롬프트를 아무리 설득력 있게 작성해도 이런 검사를 대신할 수는 없습니다.

툴은 모델 애플리케이션에 툴을 제공하는 표준 인터페이스인 Model Context Protocol, 즉 MCP를 통해 가져올 수도 있습니다. LangChain 툴과 Hugging Face Spaces용 어댑터도 사용할 수 있습니다. 하지만 툴을 재사용할 수 있다는 사실만으로 그 구현을 신뢰할 수 있는 것은 아닙니다. Hugging Face는 Hub 툴이 사용자 정의 코드를 실행하기 때문에 로드할 때 trust_remote_code=True를 명시하도록 요구합니다. 툴 연동 및 로드 문서.

이는 코드 검토를 거쳐 결정할 사안입니다. 에이전트에 툴을 제공하기 전에 구현과 의존성을 확인해야 합니다.

모델 백엔드가 샌드박스까지 결정하지는 않습니다

현재 모델 레퍼런스는 다음과 같은 연결 방식을 설명합니다.

• **InferenceClientModel**은 Hugging Face Inference Providers를 통해 연결합니다.
• **LiteLLMModel**은 LiteLLM의 제공업체 연동 계층을 사용합니다.
• **TransformersModel**은 Transformers 모델을 로컬에서 실행합니다.
• **OpenAIModel**은 OpenAI 호환 모델 서버에 연결합니다.

기능 둘러보기에서는 로컬 추론을 위한 Ollama도 다룹니다. 이는 백엔드 선택지에 관한 설명이며, 모든 모델이 코드 생성이나 툴 선택을 똑같이 잘한다는 보장은 아닙니다.

모델이 어디서 실행되는지와 모델이 생성한 Python 코드가 어디서 실행되는지는 별개의 질문입니다. 호스팅된 모델이 Docker 실행기를 사용할 수 있고, 로컬 모델도 안전하지 않은 행동을 생성할 수 있습니다. 추론을 자신의 컴퓨터로 옮기는 것만으로는 코드 실행 경계가 생기지 않습니다.

재현성을 확보하려면 데모 단계를 넘어설 때 사용할 모델을 명시적으로 설정해야 합니다. Hugging Face는 InferenceClientModel의 기본 모델이 바뀔 수 있다고 안내합니다. 모델 설정.

공식 문서 예제로 실행 흐름 살펴보기

툴을 추가하기 전에 문서의 간단한 계산 예제로 실행 경로부터 이해합니다. Hugging Face의 입문 예제는 툴을 비워 둔 상태에서 1부터 10까지의 합을 구하도록 요청합니다. 아래 코드는 이 과제를 그대로 사용하면서 샌드박스 가이드에 나온 Docker 컨텍스트 매니저 패턴을 더한 것입니다. 원본 예제, Docker 실행 설정.

1. 1

   실행 환경 준비하기

   설치 가이드는 Python 3.10 이상을 요구하며 가상 환경 사용을 권장합니다. 이 예제를 실행하려면 Docker도 설치되어 실행 중이어야 합니다. 설치 가이드.

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   Inference Providers 호출 권한이 있는 Hugging Face 토큰을 환경 변수 HF_TOKEN에 설정합니다. InferenceClientModel은 이 변수를 자동으로 읽을 수 있습니다. 스크립트 안에 토큰을 넣어서는 안 됩니다. 인증 동작.

2. 2

   문서의 계산 과제를 Docker에서 실행하기

   다음 코드를 sum_agent.py로 저장합니다.

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   그다음 실행합니다.

   python sum_agent.py

   블록을 빠져나오면 컨텍스트 매니저가 샌드박스 정리를 처리합니다. 이 코드는 공식 문서를 바탕으로 구성한 예제이며, 이 글을 위해 별도로 테스트한 실행 결과는 아닙니다.

3. 3

   결과와 실행 경계 확인하기

   수학적으로 기대하는 답은 55이며, 계산식은 10 × 11 ÷ 2입니다. 어떤 Python 코드를 생성할지는 모델이 결정하므로, 실행할 때마다 처리 기록이나 답변 문구가 정확히 같을 것이라고 가정해서는 안 됩니다.

   tools=[]는 사용자 정의 툴을 제공하지 않았다는 뜻입니다. CodeAgent의 Python 실행 능력까지 없어진 것은 아닙니다. 생성된 코드를 Docker 안에서 실행하게 만드는 것은 실행기 설정입니다.

이처럼 고정된 계산은 일반 Python 코드로 구현하는 것이 합리적입니다. 이 예제의 목적은 에이전트가 어떻게 작동하는지 보여 주는 데 있습니다. 계산을 영어로 설명할 수 있다는 이유만으로 에이전트를 도입할 필요는 없습니다. 어떤 중간 단계를 밟을지 선택하는 일 자체가 문제의 일부일 때 도입합니다.

코드를 실행하는 에이전트에는 샌드박스가 필요합니다

생성된 Python 코드는 신뢰할 수 없는 코드로 취급하고, 신뢰할 수 없는 입력을 받기 전에 명시적인 샌드박스를 마련해야 합니다. 기본 로컬 실행기는 기능이 제한된 인터프리터이며, 호스트 격리를 보장하지 않습니다. Hugging Face는 모델의 실수, 프롬프트 인젝션, 악의적인 요청을 위험 요인으로 지적합니다. 안전한 코드 실행.

로컬 인터프리터는 프로그램을 파싱한 구조인 Python 추상 구문 트리를 따라 연산을 하나씩 평가합니다. import와 하위 모듈을 제한하고 연산 횟수에도 상한을 둡니다. 이런 제어는 위험 노출을 줄여 주지만, 별도의 보안 가이드는 로컬 실행에도 여전히 위험이 있다고 경고합니다. 추가 패키지를 허용하면 생성된 프로그램이 접근할 수 있는 범위도 넓어집니다.

Hugging Face가 제공하는 샌드박스 선택지

현재 실행기 API는 로컬 실행기 외에 Blaxel, E2B, Modal, Docker를 지원합니다. 아래 설정명은 CodeAgent 레퍼런스와 실행기 레퍼런스를 따릅니다.

제공업체와 인증 정보는 이 설정들과 별도로 선택해야 합니다. 설치 문서에 선택적 의존성이 정리되어 있습니다. 추가 옵션을 설치하는 것만으로 배포 설정이 완료되지는 않습니다.

내부 실험에서는 Docker로 직접 점검할 수 있는 명확한 실행 경계를 마련할 수 있습니다. 신뢰할 수 없는 요청을 처리하는 서비스라면 필요한 격리 수준, 수명 주기 관리, 운영 제어를 기준으로 환경을 선택해야 합니다. 더 폭넓은 AI 에이전트 코드 샌드박스 비교에서 이러한 인프라 선택을 다룹니다.

코드 조각을 격리하는 것과 에이전트 전체를 격리하는 것은 다릅니다

에이전트를 추가하기 전에 실행 경계 안에 무엇을 둘지 결정해야 합니다. Hugging Face는 생성된 코드 조각만 샌드박스에서 실행하는 방식과 에이전트 시스템 전체를 그 안에서 실행하는 방식을 구분합니다. 보안 가이드는 코드 조각만 격리하는 방식이 managed agents, 즉 다른 에이전트가 보조 역할로 호출하는 에이전트를 지원하지 않는다고 경고합니다. 시스템 전체를 안으로 옮기려면 설정이 더 필요하며, 인증 정보를 제공해야 할 수도 있습니다. 샌드박스 구성 방식.

이 차이는 아키텍처에 영향을 줍니다. 나중에 전문 에이전트가 실행 환경 안에서 모델을 호출해야 한다면, 기존의 ‘코드를 보내고 결과를 받는’ 구성만으로는 부족할 수 있습니다. 배포 구성을 바꿀 때는 인증 정보의 위치와 툴 의존성도 다시 검토해야 합니다.

고객이 이용하는 서비스라면 에이전트를 시작하기 전에 접근 가능한 파일, 네트워크 목적지, 호출 가능한 작업을 정의합니다. 각 실행에는 해당 작업에 필요한 접근 권한만 부여합니다. 모델이 작업을 끝내지 못하는 경우까지 포함해, 타임아웃과 취소, 정리를 일반적인 실행 경로로 설계해야 합니다.

간결한 설계가 유리할 때와 그렇지 않을 때

애플리케이션에서 제어하기 가장 어려운 문제를 기준으로 프레임워크를 선택합니다. 초기화 코드가 짧으면 편리하지만, 그 주변에 직접 작성해야 하는 코드가 더 중요합니다.

smolagents와 LangGraph 비교: 동적인 행동 조합인가, 지속적인 흐름 제어인가

명시적인 업무 상태를 따라 프로세스를 저장하고, 일시 중지하고, 재개해야 한다면 LangGraph가 더 적합한 출발점입니다. LangGraph는 상태를 유지하는 워크플로를 위한 저수준 오케스트레이션 런타임으로, 상태 영속화와 사람의 개입을 지원합니다. 정해진 로직에 따라 실행되는 단계와 모델이 판단하는 단계를 섞을 수 있으며, LangChain을 필수로 사용해야 하는 것도 아닙니다. LangGraph 개요.

근거를 모은 뒤 관리자의 결정을 기다리고, 승인이 나면 다시 진행하는 구매 워크플로를 생각해 보겠습니다. 핵심은 프로세스 상태를 보존하고 허용된 상태 전이만 실행하도록 하는 것입니다. 이런 요구사항이 제품의 중심이라면 LangGraph부터 검토합니다.

그 대신 워크플로 설계는 직접 책임져야 합니다. 상태, 상태 전이, 영속화, 단계 재시도가 정확히 무엇을 의미하는지까지 정의해야 합니다. 구매 프로세스라면 그만한 작업이 타당합니다. 하지만 데이터를 읽고 답을 계산한 뒤 종료하는, 범위가 제한된 조사 어시스턴트에는 불필요한 구조일 수 있습니다.

주된 불확실성이 어떤 Python 연산으로 이 작업을 해결할 것인가라면 smolagents를 선택합니다. 반대로 이 프로세스가 상태를 안정적으로 유지하면서 어떻게 안전하게 진행할 것인가가 문제라면 LangGraph를 선택합니다. 이는 설계상의 권고이며, 각 프레임워크가 한 종류의 작업만 수행할 수 있다는 뜻은 아닙니다.

OpenAI Agents SDK: 작업 인계, 검사, 실행 추적이 중심일 때

전문 에이전트 간 협업과 운영상 검사가 애플리케이션의 중심이라면 OpenAI Agents SDK를 우선 검토하는 편이 좋습니다. 핸드오프는 대화의 담당을 다른 에이전트에게 넘깁니다. 에이전트를 툴로 사용하는 패턴에서는 관리자 역할의 에이전트가 응답에 대한 책임을 유지합니다. 오케스트레이션 문서.

고객 지원 어시스턴트에서는 범용 Python 문제 해결기보다 결제 담당 에이전트가 대화를 넘겨받는 구조가 더 명확할 수 있습니다. 내장된 추적 기능은 모델 호출, 툴 호출, 핸드오프, 가드레일을 기록합니다. 가드레일은 자동 검사를 수행하고, 사람의 검토가 필요한 경우에는 민감한 작업을 일시 중지해 결정을 기다립니다. 실행 추적, 가드레일과 검토.

여기서도 애플리케이션 정책은 직접 정해야 합니다. 어떤 작업에 승인이 필요한지 판단하고, 툴을 올바르게 구현하고, 중단된 작업을 처리하는 책임이 남습니다. 기본 기능이 이런 정책까지 작성해 주지는 않습니다. SDK 문서에도 샌드박스 에이전트 패턴이 설명되어 있으므로, 코드 실행은 smolagents만의 기능이 아닙니다.

Python으로 행동을 조합하는 기능이 필요하고 작은 루프로 충분하다면 smolagents를 선택합니다. 개발할 애플리케이션에 협업과 검토를 위한 기본 기능이 잘 맞는다면 Agents SDK를 선택합니다. ‘가볍다’는 이유만으로 우열을 정할 수는 없습니다.

더 많은 후보를 살펴보려면 AI 에이전트 프레임워크 비교를 참고합니다. 라이브러리를 바탕으로 직접 개발하기보다 설치해서 사용할 에이전트 애플리케이션을 찾는다면 오픈 소스 AI 에이전트 가이드부터 읽어 보면 좋습니다.

코드 에이전트에 대한 기대, 어디까지가 과장일까요?

프레임워크가 작다고 예측하기 어려운 작업까지 예측 가능해지지는 않습니다. Python의 풍부한 표현력은 유용하지만, 모델이 올바른 레코드를 선택했는지, 단위를 정확히 해석했는지, 업무 규칙을 지켰는지까지 보장하지는 못합니다.

행동을 조합할 수 있다는 특성을 모든 작업에서 더 빠르다는 주장으로 확대해서는 안 됩니다. 여러 연산을 묶으면 실행 흐름이 달라질 수는 있습니다. 그래도 결과를 결정하는 것은 모델, 작업, 툴의 동작, 실행 환경입니다. 성능을 기준으로 선택하려면 자신의 작업으로 직접 측정해야 합니다.

구체적인 제한도 알아둘 필요가 있습니다. 현재 에이전트 API에서 max_steps의 기본값은 20입니다. 이는 에이전트의 단계 수를 제한하며, 개별 Python 행동이 소비하는 자원을 제한하지는 않습니다. API에는 콜백, managed agents, 최종 답변 검사 기능도 있으므로, 간결한 설계를 제어 기능의 부재와 혼동해서는 안 됩니다. 에이전트 레퍼런스.

따라서 운영할 때는 실행 시간과 자원 한도를 별도로 설정해야 합니다. 단계 수 상한이 샌드박스 정책을 대신할 수 없고, 샌드박스도 결과의 정확성을 보장하지 않습니다.

다음 주에 시작해 볼 만한 작업

범위가 좁고 답을 독립적으로 검증할 수 있는 읽기 전용 작업부터 시작합니다. smolagents를 평가하는 Python 개발자라면 민감한 정보를 제거한 재고 내보내기 데이터와 범위가 제한된 조회 툴을 사용할 수 있습니다. 그런 다음 에이전트가 찾아낸 불일치 항목을 이미 알고 있는 사례와 비교합니다.

올바른 레코드를 골랐는지, 툴을 정확히 사용했는지, 예상 가능한 실패에서 복구했는지, 정해 둔 한도 안에서 종료했는지를 기록합니다. 비교 기준으로는 정해진 로직을 따르는 코드를 유지합니다. 작업이 항상 같은 경로를 따른다면 그 경로를 일반 코드로 작성합니다. Hugging Face의 가이드도 가능한 한 결정론적 함수를 사용하도록 권합니다. 좋은 에이전트 만들기.

Python 코드를 동적으로 조합하는 이점이 추가되는 복잡성을 정당화할 때 CodeAgent를 도입합니다. 정해진 툴 목록만으로 충분하다면 ToolCallingAgent를 사용합니다. 기존 워크플로가 이미 요구사항을 충족한다면 전환은 미뤄도 됩니다. 승인 대기 상태를 지속적으로 유지하거나 전문 에이전트에게 일을 넘기는 기능이 핵심이 될 때 프레임워크 선택을 다시 검토합니다.

설치와 호환성

smolagents는 pip로 어떻게 설치하나요?

핵심 라이브러리는 pip install smolagents로 설치합니다. 툴, 모델, 실행 환경에 필요한 추가 옵션을 함께 설치하면 됩니다. 앞서 살펴본 예제에서는 smolagents[docker]를 사용합니다.

smolagents의 HfApiModel 예제를 그대로 사용해도 되나요?

새 코드를 작성할 때는 현재 문서의 InferenceClientModel 인터페이스를 따릅니다. 오래된 예제의 import를 복사하기 전에 최신 모델 레퍼런스와 대조해야 합니다.

smolagents를 Docker에서 실행하려면 어떻게 설정하나요?

Docker를 설치해 실행한 뒤 Docker 추가 옵션을 설치하고 executor_type="docker"를 선택합니다. 워크로드에 맞게 실행 경계를 구성해야 합니다. 이 설정만으로 완전한 보안 정책이 갖춰지지는 않습니다.

뉴스레터로 실용적인 AI 개발 노트 받기.