AGENTS.md 표준 준수 🥳 NEW: tiny-agents 는 이제 MCP 를 지원합니다.

Tiny Agents in JS 에서 영감을 받아 Python 🐍 으로 포팅하고, huggingface_hub 클라이언트 SDK 를 MCP Client 로 확장하여 MCP 서버에서 도구를 가져와 추론 (inference) 시 LLM 에 전달할 수 있도록 했습니다.

MCP(Model Context Protocol) 는 대형 언어 모델 (LLMs) 이 외부 도구 및 API 와 상호작용하는 방식을 표준화한 오픈 프로토콜입니다. 기본적으로 각 도구에 대해 커스텀 통합을 작성할 필요가 없어, LLM 에 새로운 기능을 추가하는 것이 훨씬 쉬워졌습니다.

이번 블로그 포스트에서는 Python 으로 MCP 서버에 연결된 작은 에이전트를 시작하여 강력한 도구 기능을 해제하는 방법을 보여드리겠습니다. 에이전트를 생성하고 구축하는 것이 얼마나 쉬운지 확인해 보겠습니다.

스포일러: 에이전트는 사실 MCP Client 위에 바로 구축된 while 루프와 같습니다!

이 섹션은 기존 Tiny Agents 를 사용하는 방법을 안내합니다. 에이전트를 실행하기 위한 설정 및 명령어를 다룹니다.

먼저 huggingface_hub 의 최신 버전을 mcp 추가 (extra) 와 함께 설치하여 모든 필수 구성 요소를 가져옵니다.

pip install "huggingface_hub[mcp]>=0.32.0"

이제 CLI 를 사용하여 에이전트를 실행해 보겠습니다!

가장 멋진 점은 Hugging Face Hub tiny-agents 데이터셋에서 에이전트를 직접 로드하거나, 자체 로컬 에이전트 구성 파일의 경로를 지정할 수 있다는 점입니다.

> tiny-agents run --help
Usage: tiny-agents run [OPTIONS] [PATH] COMMAND [ARGS]...
Run the Agent in the CLI
...

특정 에이전트 구성 파일의 경로를 제공하지 않으면, Tiny Agent 는 기본적으로 다음 두 MCP 서버에 연결됩니다:

• "canonical" 파일 시스템 서버 (데스크톱에 액세스 가능),
• Playwright MCP 서버 (샌드박스 Chromium 브라우저 사용법 알고 있음).

다음 예제는 Qwen/Qwen2.5-72B-Instruct 모델을 Nebius 추론 제공자를 통해 사용하는 웹 브라우징 에이전트를 보여줍니다. playwright MCP 서버가 내장되어 있어 웹 브라우저를 사용할 수 있습니다. 에이전트 구성은 tiny-agents/tiny-agents Hugging Face 데이터셋에서 경로를 지정하여 로드됩니다.

에이전트를 실행하면, 연결된 MCP 서버에서 발견한 도구를 나열하며 로딩되는 것을 볼 수 있습니다. 이제 프롬프트 (prompt) 에 준비되었습니다!

이 데모에서 사용된 프롬프트:
do a Web Search for HF inference providers on Brave Search and open the first result and then give me the list of the inference providers supported on Hugging Face

Gradio Spaces 를 MCP 서버로 사용할 수도 있습니다. 다음 예제는 Qwen/Qwen2.5-72B-Instruct 모델을 Nebius 추론 제공자를 통해 사용하며, FLUX.1 [schnell] 이미지 생성 HF Space 를 MCP 서버로 연결합니다. 에이전트는 Hugging Face Hub 의 tiny-agents/tiny-agents 데이터셋에서 구성 파일을 로드합니다.

이 데모에서 사용된 프롬프트:
Generate a 1024x1024 image of a tiny astronaut hatching from an egg on the surface of the moon.

기존 Tiny Agents 를 실행하는 방법을 확인했으니, 이제 다음 섹션은 그들이 어떻게 작동하는지 및 자체 에이전트를 구축하는 방법에 대해 더 깊이 다룹니다.

각 에이전트의 행동 (기본 모델, 추론 제공자, 연결할 MCP 서버, 초기 시스템 프롬프트) 은 agent.json 파일로 정의됩니다. 동일한 디렉토리에 더 상세한 시스템 프롬프트를 위해 커스텀 PROMPT.md 를 제공할 수도 있습니다. 예시는 다음과 같습니다:

agent.json

model 및 provider 필드는 에이전트가 사용하는 LLM 과 추론 제공자를 지정합니다.
servers

agent 이 연결할 MCP 서버를 정의합니다.
이 예제에서는 "stdio" MCP 서버가 구성됩니다. 이 유형의 서버는 로컬 프로세스로 실행됩니다. Agent 는 지정된 command 와 args 를 사용하여 이를 시작하고, stdin/stdout 을 통해 사용할 수 있는 도구를 발견하고 실행합니다.

{
"model": "Qwen/Qwen2.5-72B-Instruct",
"provider": "nebius",
...

PROMPT.md

You are an agent - please keep going until the user's query is completely resolved [...]

Hugging Face Inference Provider 에 대한 자세한 내용은 여기에서 찾을 수 있습니다.

Modern LLM 은 function calling (또는 tool use) 을 위해 구축되어 있으며, 이를 통해 사용자는 특정 사용 사례와 실제 작업에 맞춤화된 애플리케이션을 쉽게 구축할 수 있습니다.

함수는 그 스키마로 정의되며, 이는 LLM 이 무엇을 수행하고 입력 인자를 어떻게 기대하는지 알려줍니다. LLM 은 도구를 사용할 때를 결정하고, Agent 는 도구를 실행하고 결과를 다시 제공하는 것을 조정합니다.

tools = [
{
"type": "function",
...

InferenceClient

은 추론 제공자와 커뮤니티에서 확립된 표준인 OpenAI Chat Completions API 와 동일한 도구 호출 인터페이스를 구현합니다.

MCPClient 는 우리 도구 사용 기능의 핵심입니다. 이제 huggingface_hub 의 일부이며 LLM 과 통신하기 위해 AsyncInferenceClient 를 사용합니다.

완전한 MCPClient 코드는 실제 코드를 따라 하기 위해 여기에 있습니다 🤓

MCPClient 의 주요 책임:

• 하나 이상의 MCP 서버에 비동기 연결 관리.
• 이러한 서버에서 도구 발견.
• LLM 을 위한 도구 형식화.
• 올바른 MCP 서버를 통해 도구 호출 실행.

이것이 MCP 서버 ( add_mcp_server 메서드) 에 어떻게 연결되는지에 대한 예입니다:

# Lines 111-219 of `MCPClient.add_mcp_server`
# https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/mcp_client.py#L111:L219
class MCPClient:
...

그것은 로컬 도구 (예: 파일 시스템 액세스) 를 위한 stdio 서버와 원격 도구를 위한 http 서버를 지원합니다. 또한 이전 원격 도구 표준인 sse 와 호환됩니다.

MCPClient 의 process_single_turn_with_tools 메서드는 LLM 상호작용이 발생하는 곳입니다. 그것은 AsyncInferenceClient.chat.completions.create(..., stream=True) 를 통해 대화사와 사용할 수 있는 도구를 LLM 에게 전송합니다.

먼저,该方法 결정 현재 턴에 대해 LLM 이 인지해야 할 모든 도구 - 이는 MCP 서버의 도구와 에이전트 제어용 특수 "exit loop" 도구를 포함합니다; 그런 다음 LLM 에 대한 스트리밍 호출을 수행합니다:

# Lines 241-251 of `MCPClient.process_single_turn_with_tools`
# https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/mcp_client.py#L241:L251
# Prepare tools list based on options
...

LLM 에서 채크가 도착하면,该方法 이를 반복합니다. 각 채크는 즉시 yield 되며, 우리는 완전한 텍스트 응답과 도구 호출을 재구성합니다.

# Lines 258-290 of `MCPClient.process_single_turn_with_tools`
# https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/mcp_client.py#L258:L290
# Read from stream
...

스트림이 완료되면, LLM 이 도구 호출을 요청했다면 (현재 final_tool_calls 에서 완전히 재구성됨),该方法 각 하나를 처리합니다:

Lines 293-313 of MCPClient.process_single_turn_with_tools

https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/mcp_client.py#L293:L313

for tool_call in final_tool_calls.values():
...

먼저 호출된 도구가 루프를 종료하는지 (exit_loop_tool) 확인합니다. 그렇지 않으면 해당 도구와 관련된 올바른 MCP 세션을 찾아 session.call_tool() 을 호출합니다. 결과 (또는 오류 응답) 는 대화 기록에 추가되고 생성되어 에이전트가 도구의 출력을 인지할 수 있도록 합니다.

MCPClient 가 도구 상호작용을 모두 처리하므로, 우리의 Agent 클래스는 놀라게 단순해집니다. 그것은 MCPClient 를 상속받고 대화 관리 로직을 추가합니다.

에이전트 클래스는 매우 작으며 대화 루프에 집중하며, 코드는 여기에 찾을 수 있습니다.

에이전트가 생성될 때, 에이전트 설정 (모델, 제공자, 사용할 MCP 서버, 시스템 프롬프트) 을 받아 대화 기록을 시스템 프롬프트로 초기화합니다. load_tools() 메서드는 서버 구성 (agent.json 에 정의됨) 을 순회하고 각 하나를 위한 add_mcp_server 를 호출하여 에이전트의 도구 상자를 채웁니다.

# Lines 12-54 of `Agent`
# https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/agent.py#L12:L54
class Agent(MCPClient):
...

Agent.run() 메서드는 단일 사용자 입력을 처리하는 비동기 생성기입니다. 대화 턴을 관리하고 에이전트의 현재 작업이 완료되었는지 결정합니다.

# Lines 56-99 of `Agent.run()`
# https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_mcp/agent.py#L56:L99
async def run(self, user_input: str, *, abort_event: Optional[asyncio.Event] = None, ...) -> AsyncGenerator[
...

run() 루프 내부에서:

• 사용자 프롬프트를 대화에 먼저 추가합니다.
• 그 다음 MCPClient.process_single_turn_with_tools(...) 을 호출하여 LLM 의 응답을 얻고 한 단계의 추론을 위한 도구 실행을 처리합니다.
• 각 항목은 즉시 생성되어 호출자에게 실시간 스트리밍을 가능하게 합니다.
• 각 단계 후, 종료 조건을 확인합니다: 특수 "exit loop" 도구가 사용되었는지, 최대 턴 제한에 도달했는지, 또는 LLM 이 현재 요청에 대해 최종적인 텍스트 응답을 제공하는지 확인합니다.

MCP Client 와 Tiny Agent 를 탐색하고 확장하는 데 많은 흥미로운 방법이 있습니다 🔥 시작할 아이디어는 다음과 같습니다:

• 서로 다른 LLM 모델과 추론 제공자가 에이전트 성능에 미치는 영향을 벤치마크합니다: 도구 호출 성능은 각 제공자가 이를 다르게 최적화할 수 있기 때문에 달라질 수 있습니다. 지원되는 제공자 목록은 여기에 찾을 수 있습니다.
• llama.cpp 나 LM Studio 와 같은 로컬 LLM 추론 서버를 사용하여 작은 에이전트를 실행합니다.
• .. 그리고 물론 기여하기! Hugging Face Hub 의 tiny-agents/tiny-agents 데이터셋에서 고유한 작은 에이전트와 오픈 PR 을 공유하세요.

풀 리퀘스트와 기여는 환영합니다! 다시 말하지만, 여기 모든 것은 오픈 소스입니다! 💎❤️