Hugging Face Tiny Agents: 50줄 코드로 MCP 기반 에이전트 구축

Hugging Face는 Model Context Protocol (MCP)과 최신 LLM에서 제공되는 기본 툴 호출 지원을 활용하면, 약 50줄의 코드로 기능적인 AI 에이전트를 구현할 수 있음을 보여주었습니다. 핵심적인 통찰은 MCP 클라이언트를 구축하여 툴 탐색 및 실행을 처리하면, 에이전트는 본질적으로 LLM 추론과 툴 실행을 번갈아 수행하는 while 루프에 불과하다는 점입니다.

Model Context Protocol (MCP)을 툴링 표준으로 활용

MCP는 LLM과 통합될 수 있는 툴 세트를 노출하는 표준 API 역할을 합니다. MCP를 사용하면 개발자는 툴을 LLM 구현으로부터 분리할 수 있어, 추론 클라이언트가 다양한 MCP 서버에서 제공되는 툴을 모델의 추론 과정에 연결할 수 있습니다.

현재 MCP 서버는 로컬 프로세스로 동작합니다. Hugging Face의 구현은 @modelcontextprotocol/sdk/client TypeScript SDK를 사용하여 이러한 서버에 연결하고 listTools() 메서드를 통해 사용 가능한 툴을 가져옵니다. 가져온 툴은 이름, 설명, 매개변수로 구성된 JSONSchema 형태로 재구성되어, 기본 LLM 툴 호출 인터페이스와 호환됩니다.

InferenceClient를 사용한 MCP 클라이언트 구현

MCP 기반 에이전트를 구축하기 위해 Hugging Face는 @huggingface/inference JS 라이브러리의 InferenceClient를 활용합니다. 아키텍처는 세 가지 주요 구성 요소로 이루어집니다:

  1. Inference Client: LLM 제공자(예: Nebius)와 모델(예: Qwen2.5-72B-Instruct)와의 연결을 관리합니다.
  2. MCP Client Sessions: 연결된 각 MCP 서버에 대한 세션 맵을 유지하여 툴 실행을 처리합니다.
  3. Tool Registry: 모든 연결된 MCP 서버에서 수집된 사용 가능한 툴 목록을 제공합니다.

LLM이 툴 호출을 생성하면, 클라이언트는 올바른 MCP 세션을 식별하고 client.callTool() 메서드를 사용해 함수를 실행하고 결과를 가져옵니다. 이 결과는 툴 메시지 형태로 LLM에 다시 전달됩니다.

에이전트 아키텍처: "While Loop" 로직

에이전트는 시스템 프롬프트, LLM 추론 클라이언트, MCP 클라이언트, 그리고 기본 제어 흐름의 조합으로 정의됩니다. Hugging Face는 툴 설명을 프롬프트에 수동으로 삽입하는 대신, 추론 엔진의 기본 tools 파라미터에 의존합니다.

제어 흐름 및 루프 종료

에이전트의 메인 루프는 툴 호출과 결과를 LLM에 다시 전달하는 과정을 반복합니다. 루프는 다음 조건 중 하나가 충족될 때 종료됩니다:

  • 명시적 작업 완료: LLM이 특정 task_complete 툴을 호출합니다.
  • 사용자 상호작용: LLM이 ask_question 툴을 호출해 사용자에게 추가 정보를 요청합니다.
  • 턴 제한: 턴 수가 사전에 정의된 MAX_NUM_TURNS를 초과합니다.
  • 응답 패턴: LLM이 연속으로 두 개의 비툴 메시지를 응답하면 루프가 종료됩니다.

실용적인 적용 및 데모

사용자는 npx @huggingface/mcp-client 명령으로 전체 데모를 실행할 수 있습니다. 기본 설정은 두 개의 로컬 MCP 서버에 연결합니다:

  • File System Server: 에이전트가 로컬 데스크톱의 파일을 읽고 쓸 수 있는 권한을 부여합니다.
  • Playwright MCP Server: 웹 탐색 및 검색을 위한 샌드박스 Chromium 브라우저를 제공합니다.

예를 들어, 에이전트는 데스크톱에 하이쿠를 파일로 작성하거나, 추론 제공자를 대상으로 Brave Search를 수행하고 상위 세 개 결과를 여는 등 복잡한 다단계 프롬프트를 처리할 수 있습니다.

기술 사양 및 확장성

  • Default Model: Qwen/Qwen2.5-72B-Instruct
  • Default Provider: Nebius
  • Language: TypeScript/JavaScript (LLM 응답을 위해 async generator 사용).
  • Extensibility: 이 시스템은 Cerebras, Cohere, Fireworks 등 다양한 추론 제공자를 포함한 OpenAI 호환 클라이언트 SDK와 함께 작동하도록 설계되었습니다. 또한 llama.cpp 또는 LM Studio를 통한 로컬 LLM도 지원합니다.

Sources