🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

이 글은 Hugging Face의 huggingface_hub에 포함된 MCP 클라이언트를 활용해 Python에서 약 70줄짜리 Tiny Agent를 실행하고 구성하며, LLM이 MCP 서버의 도구를 발견·호출·반영하는 흐름을 설명한다.

📌 핵심 요약

• 글은 Tiny Agents in JS에서 영감을 받아 Python으로 포팅한 Tiny Agents를 소개하며, huggingface_hub 클라이언트 SDK가 MCP Client 역할을 하도록 확장되어 MCP 서버에서 도구를 가져오고 LLM 추론 중 전달할 수 있다고 설명한다.
• MCP는 LLM이 외부 도구와 API와 상호작용하는 방식을 표준화하는 공개 프로토콜이며, 도구마다 별도의 커스텀 통합을 작성해야 하는 부담을 줄여 새로운 기능을 LLM에 더 쉽게 연결하게 해준다.
• 데모 실행은 huggingface_hub[mcp]>=0.32.0 설치 후 tiny-agents CLI를 사용하는 방식으로 진행되며, 에이전트 설정은 Hugging Face Hub의 tiny-agents 데이터셋이나 로컬 agent.json에서 불러올 수 있다.
• agent.json은 사용할 모델, 추론 제공자, 연결할 MCP 서버를 정의하고, PROMPT.md는 더 자세한 시스템 프롬프트를 제공할 수 있으며, 예시에서는 Playwright MCP 서버와 Gradio Space 기반 이미지 생성 MCP 서버를 활용한다.
• 핵심 구현은 MCPClient가 MCP 서버 연결, 도구 발견, LLM용 도구 스키마 포맷팅, 도구 실행을 맡고, Agent 클래스는 그 위에서 대화 루프를 관리하는 매우 단순한 구조로 설명된다.

🧩 주요 포인트

1. 글은 Tiny Agents in JS에서 영감을 받아 Python으로 포팅한 Tiny Agents를 소개하며, huggingface_hub 클라이언트 SDK가 MCP Client 역할을 하도록 확장되어 MCP 서버에서 도구를 가져오고 LLM 추론 중 전달할 수 있다고 설명한다.
2. MCP는 LLM이 외부 도구와 API와 상호작용하는 방식을 표준화하는 공개 프로토콜이며, 도구마다 별도의 커스텀 통합을 작성해야 하는 부담을 줄여 새로운 기능을 LLM에 더 쉽게 연결하게 해준다.
3. 데모 실행은 huggingface_hub[mcp]>=0.32.0 설치 후 tiny-agents CLI를 사용하는 방식으로 진행되며, 에이전트 설정은 Hugging Face Hub의 tiny-agents 데이터셋이나 로컬 agent.json에서 불러올 수 있다.
4. agent.json은 사용할 모델, 추론 제공자, 연결할 MCP 서버를 정의하고, PROMPT.md는 더 자세한 시스템 프롬프트를 제공할 수 있으며, 예시에서는 Playwright MCP 서버와 Gradio Space 기반 이미지 생성 MCP 서버를 활용한다.
5. 핵심 구현은 MCPClient가 MCP 서버 연결, 도구 발견, LLM용 도구 스키마 포맷팅, 도구 실행을 맡고, Agent 클래스는 그 위에서 대화 루프를 관리하는 매우 단순한 구조로 설명된다.

🧠 상세 정리

1. Python Tiny Agents의 출발점과 MCP의 역할

글은 Hugging Face가 Tiny Agents in JS에서 아이디어를 얻어 이를 Python으로 옮겼다고 설명하며 시작한다. 핵심 확장은 huggingface_hub 클라이언트 SDK가 MCP Client처럼 동작하도록 만든 점이다. 이 덕분에 에이전트는 MCP 서버에서 제공하는 도구를 가져오고, 추론 중 LLM에 해당 도구들을 전달할 수 있다. MCP는 Model Context Protocol의 약자로, LLM이 외부 도구와 API를 사용하는 방식을 표준화하는 공개 프로토콜로 소개된다. 글의 기본 메시지는 에이전트가 거창한 구조라기보다 MCP Client 위에 얹힌 반복 루프에 가깝다는 점이다.

2. 데모 실행을 위한 설치와 CLI 사용 방식

실행 절차는 먼저 huggingface_hub의 최신 버전을 mcp extra와 함께 설치하는 것에서 시작한다. 글은 pip install "huggingface_hub[mcp]>=0.32.0" 명령을 제시하고, 이후 tiny-agents run CLI로 에이전트를 실행할 수 있다고 설명한다. CLI는 로컬 폴더의 agent.json 파일 경로나 Hugging Face의 tiny-agents/tiny-agents 데이터셋에 저장된 내장 에이전트 경로를 받을 수 있다. 특정 설정 경로를 제공하지 않으면 기본적으로 파일 시스템 서버와 Playwright MCP 서버에 연결된다. 이 기본 구성은 데스크톱 접근과 샌드박스 Chromium 브라우저 사용이라는 두 가지 도구 능력을 에이전트에 제공한다.

3. 웹 브라우징과 이미지 생성 예시

글은 Tiny Agent가 실제로 어떤 도구 능력을 얻는지 보여주기 위해 두 가지 데모를 소개한다. 첫 번째는 Qwen/Qwen2.5-72B-Instruct 모델을 Nebius 추론 제공자를 통해 사용하고, Playwright MCP 서버를 연결해 브라우저를 조작하는 웹 브라우징 에이전트다. 예시 프롬프트는 Brave Search에서 Hugging Face inference providers를 검색하고 첫 번째 결과를 연 뒤 지원되는 추론 제공자 목록을 알려 달라는 내용이다. 두 번째는 Gradio Spaces를 MCP 서버로 사용할 수 있음을 보여주는 사례로, FLUX.1 [schnell] 이미지 생성 Hugging Face Space에 연결한다. 이 데모에서는 달 표면에서 알을 깨고 나오는 작은 우주비행사 이미지를 1024x1024로 생성하는 프롬프트가 사용된다.

4. agent.json과 PROMPT.md로 정의되는 에이전트 구성

각 에이전트의 동작은 agent.json 파일에 의해 정의된다고 글은 설명한다. 이 파일에는 기본 모델, 추론 제공자, 연결할 MCP 서버 목록, 초기 시스템 프롬프트와 관련된 구성이 들어간다. 예시 agent.json에서는 model 필드에 Qwen/Qwen2.5-72B-Instruct를, provider 필드에 nebius를 지정하고, servers 배열에는 stdio 타입 MCP 서버를 설정한다. stdio 서버는 로컬 프로세스로 실행되며, 예시에서는 npx와 @playwright/mcp@latest 인자를 통해 Playwright MCP 서버를 시작한다. 같은 디렉터리에 PROMPT.md를 두면 더 자세한 시스템 프롬프트를 제공할 수 있으며, 글은 사용자의 요청이 완전히 해결될 때까지 계속 진행하라는 성격의 프롬프트 예시를 언급한다.

5. LLM 도구 사용과 함수 호출 인터페이스

글은 현대 LLM이 function calling 또는 tool use를 지원하도록 설계되어 있으며, 이를 통해 특정 사용 사례와 실제 작업에 맞춘 애플리케이션을 만들 수 있다고 설명한다. 도구는 이름, 설명, 입력 파라미터 스키마로 정의되며, 예시로 특정 위치의 현재 온도를 가져오는 get_weather 함수가 제시된다. LLM은 대화 맥락에서 도구가 필요한지 판단하고, Agent는 해당 도구 실행을 조율한 뒤 결과를 다시 LLM에 전달한다. 이 구조에서 도구 스키마는 LLM이 무엇을 호출할 수 있고 어떤 인자가 필요한지를 이해하게 하는 계약 역할을 한다. 또한 InferenceClient가 OpenAI Chat Completions API와 같은 도구 호출 인터페이스를 구현한다고 설명해, 기존 추론 제공자 및 커뮤니티 표준과의 호환성을 강조한다.

6. MCPClient의 핵심 책임과 서버 연결 과정

MCPClient는 글에서 도구 사용 기능의 중심으로 제시된다. 이 클라이언트는 huggingface_hub에 포함되어 있으며 AsyncInferenceClient를 사용해 LLM과 통신한다. 주요 책임은 하나 이상의 MCP 서버에 대한 비동기 연결 관리, 서버로부터 도구 발견, 도구를 LLM이 이해할 수 있는 형식으로 변환, 올바른 MCP 서버를 통한 도구 호출 실행이다. add_mcp_server 메서드 예시는 stdio, sse, http 타입에 따라 연결을 만들고, ClientSession을 초기화한 뒤 session.list_tools()로 도구 목록을 가져오는 과정을 보여준다. 발견된 각 도구는 이름을 기준으로 세션에 매핑되고, 동시에 available_tools 목록에 OpenAI식 function tool 형식으로 저장된다.

7. 스트리밍 추론과 도구 호출 처리 흐름

process_single_turn_with_tools 메서드는 LLM 상호작용이 실제로 일어나는 위치로 설명된다. 먼저 현재 턴에서 LLM이 알아야 할 도구 목록을 준비하는데, 여기에는 MCP 서버에서 발견한 도구와 필요할 경우 루프 종료용 특수 도구가 포함된다. 이후 AsyncInferenceClient.chat.completions.create를 stream=True로 호출해 대화 이력, 도구 목록, tool_choice="auto"를 LLM에 전달한다. 스트리밍 응답이 도착하면 각 chunk를 즉시 호출자에게 yield하면서 동시에 텍스트 응답과 도구 호출 조각들을 재구성한다. 이 방식은 사용자에게 진행 중인 출력을 보여주면서도, 최종적으로 어떤 도구 호출이 요청되었는지 완성된 형태로 처리할 수 있게 한다.

8. 도구 실행과 Tiny Agent 루프의 단순함

스트리밍이 끝난 뒤 LLM이 도구 호출을 요청했다면, MCPClient는 재구성된 final_tool_calls를 순회하며 각 호출을 처리한다. 먼저 호출된 함수가 exit_loop_tools에 포함된 특수 종료 도구인지 확인하고, 그렇다면 tool 메시지를 추가하고 현재 턴 처리를 종료한다. 일반 도구라면 함수 이름을 기준으로 self.sessions에서 해당 MCP 세션을 찾고, session.call_tool(function_name, function_args)를 호출해 실제 도구를 실행한다. 결과는 format_result를 거쳐 tool 메시지의 content에 담기며, 오류가 있으면 세션을 찾지 못했다는 오류 메시지가 포함될 수 있다. 글은 이런 도구 상호작용을 MCPClient가 대부분 처리하기 때문에 Agent 클래스는 MCPClient를 상속하고 대화 관리 루프를 더하는 작고 단순한 구조가 된다고 설명한다.

🧾 핵심 주장 / 시사점

• 이 글의 핵심은 에이전트를 복잡한 프레임워크가 아니라, 표준화된 도구 연결 계층인 MCPClient와 반복 대화 루프의 조합으로 단순화해 보여준다는 점이다.
• MCP 서버가 도구 발견과 실행을 담당하고 LLM에는 표준 function schema만 전달되므로, 파일 시스템·브라우저·Gradio Space 같은 서로 다른 기능을 같은 방식으로 연결할 수 있다.
• agent.json 중심의 구성 방식은 모델, 추론 제공자, MCP 서버를 코드 변경 없이 교체할 수 있게 해주며, Tiny Agent의 실험과 재사용을 쉽게 만드는 구조로 제시된다.

✅ 액션 아이템

• 핵심 구현 흐름대로 MCPClient를 서버 연결, 도구 발견, 스키마 포맷팅, 실행 단계로 분리하고 Agent는 대화 루프 유지에만 집중하도록 정리한다.
• tiny-agents CLI 데모 재현을 위해 huggingface_hub[mcp]>=0.32.0 설치를 전제로 기본 실행 경로를 점검하고 설정 오류 발생 지점을 추적한다.
• agent.json에 모델, 추론 제공자, MCP 서버 구성을 넣고 PROMPT.md로 상세 지시를 보강해 Playwright·Gradio Space MCP 호출 동작을 반영한다.

❓ 열린 질문

• Hugging Face Hub tiny-agents 데이터셋과 로컬 agent.json을 함께 사용할 때 충돌 규칙은 어떤 기준으로 정해야 하는가?
• 도구 목록이 증가할 때 MCPClient의 도구 발견과 스키마 포맷팅 단계에서 성능 저하를 판단할 실질적 지표는 무엇인가?
• 70줄 수준의 단순 구조에서 MCP 서버를 추가 확장할 때 Agent 루프를 건드리지 않기 위한 최소 분리 기준은 어디까지인가?