# Agentes

O Hugging Face oferece ferramentas e protocolos que conectam agentes de IA diretamente ao Hub. Seja você conversando com o Claude, construindo com o Codex ou desenvolvendo agentes personalizados, você pode acessar modelos, conjuntos de dados, Spaces e ferramentas da comunidade. Esta página aborda a conexão dos seus [agentes de chat](#chat-with-hugging-face) e [agentes de codificação](#coding-agents) ao Hub.

| Página | Descrição |
| ---- | ----------- |
| [CLI](./agents-cli) | Dê ao seu agente o CLI `hf` com uma Skill integrada |
| [Servidor MCP](./agents-mcp) | Conecte qualquer cliente compatível com MCP ao Hub |
| [Habilidades](./agents-skills) | Orientações específicas para tarefas em fluxos de trabalho de IA/ML |
| [SDK](./agents-sdk) | Crie agentes programaticamente com Python ou JavaScript |
| [Agentes Locais](./agents-local) | Execute agentes totalmente locais com llama.cpp e Pi |
| [Rastreamentos de Agentes](./agent-traces) | Veja as sessões do Claude Code, Codex e Pi no Hub |

## Converse com o Hugging Face

Conecte seu assistente de IA diretamente ao Hugging Face Hub usando o Model Context Protocol (MCP). Uma vez conectado, você pode buscar modelos, explorar conjuntos de dados, gerar imagens e usar ferramentas da comunidade — tudo a partir da sua interface de chat.

### Assistentes suportados

O HF MCP Server funciona com qualquer cliente compatível com MCP:
- **ChatGPT** (via plugins)
- **Claude Desktop**
- **Clientes MCP personalizados**

### Configuração

#### 1. Abra as Configurações do MCP

![MCP Settings Example](https://huggingface.co/huggingface/documentation-images/resolve/main/agents-docs/mcp-settings.png)

Acesse [huggingface.co/settings/mcp](https://huggingface.co/settings/mcp) enquanto estiver conectado.

#### 2. Selecione seu cliente

Escolha seu cliente compatível com MCP da lista. A página exibe instruções específicas do cliente e um trecho de configuração pronto para copiar.

#### 3. Configure e reinicie

Copie o trecho de configuração para as configurações de MCP do seu cliente, salve e reinicie o cliente.

> [!TIP]
> A página de configurações gera a configuração exata que seu cliente espera. Use-a em vez de escrever a configuração manualmente.

### O Que Você Pode Fazer

Conectado, peça ao seu assistente para usar as ferramentas do Hugging Face entre as que você selecionou na sua configuração:

| Tarefa | Prompt de exemplo |
| ---- | -------------- |
| Pesquisar modelos | "Encontre quantizações do Qwen 3 no Hugging Face" |
| Explore conjuntos de dados | "Mostrar conjuntos de dados sobre séries temporais de clima" |
| Encontrar Spaces | "Encontre um Space que possa transcrever arquivos de áudio" |
| Gerar imagens | "Crie uma imagem de 1024x1024 de um gato no estilo Ghibli" |
| Pesquisar artigos | "Encontre artigos recentes sobre modelos de visão-linguagem" |

Seu assistente chama as ferramentas MCP expostas pelo servidor Hugging Face e retorna resultados com metadados, links e contexto.

### Adicionar Ferramentas da Comunidade

Estenda sua configuração com Spaces do Gradio compatíveis com MCP:

1. Navegue por [Spaces com suporte a MCP](https://huggingface.co/spaces?filter=mcp-server)
2. Adicione-os em suas [configurações do MCP](https://huggingface.co/settings/mcp)
3. Reinicie seu cliente para incorporar as novas ferramentas

Os aplicativos Gradio MCP expõem suas funções como ferramentas com argumentos e descrições, permitindo que seu assistente as chame diretamente.

### Saiba Mais

- [Guia do servidor MCP](./agents-mcp) - Configuração e configuração detalhadas
- [Configurações do HF MCP](https://huggingface.co/settings/mcp) - Configure seu cliente
- [Espaços compatíveis com MCP](https://huggingface.co/spaces?filter=mcp-server) - Ferramentas da comunidade

## Agentes de Código

Integre o Hugging Face ao seu fluxo de trabalho de codificação com o MCP Server e Skills. Acesse modelos, conjuntos de dados e ferramentas de ML diretamente do seu IDE ou agente de codificação. Por exemplo, abordamos esses agentes de codificação e outros com MCP e/ou Skills:

| Agente de Código | Método de Integração |
| ------------ | ------------------ |
| [Claude Code](https://code.claude.com/docs) | Servidor MCP + Skills |
| [OpenAI Codex](https://openai.com/codex/) | Servidor MCP + Skills |
| [Código Aberto](https://opencode.ai/) | Servidor MCP + Skills |
| [Cursor](https://www.cursor.com/) | Servidor MCP + Skills |
| [VS Code](https://code.visualstudio.com/) | Servidor MCP |
| [Gemini CLI](https://geminicli.com/) | Servidor MCP |
| [Zed](https://zed.dev/) | Servidor MCP |

### Configuração Rápida

#### Servidor MCP

O MCP Server dá ao seu agente de codificação acesso à busca no Hub, Spaces e ferramentas da comunidade.

**Cursor / VS Code / Zed:**

1. Acesse [huggingface.co/settings/mcp](https://huggingface.co/settings/mcp)
2. Selecione sua IDE da lista
3. Copie o trecho de configuração
4. Adicione-o às configurações de MCP do seu IDE
5. Reinicie a IDE

**Claude Code:**

```bash
claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"
```

#### Habilidades

Skills fornecem orientações específicas para tarefas em fluxos de trabalho de IA/ML. Elas funcionam em conjunto com MCP ou de forma independente.

```bash
# start claude 
claude

# install the skills marketplace plugin
/plugin marketplace add huggingface/skills
```

Em seguida, para instalar uma especificação de Skill:
```bash
/plugin install hf-cli@huggingface-skills
```

Consulte o [Guia de Habilidades](./agents-skills) para as habilidades disponíveis e o uso.

### O Que Você Pode Fazer

Uma vez configurado, seu agente de codificação pode:

| Capacidade | Exemplo |
| ---------- | ------- |
| Pesquisar no Hub | "Encontre um modelo de geração de código com menos de 7B parâmetros" |
| Gerar imagens | "Crie um diagrama de uma arquitetura de transformer" |
| Explore conjuntos de dados | "Quais conjuntos de dados estão disponíveis para análise de sentimento?" |
| Executar Spaces | Use o Whisper Space para transcrever este arquivo de áudio |
| Obter documentação | Como faço para ajustar finamente um modelo com transformers? |

### Configuração do Ambiente

#### Autenticação

Defina seu token do Hugging Face como uma variável de ambiente:

```bash
export HF_TOKEN="hf_..."
```

Ou autentique via [CLI](./agents-cli):

```bash
hf auth login
```

#### Adicionando ferramentas da comunidade

Estenda sua configuração com Spaces do Gradio compatíveis com MCP:

1. Navegue por [Spaces com suporte a MCP](https://huggingface.co/spaces?filter=mcp-server)
2. Adicione-os em suas [configurações do MCP](https://huggingface.co/settings/mcp)
3. Reinicie seu IDE

### Fluxo de Trabalho de Exemplo

```text
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!")
```

## Registre seu harness de agente

O Hugging Face mantém um registro público de harnesses de agentes, os agentes de codificação e ferramentas que interagem com o Hub (Claude Code, Codex, Cursor, entre outros). Quando o `huggingface_hub` detecta que está sendo executado dentro de um harness registrado, ele o relata por meio do user agent nas solicitações ao Hub. Registrar seu harness significa que essa atividade é atribuída à sua ferramenta pelo nome e dá ao seu projeto um rótulo de exibição amigável, links para sua documentação e repositório, e um lugar no conjunto de dados público de [uso de agentes](https://huggingface.co/datasets/huggingface/agent-usage) — ferramentas não registradas são contadas apenas em sua parcela agregada de `unknown`.

Para registrar um harness, abra um Pull Request adicionando uma entrada em [`agent-harnesses.ts`](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/agent-harnesses.ts) no pacote `@huggingface/tasks`:

- o id do harness (a chave de entrada) deve estar em minúsculas e separado por hífens (exemplo: `"claude-code"`).
- Defina `prettyLabel` com uma capitalização amigável para o usuário (exemplo: `Claude Code`).
- (opcional) defina `repoUrl` com um link para o código-fonte do harness (geralmente um repositório do GitHub).
- (opcional) defina `docsUrl` com um link para a documentação ou o site do harness.
- (opcional) defina `description` com uma explicação curta, em uma linha, do harness.
- define como o seu harness é detectado a partir do ambiente:
  - Se o seu harness definir uma das variáveis de ambiente padrão (`AI_AGENT` ou `AGENT`), seu valor será usado diretamente como identificador e nenhuma configuração extra será necessária.
  - Caso contrário, defina `envVars` para mapear nomes de variáveis de ambiente para padrões de valor. Use `"*"` para corresponder a qualquer valor não vazio, uma string exata para correspondência exata, ou `"<prefix>*"` para correspondência por prefixo.

E é isso! Assim que o PR for mesclado, o tráfego do `huggingface_hub` (incluindo o CLI `hf`) do seu harness de agente será atribuído a ele pelo nome e aparecerá no [conjunto de dados de uso de agentes](https://huggingface.co/datasets/huggingface/agent-usage) a partir da próxima atualização mensal.

## Próximas etapas

- [CLI](./agents-cli) - Interface de linha de comando para operações do Hub
- [Servidor MCP](./agents-mcp) - Conecte qualquer assistente de IA compatível com MCP ao Hub
- [Habilidades](./agents-skills) - Capacidades pré-criadas para agentes de codificação
- [SDK](./agents-sdk) - Bibliotecas em Python e JavaScript para criar agentes