# SDK를 활용한 빌드

Hugging Face의 에이전틱 SDK를 사용하여 MCP 기반 에이전트를 구축합니다. `huggingface_hub`(Python) 및 `@huggingface/tiny-agents`(JavaScript) 라이브러리는 LLM을 MCP 도구에 연결하는 데 필요한 모든 것을 제공합니다.

## 설치

```bash
pip install "huggingface_hub[mcp]"
```

```bash
npm install @huggingface/tiny-agents
# or
pnpm add @huggingface/tiny-agents
```

## 빠른 시작: 에이전트 실행

가장 빠르게 시작하는 방법은 `tiny-agents` CLI를 사용하는 것입니다:

```bash
tiny-agents run julien-c/flux-schnell-generator
```

```bash
npx @huggingface/tiny-agents run "julien-c/flux-schnell-generator"
```

이것은 [tiny-agents collection](https://huggingface.co/datasets/tiny-agents/tiny-agents)에서 에이전트를 로드하고, 해당 MCP 서버에 연결한 후, 대화형 채팅을 시작합니다.

## Agent 클래스 사용

`Agent` 클래스는 채팅 루프와 MCP 도구 실행을 관리합니다. LLM 실행에 [Inference Providers](https://huggingface.co/docs/inference-providers)를 사용합니다.

```python
from huggingface_hub import Agent
import asyncio

agent = Agent(
    model="Qwen/Qwen2.5-72B-Instruct",
    provider="novita",
    servers=[
        {
            "type": "sse",
            "url": "https://evalstate-flux1-schnell.hf.space/gradio_api/mcp/sse"
        }
    ]
)

async def main():
    async for chunk in agent.run("Generate an image of a sunset"):
        if hasattr(chunk, 'choices'):
            delta = chunk.choices[0].delta
            if delta.content:
                print(delta.content, end="")

asyncio.run(main())
```

모든 옵션은 [Agent reference](https://huggingface.co/docs/huggingface_hub/package_reference/mcp#huggingface_hub.Agent)를 참조하세요.

```typescript
import { Agent } from "@huggingface/tiny-agents";

const agent = new Agent({
    model: "Qwen/Qwen2.5-72B-Instruct",
    provider: "novita",
    apiKey: process.env.HF_TOKEN,
    servers: [
        {
            type: "sse",
            url: "https://evalstate-flux1-schnell.hf.space/gradio_api/mcp/sse"
        }
    ]
});

await agent.loadTools();

for await (const chunk of agent.run("Generate an image of a sunset")) {
    if ("choices" in chunk) {
        const delta = chunk.choices[0]?.delta;
        if (delta.content) {
            console.log(delta.content);
        }
    }
}
```

모든 옵션에 대한 내용은 [tiny-agents 문서](https://huggingface.co/docs/huggingface.js/tiny-agents/README)를 참조하세요.

## MCPClient 직접 사용

더 세밀한 제어가 필요하면 `MCPClient`를 사용하여 MCP 서버와 도구 호출을 직접 관리하세요.

```python
import asyncio
from huggingface_hub import MCPClient

async def main():
    async with MCPClient(
        model="Qwen/Qwen2.5-72B-Instruct",
        provider="novita",
    ) as client:
        # Connect to an MCP server
        await client.add_mcp_server(
            type="sse", 
            url="https://evalstate-flux1-schnell.hf.space/gradio_api/mcp/sse"
        )
        
        # Process a request with tools
        messages = [{"role": "user", "content": "Generate an image of a sunset"}]
        
        async for chunk in client.process_single_turn_with_tools(messages):
            if hasattr(chunk, 'choices'):
                delta = chunk.choices[0].delta
                if delta.content:
                    print(delta.content, end="")

asyncio.run(main())
```

모든 옵션은 [MCPClient 참조](https://huggingface.co/docs/huggingface_hub/package_reference/mcp#huggingface_hub.MCPClient)를 확인하세요.

JavaScript SDK는 MCP 상호작용에 `Agent` 클래스를 사용합니다. 더 낮은 수준의 제어가 필요하면 [@huggingface/mcp-client](https://huggingface.co/docs/huggingface.js/mcp-client/README) 패키지를 참고하세요.

## 에이전트 공유하기

Hub의 [tiny-agents collection](https://huggingface.co/datasets/tiny-agents/tiny-agents)에 에이전트를 기여하세요. 다음을 포함하세요:

- `agent.json` - 에이전트 구성 (필수)
- `PROMPT.md` 또는 `AGENTS.md` - 시스템 프롬프트 (선택 사항)
- `EXAMPLES.md` - 샘플 프롬프트 및 사용 사례 (선택 사항)

## 자세히 알아보기

- [huggingface_hub MCP Reference](https://huggingface.co/docs/huggingface_hub/package_reference/mcp) - Python API 참조
- [tiny-agents 문서](https://huggingface.co/docs/huggingface.js/tiny-agents/README) - JavaScript API 참조
- [추론 제공자](https://huggingface.co/docs/inference-providers) - 사용 가능한 LLM 제공자
- [tiny-agents 컬렉션](https://huggingface.co/datasets/tiny-agents/tiny-agents) - 커뮤니티 에이전트 둘러보기
- [MCP 서버 가이드](./agents-mcp) - Hugging Face MCP 서버에 연결