README.md

---
title: Agente Gerador de Questões de Matemática
emoji: 📐
colorFrom: blue
colorTo: gray
sdk: gradio
sdk_version: 5.23.1
app_file: app.py
pinned: false
tags:
- smolagents
- agent
- smolagent
- tool
- agent-course
short_description: Questões alinhadas à BNCC
---
## 🤖 Agente Gerador de Questões de Matemática

Este é um agente de Inteligência Artificial projetado para auxiliar educadores na criação de questões de matemática personalizadas e de alta qualidade, alinhadas à **Base Nacional Comum Curricular (BNCC)** 

O agente utiliza um modelo de linguagem avançado para interpretar sua solicitação, usar ferramentas para gerar gráficos e tabelas, e então formatar questões completas, incluindo enunciado, alternativas, resposta correta e resolução passo a passo.

---
### **Como Usar**

Para interagir com o agente, digite sua solicitação na caixa de texto na parte inferior, seguindo os seguintes campos, separados por vírgula:

1.  **`habilidade_bncc:`** (Obrigatório) O código da habilidade da BNCC que a questão deve abordar, junto com seu significado. 
2.  **`nivel_dificuldade:`** (Obrigatório) O nível da questão. Opções: `fácil`, `médio`, `difícil`.
3.  **`quantidade:`** (Obrigatório) O número de questões que você deseja gerar (até 10). Ex: `1`, `3`, etc.
4.  **`tipo_questao:`** (Obrigatório) O formato da questão. Opções: `multipla_escolha` ou `dissertativa`.
5.  **`observacao:`** (Opcional) Qualquer instrução adicional ou contexto específico que você queira fornecer para a geração da questão.
   - Exemplo:
     
       habilidade_bncc:(EM13MAT102) Analisar tabelas, gráficos e amostras de pesquisas estatísticas apresentadas em relatórios divulgados por diferentes meios de comunicação, identificando, quando for o caso, inadequações que possam induzir a erros de interpretação, como escalas e amostras não apropriadas., nivel_dificuldade: difícil, quantidade: 3, tipo_questao: multipla_escolha

---
### **Resultado**

Após enviar sua tarefa, o agente mostrará seus "pensamentos" e as ferramentas que está usando. Ao final, ele apresentará a(s) questão(ões) formatada(s), prontas para uso.

---
### ⚙️ Configurações Técnicas e Funcionamento

Esta seção detalha os componentes e parâmetros utilizados para construir e operar este agente de IA.

#### O Modelo

O núcleo do agente é um Grande Modelo de Linguagem (LLM) de código aberto.

* **Modelo Utilizado:** `Qwen/Qwen2.5-VL-32B-Instruct`
* **Link para o Modelo:** [Qwen/Qwen2.5-VL-32B-Instruct no Hugging Face](https://huggingface.co/Qwen/Qwen2.5-VL-32B-Instruct)
* **Janela de Contexto:** O modelo suporta uma memória de trabalho (janela de contexto) de até **32.768 tokens**, o que permite o uso de prompts complexos e a geração de respostas detalhadas.

#### Parâmetros de Geração

Para controlar a qualidade e o formato da resposta, utilizamos os seguintes parâmetros:

* **`max_tokens: 4096`**: Limitamos o comprimento máximo da resposta gerada para 4096 tokens, valor que nos dá a capacidade de gerar até 10 questões detalhadas em uma única chamada. Isso garante que as respostas sejam completas sem serem excessivamente longas, além de otimizar o tempo de processamento.
* **`temperature: 0.6`**: Este valor controla a "criatividade" do modelo. Uma temperatura de `0.6` oferece um ótimo equilíbrio entre seguir as instruções de forma precisa e ainda ter criatividade para gerar questões originais.

#### Estratégia do Agente

O comportamento do agente é guiado por um conjunto de instruções e ferramentas.

* **Prompt Principal (`prompts.yaml`):** O "manual de instruções" do agente está em um arquivo `prompts.yaml`, que consome ,atualmente, aproximadamente **3.000 tokens**. Ele contém as regras de operação e múltiplos exemplos que o ensinam a raciocinar (`Thought:`) e a usar suas ferramentas (`Code:`).
* **Ferramentas Python:** O agente não está limitado a gerar apenas texto. Ele tem acesso a um conjunto de ferramentas Python customizadas (ex: `plot_parabola_graph`, `generate_data_table`) que permitem a ele executar ações complexas, como gerar gráficos e tabelas.

#### A Saída: Objeto Python (Estrutura JSON) vs. Apresentação Visual

Como a resposta final é produzida:

1.  **A Saída Real do Agente é um Objeto Python:** A resposta fundamental que o agente gera e que nosso código manipula é um objeto Python (especificamente, uma lista de dicionários). Essa estrutura de dados foi projetada para ser facilmente convertível para o formato JSON, pois segue todas as suas convenções e poderá ser integrado com outros sistemas, como o site da empresa.

2.  **O Gradio Renderiza o JSON para o Usuário:** A interface do **Gradio**, através da nossa função `render_single_question()`, atua como um interpretador visual:
    * Ele lê o objeto Python (a lista de dicionários) retornado pelo agente.
    * Extrai as informações de cada campo (`enunciado`, `alternativas`, etc.).
    * Exibe tudo de forma formatada e amigável no chat.
    * Se o JSON contém um caminho para um gráfico (`url_grafico`), o Gradio carrega e **mostra a imagem** diretamente na interface.

Isso garante que o agente tenha uma saída robusta e padronizada (JSON), ao mesmo tempo em que oferece uma experiência de usuário rica e visual.