에이전트
에이전트 (Agents)
Hugging Face는 AI 에이전트를 Hub에 직접 연결하는 도구와 프로토콜을 제공해요. Claude와 대화하든, Codex로 빌드하든, 커스텀 에이전트를 개발하든 모델·데이터셋·Spaces·커뮤니티 도구에 접근할 수 있습니다.
출처: 문서
본문
Hugging Face는 AI 에이전트를 Hub에 직접 연결하는 도구와 프로토콜을 제공합니다. Claude와 대화하든, Codex로 빌드하든, 커스텀 에이전트를 개발하든, 모델·데이터셋·Spaces·커뮤니티 도구에 접근할 수 있어요. 이 페이지는 채팅 에이전트와 코딩 에이전트를 Hub에 연결하는 방법을 다룹니다.
| Page | Description |
|---|---|
| CLI | 내장 Skill과 함께 에이전트에 hf CLI 부여 |
| MCP Server | 모든 MCP 호환 클라이언트를 Hub에 연결 |
| Skills | AI/ML 워크플로를 위한 태스크별 지침 |
| SDK | Python 또는 JavaScript로 프로그래밍 방식 에이전트 구축 |
| Local Agents | llama.cpp와 Pi로 완전 로컬 에이전트 실행 |
| Agent Traces | Hub에서 Claude Code, Codex, Pi 세션 보기 |
Hugging Face와 채팅하기 (Chat with Hugging Face)
Model Context Protocol (MCP)을 사용해 AI 어시스턴트를 Hugging Face Hub에 직접 연결하세요. 연결되면 모델 검색, 데이터셋 탐색, 이미지 생성, 커뮤니티 도구 사용을 채팅 인터페이스 안에서 모두 할 수 있습니다.
지원되는 어시스턴트 (Supported Assistants)
HF MCP Server는 모든 MCP 호환 클라이언트에서 동작합니다:
- ChatGPT (플러그인 통해)
- Claude Desktop
- 커스텀 MCP 클라이언트
설정 (Setup)
1. MCP 설정 열기 (Open MCP Settings)
로그인한 상태에서 huggingface.co/settings/mcp에 방문하세요.
2. 클라이언트 선택 (Select Your Client)
목록에서 MCP 호환 클라이언트를 선택하세요. 페이지가 클라이언트별 지침과 복사 가능한 설정 스니펫을 보여줍니다.
3. 구성하고 재시작하기 (Configure and Restart)
구성 스니펫을 클라이언트의 MCP 설정에 복사하고 저장한 뒤 클라이언트를 재시작하세요.
[!TIP] 설정 페이지는 클라이언트가 기대하는 정확한 구성을 생성합니다. 손으로 작성하는 대신 이를 사용하세요.
할 수 있는 것 (What You Can Do)
연결되면 구성에서 선택한 Hugging Face 도구를 어시스턴트에게 사용하라고 요청할 수 있어요:
| Task | Example Prompt |
|---|---|
| 모델 검색 | "Find Qwen 3 quantizations on Hugging Face" |
| 데이터셋 탐색 | "Show datasets about weather time-series" |
| Spaces 찾기 | "Find a Space that can transcribe audio files" |
| 이미지 생성 | "Create a 1024x1024 image of a cat in Ghibli style" |
| 논문 검색 | "Find recent papers on vision-language models" |
어시스턴트는 Hugging Face 서버가 노출한 MCP 도구를 호출하고 메타데이터·링크·컨텍스트와 함께 결과를 반환합니다.
커뮤니티 도구 추가하기 (Add Community Tools)
MCP 호환 Gradio Spaces로 설정을 확장하세요:
- MCP 지원 Spaces 둘러보기
- MCP 설정에 추가
- 새 도구를 받으려면 클라이언트 재시작
Gradio MCP 앱은 함수를 인자와 설명이 있는 도구로 노출하므로 어시스턴트가 직접 호출할 수 있어요.
더 알아보기 (Learn More)
- MCP Server Guide — 상세 설정과 구성
- HF MCP Settings — 클라이언트 구성
- MCP-compatible Spaces — 커뮤니티 도구
코딩 에이전트 (Coding Agents)
MCP Server와 Skills로 Hugging Face를 코딩 워크플로에 통합하세요. IDE나 코딩 에이전트에서 직접 모델·데이터셋·ML 도구에 접근할 수 있어요. 예를 들어 다음 코딩 에이전트를 MCP 및/또는 Skills로 다룹니다:
| Coding Agent | Integration Method |
|---|---|
| Claude Code | MCP Server + Skills |
| OpenAI Codex | MCP Server + Skills |
| Open Code | MCP Server + Skills |
| Cursor | MCP Server + Skills |
| VS Code | MCP Server |
| Gemini CLI | MCP Server |
| Zed | MCP Server |
빠른 설정 (Quick Setup)
MCP Server
MCP Server는 코딩 에이전트에 Hub 검색, Spaces, 커뮤니티 도구 접근을 제공합니다.
Cursor / VS Code / Zed:
- huggingface.co/settings/mcp 방문
- 목록에서 IDE 선택
- 구성 스니펫 복사
- IDE의 MCP 설정에 추가
- IDE 재시작
Claude Code:
claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"
Skills
Skills는 AI/ML 워크플로를 위한 태스크별 지침을 제공해요. MCP와 함께 또는 단독으로 동작합니다.
# start claude
claude
# install the skills marketplace plugin
/plugin marketplace add huggingface/skills
그런 다음 Skill 명세를 설치하려면:
/plugin install hf-cli@huggingface/skills
사용 가능한 skills와 사용법은 Skills Guide를 참고하세요.
할 수 있는 것 (What You Can Do)
구성하면 코딩 에이전트가 다음을 할 수 있어요:
| Capability | Example |
|---|---|
| Hub 검색 | "Find a code generation model under 7B parameters" |
| 이미지 생성 | "Create a diagram of a transformer architecture" |
| 데이터셋 탐색 | "What datasets are available for sentiment analysis?" |
| Spaces 실행 | "Use the Whisper Space to transcribe this audio file" |
| 문서 얻기 | "How do I fine-tune a model with transformers?" |
환경 구성 (Environment Configuration)
인증 (Authentication)
Hugging Face 토큰을 환경 변수로 설정하세요:
export HF_TOKEN="hf_..."
또는 CLI로 인증:
hf auth login
커뮤니티 도구 추가 (Adding Community Tools)
MCP 호환 Gradio Spaces로 설정을 확장하세요:
- MCP 지원 Spaces 둘러보기
- MCP 설정에 추가
- IDE 재시작
예시 워크플로 (Example Workflow)
You: Find a text classification model that works well on short texts
Agent: [Searches Hugging Face Hub]
Found several options:
- distilbert-base-uncased-finetuned-sst-2-english (sentiment)
- facebook/bart-large-mnli (zero-shot)
...
You: Show me how to use the first one
Agent: [Fetches documentation]
Here's how to use it with transformers:
from transformers import pipeline
classifier = pipeline("sentiment-analysis",
model="distilbert-base-uncased-finetuned-sst-2-english")
result = classifier("I love this product!")
에이전트 하네스 등록하기 (Register your agent harness)
Hugging Face는 Hub와 상호작용하는 코딩 에이전트와 도구(Claude Code, Codex, Cursor 등)인 에이전트 하네스의 공개 레지스트리를 유지합니다. huggingface_hub이 등록된 하네스 안에서 실행 중임을 감지하면 Hub 요청의 user agent로 이를 보고해요. 하네스를 등록하면 이 활동이 도구 이름으로 귀속되고, 표시 라벨, 문서·리포지토리 링크, 공개 agent usage dataset의 자리가 제공됩니다 — 미등록 도구는 집계 unknown 비중에만 포함됩니다.
하네스를 등록하려면 @huggingface/tasks 패키지의 agent-harnesses.ts에 항목을 추가하는 Pull Request를 여세요:
- harness id(항목 키)는 소문자와 하이픈으로 구분해야 합니다(예:
"claude-code"). prettyLabel은 사용자 친화적인 표기로 설정(예:Claude Code).- (선택)
repoUrl에 하네스 소스 코드 링크(보통 GitHub 리포지토리) 설정. - (선택)
docsUrl에 하네스 문서나 웹사이트 링크 설정. - (선택)
description에 하네스에 대한 짧은 한 줄 설명 설정. - 하네스가 환경에서 어떻게 감지되는지 정의:
- 하네스가 표준 환경 변수(
AI_AGENT또는AGENT) 중 하나를 설정하면 그 값이 식별자로 직접 사용되며 추가 설정이 필요 없습니다. - 그렇지 않으면
envVars로 환경 변수 이름을 값 패턴에 매핑하세요."*"는 비어 있지 않은 모든 값, 정확한 문자열은 정확히 일치,"<prefix>*"는 접두사 매칭입니다.
- 하네스가 표준 환경 변수(
그게 전부입니다! PR이 머지되면 에이전트 하네스의 huggingface_hub 트래픽(hf CLI 포함)이 이름으로 귀속되고, 다음 월간 업데이트부터 agent usage dataset에 나타납니다.
다음 단계 (Next Steps)
- CLI — Hub 작업용 커맨드라인 인터페이스
- MCP Server — 모든 MCP 호환 AI 어시스턴트를 Hub에 연결
- Skills — 코딩 에이전트용 사전 구축 기능
- SDK — 에이전트 구축용 Python·JavaScript 라이브러리
더 알아보기 (Learn more)
huggingface.co/settings/mcp에서 클라이언트별 구성 스니펫을 생성해 채팅·코딩 에이전트를 Hub에 연결할 수 있어요. 코드/채팅 에이전트 + Gradio MCP Spaces 조합으로 모델 검색부터 이미지 생성까지 가능하고, 하네스를 등록하면 사용량이 에이전트 이름으로 집계됩니다. 각 상세 가이드(CLI·MCP·Skills·SDK)를 이어서 읽어 보세요.