README.md

metadata

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
• 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.