Hugging Face 파이썬용 Tiny Agents

Hugging Face는 "Tiny Agents" 개념을 Python으로 포팅하여 huggingface_hub 클라이언트 SDK를 Model Context Protocol (MCP) 클라이언트로 확장했습니다. 이를 통해 개발자는 대형 언어 모델(LLM)이 외부 도구를 발견하고 실행하는 방식을 표준화함으로써 약 70줄의 코드만으로 기능적인 AI 에이전트를 만들 수 있습니다.

모델 컨텍스트 프로토콜 (MCP)

MCP는 LLM과 외부 도구 또는 API 간의 상호작용을 표준화하도록 설계된 오픈 프로토콜입니다. 범용 인터페이스를 제공함으로써, MCP는 개발자가 개별 도구마다 맞춤형 통합을 작성할 필요성을 없애고 LLM에 새로운 기능을 추가하는 과정을 단순화합니다.

Tiny Agents 실행 및 구성

Tiny Agents는 mcp 추가 옵션을 포함한 huggingface_hub 라이브러리를 설치한 후 CLI를 통해 배포할 수 있습니다:

pip install "huggingface_hub[mcp]>=0.32.0"

에이전트 구성

에이전트의 동작은 agent.json 파일과 상세 시스템 지시를 위한 선택적 PROMPT.md 파일에 의해 정의됩니다. agent.json 파일은 다음을 지정합니다:

  • Model: 사용할 LLM (예: Qwen/Qwen2.5-72B-Instruct).
  • Provider: 추론 제공자 (예: Nebius).
  • Servers: 에이전트가 연결해야 할 MCP 서버들의 배열. 이는 stdio 서버(명령 및 인수를 통해 로컬 프로세스로 실행) 또는 http 서버(원격 도구)일 수 있습니다.

배포 예시

에이전트는 로컬 구성에서 로드하거나 Hugging Face Hub의 tiny-agents/tiny-agents 데이터셋에서 직접 로드할 수 있습니다. 예시는 다음과 같습니다:

  • Web-Browsing Agent: Playwright MCP 서버를 사용하여 샌드박스된 Chromium 브라우저를 작동합니다.
  • Image Generation Agent: MCP 서버 역할을 하는 FLUX.1 [schnell] 이미지 생성 HF Space에 연결합니다.

기술 아키텍처: MCPClient

huggingface_hub 내의 MCPClient는 도구 사용 기능을 관리하는 핵심 구성 요소입니다. 주요 역할은 MCP 서버와의 비동기 연결 관리, 사용 가능한 도구 탐색, 해당 도구를 LLM에 맞게 포맷팅, 그리고 도구 호출을 실행하는 것입니다.

연결 및 도구 탐색

add_mcp_server 메서드는 서버 유형(stdio, sse, http)에 따라 연결을 설정합니다. 연결이 완료되면 클라이언트는 ClientSession을 초기화하고 list_tools()를 호출하여 서버의 사용 가능한 도구를 가져옵니다. 이러한 도구는 OpenAI Chat Completions API와 호환되는 스키마로 포맷팅되며, 이는 InferenceClient가 사용하는 표준 인터페이스입니다.

도구 실행 루프

process_single_turn_with_tools 메서드는 LLM 상호작용 사이클을 처리합니다:

  1. Preparation: MCP 서버와 모든 "exit loop" 제어 도구를 집계합니다.
  2. Streaming: AsyncInferenceClient.chat.completions.create를 사용하여 LLM에 스트리밍 호출을 수행합니다.
  3. Processing: 청크가 도착하면 클라이언트는 텍스트 응답과 요청된 도구 호출을 재구성합니다.
  4. Execution: 도구가 호출되면 클라이언트는 해당 MCP 세션을 식별하고 session.call_tool()을 통해 도구를 실행합니다. 결과는 포맷팅되어 대화 기록에 추가됩니다.

에이전트 구현

Agent 클래스는 MCPClient를 상속하고 대화 관리 레이어를 추가합니다. 이는 상태를 유지하고 작업이 완료되었는지를 판단하는 간단한 루프로 설계되었습니다.

초기화

생성 시, Agent는 시스템 프롬프트로 대화 기록을 초기화하고 load_tools()를 호출하여 모든 구성된 MCP 서버에 연결하여 에이전트의 사용 가능한 도구 상자를 채웁니다.

핵심 실행 루프

Agent.run() 메서드는 while True 루프를 통해 사용자 입력을 처리하는 비동기 생성기입니다. 각 반복에서 LLM 및 도구 상호작용을 process_single_turn_with_tools에 위임하고 실시간으로 결과를 반환합니다.

루프는 다음 세 가지 조건 중 하나가 충족될 때 종료됩니다:

  • "exit loop" 도구가 명시적으로 호출된 경우.
  • 최대 턴 수(MAX_NUM_TURNS)에 도달한 경우.
  • LLM이 추가 도구 호출이 필요 없는 최종 텍스트 응답을 제공한 경우.

Sources