README_SPACE.md

Deploy para Hugging Face Spaces

Guia para publicar seu agente como Space público gratuito.

Pré-requisitos

• Conta Hugging Face ativa (gratuita) em https://huggingface.co/join.
• Repositório aula07-agentes no GitHub com tag aula07-final.
• Saldo na conta OpenAI (mesma chave que você usou no Codespaces).

Passo 1 · Criar o Space

1. Acesse https://huggingface.co/new-space.
2. Owner: seu usuário.
3. Space name: educiacao ou designmind (sem espaços, minúsculo).
4. License: MIT (padrão para projetos didáticos).
5. Space SDK: selecione Gradio.
6. Gradio template: deixe como "Blank".
7. Hardware: CPU basic · Free (suficiente para o agente, que só chama API).
8. Visibility: Public (recomendado para portfólio) ou Private.
9. Clique em Create Space.

Passo 2 · Configurar Secrets e Variables

Antes de subir código, configure os segredos. No Space recém-criado:

1. Clique em Settings (canto superior direito do Space).
2. Role até Variables and secrets.
3. Em Secrets, clique em New secret:
   • Name: OPENAI_API_KEY
   • Value: sua chave (sk-...)
4. Em Variables, clique em New variable:
   • Name: PRODUCT
   • Value: educiacao ou designmind (mesmo que você usa no .env)
   • Name: OPENAI_MODEL
   • Value: gpt-4.1-mini

Importante: Secrets ficam ocultos para visitantes. Variables aparecem no log público mas servem para config não-sensível.

Passo 3 · Subir os arquivos

Você tem duas opções: upload manual via UI ou git push. Recomendo git.

Opção A · git push (recomendado)

# No seu Codespaces, terminal:

# 1. Clone o repositório do Space ao lado do projeto
cd /tmp
git clone https://huggingface.co/spaces/<SEU_USER>/<NOME_SPACE>
cd <NOME_SPACE>

# 2. Copie os 3 arquivos do deploy + tudo de src/ e config/
cp -r /workspaces/aula07-agentes/deploy/* .
cp -r /workspaces/aula07-agentes/src ./src
cp -r /workspaces/aula07-agentes/config ./config

# 3. Commit e push (HF aceita push direto)
git add .
git commit -m "deploy: agente aula07 no HF Space"
git push

O Space vai detectar app.py na raiz, instalar requirements.txt, e em ~2 minutos seu agente estará público.

Opção B · upload manual via UI

1. No Space, aba Files.
2. Clique em Add file → Upload files.
3. Suba os arquivos nesta estrutura na raiz do Space:

<seu-space>/
├── app.py                ← do deploy/app.py
├── requirements.txt      ← do deploy/requirements.txt
├── README.md             ← este arquivo (opcional)
├── src/                   ← pasta inteira
│   ├── __init__.py
│   ├── config.py
│   ├── llm.py
│   ├── agents/
│   │   ├── __init__.py
│   │   ├── single_agent.py
│   │   └── multi_agent.py
│   └── tools/
│       └── ... (todos os 6 arquivos)
└── config/
    └── products.yaml

4. Commit.

Passo 4 · Aguardar build e validar

1. Volte à aba App do Space.
2. Verá um log de build:

===== Application Startup at 2026-MM-DD HH:MM =====
Installing requirements...
Successfully installed gradio openai langgraph ...
Running on local URL:  http://0.0.0.0:7860

3. Quando aparecer a UI Gradio, clique em uma das perguntas-exemplo.
4. Confirme que retorna resposta coerente em PT-BR.

Limitações deste Space gratuito

Limitação	Valor	Impacto
Timeout por requisição	30 segundos	Multi-agente complexo pode estourar. Use single para chat.
Hardware	2 vCPU, 16GB RAM	Suficiente — agente só faz I/O ao OpenAI.
Persistência	Nenhuma	Histórico de conversa some entre sessões.
Auth	Nenhuma	Qualquer pessoa com a URL usa sua chave OpenAI.
Sleep	48h sem uso	Volta a rodar em ~30s na primeira requisição depois.
Rate limit OpenAI	sua quota	Se viralizar e sua conta zerar, Space para de responder.

O que NÃO usar este Space para

• Produção comercial real (sem auth, sem SLA, sem monitoramento).
• Dados sensíveis dos usuários (não há controle de acesso).
• Workloads pesados (timeout de 30s).
• Workflows multi-step de longa duração.

Como atualizar depois

Sempre que mudar o código local:

cd /tmp/<NOME_SPACE>
cp -r /workspaces/aula07-agentes/src/* ./src/
git add .
git commit -m "update: ..."
git push

O Space rebuilda automaticamente em ~1-2 minutos.

Próximos passos pós-Space

1. Compartilhar a URL com colegas, recrutadores, professores.
2. Adicionar ao seu CV: "Construí agente conversacional em LangGraph + OpenAI, publicado em HF Spaces. Acesso público: huggingface.co/spaces/...".
3. Iterar com feedback real: usuários diferentes encontram bugs diferentes. Anote, ajuste persona, faça push.
4. Migrar para produção real quando ficar grande: Render, Railway, Fly.io, AWS App Runner. Mas só quando precisar.

Custos esperados

Cenário	Custo/mês
Space gratuito + você testando	USD 0 (sem chamadas)
Space público com 10 visitantes/mês	USD 0.50 - 2.00
Space viralizado com 1000 chamadas/dia	USD 30 - 100

Se viralizar, desative o Space ou adicione rate limit antes de virar Space pago.