TP3: O Agente Autônomo e Demoday

Orquestração, Tool Calling, Data Anchoring e Qualidade (Fases 4 e 5 do Pipeline)

Conteúdo de estudo sobre TP3: O Agente Autônomo e Demoday para a disciplina de Inteligência Artificial II (Prof. Aléssio M. Jr).

Data de Publicação

08/09/2026

Data de Modificação

02/09/2026

🧭 Por que este TP existe?

É o momento da consolidação. Nos TPs anteriores, vocês construíram dois microsserviços independentes:

TP1: Uma API que prevê skills a partir de um enunciado (POST /predict).
TP2: Uma API que busca exercícios similares num banco vetorial (GET /search).

Agora, vocês vão construir o Gerente: um Agente Autônomo (construído com LangChain ou LlamaIndex) que usa essas duas APIs como ferramentas para percorrer automaticamente as Fases 4 e 5 do Pipeline WOKDEX.

O objetivo final é claro: o agente recebe o texto bruto de um exercício de programação e gera, do zero, o metadata.yaml completo no formato WOKDEX — incluindo skills, cenários de teste, misconceptions e dicas formativas.

Data Limite de Entrega (Checkpoint 3): 30/11 (Segunda-feira) - No Demoday.

Valor: 20 Pontos (10 em Grupo, 10 Individual)

🤖 LLM Permitido e Custo

Para o Tool Calling e o raciocínio do Agente, o grupo utilizará um dos LLMs abaixo:

LLM	Custo	Observação
Google Gemini 2.0 Flash (via API)	🆓 Gratuito (tier free)	Modelo padrão recomendado. API key fornecida pelo professor.
OpenAI GPT-4o-mini (via API)	💰 Pago	API key fornecida pelo professor (cota compartilhada, máx. R$10/grupo).
Llama 3 8B (via Ollama, local)	🆓 Gratuito	Roda na máquina do aluno. Sem dependência de cloud.

[!WARNING] Limite de Custo e Prevenção de Rate Limits (Boas Práticas de Engenharia):
Loops reflexivos de auto-cura (Self-Healing) podem consumir tokens desnecessariamente e disparar erros de HTTP 429 (Too Many Requests) se não forem configurados corretamente. É obrigatório adotar: 1. Trava de Iteração: Configure rigorosamente max_retries = 3 no loop de Self-Healing. Se o JSON não for corrigido na 3ª tentativa, registre o log e aborte. 2. Cache Local de LLM durante o Desenvolvimento: Ative o cache em SQLite para não reenviar requisições repetidas ao debugar: python from langchain_community.cache import SQLiteCache from langchain.globals import set_llm_cache set_llm_cache(SQLiteCache(database_path=".langchain_cache.db")) 3. Exponential Backoff: Use esperas com fator exponencial (1s, 2s, 4s) ao capturar falhas de rede.

[!TIP] A variação experimental (diferentes LLMs entre grupos) gerará dados comparativos valiosos: qual LLM alucina menos no Schema WOKDEX? Qual gera misconceptions mais precisas?

📖 Leitura Obrigatória (Fundamentação)

Antes de programar, vocês precisam ler e entender estes dois artigos científicos. Eles serão a base do Draft 3 na seção de Trabalhos Relacionados.

Artigo 1: Yao, S. et al. (2023). “ReAct: Synergizing Reasoning and Acting in Language Models”. arXiv:2210.03629: Por que ler: Este paper formalizou o padrão Reason + Act (Raciocinar → Agir → Observar → Raciocinar de novo). É exatamente o loop que o agente de vocês vai executar: ele raciocina (“preciso saber as skills”), age (chama predict_skills()), observa o resultado, e raciocina de novo (“agora preciso buscar exercícios similares”). Sem ler o ReAct, vocês não entendem por que o agente funciona.
Artigo 2: Schick, T. et al. (2023). “Toolformer: Language Models Can Teach Themselves to Use Tools”. arXiv:2302.04761: Por que ler: Publicado pela Meta AI, este paper demonstrou que LLMs podem aprender a chamar APIs externas (calculadoras, buscadores, bancos de dados) de forma autônoma. É a fundamentação teórica para o conceito de @tool no LangChain. Quando o agente de vocês decide sozinho que precisa chamar search_similar_cases(), ele está replicando o mecanismo descrito neste paper.

🔧 O Pipeline de 5 Fases em Detalhe

Abaixo está o detalhamento de cada fase do pipeline que o agente deve executar. As Fases 1-3 usam as APIs dos TPs anteriores. As Fases 4-5 são construídas neste TP.

Fase 1: Leitura do Enunciado

O agente recebe o texto bruto de um exercício (ex: “Leia dois inteiros A e B. Imprima A/B com duas casas decimais.”). Ele extrai as informações descritivas: título, nível (CS1/CS2/CS3), complexidade estimada.

Fase 2: Inferência de Skills (→ chama o TP1)

O agente invoca a ferramenta predict_skills(), que faz uma requisição POST /predict na API FastAPI do TP1. A resposta contém as skills previstas pela Rede Neural (ex: ["Math", "Array", "Two Pointers"]).

Fase 3: Busca de Exercícios Similares (→ chama o TP2)

O agente invoca a ferramenta search_similar_cases(), que faz uma requisição GET /search na API Spring Boot do TP2. Os exercícios retornados servem de contexto para o LLM, evitando que ele invente cenários de teste sem base na realidade.

Fase 4: Geração de Misconceptions (Chain-of-Thought)

Esta é a fase mais sofisticada. O agente usa a técnica de Chain-of-Thought (CoT): ele instrui o LLM a pensar como um aluno novato e tentar resolver o exercício cometendo erros conceituais comuns. A partir desses erros simulados, o agente gera os cenários MISCONCEPTION com suas respectivas helpTip.

Exemplo de raciocínio CoT para o exercício “Divisão”:

“Eu sou um aluno de CS1. O exercício pede para dividir dois números. Eu sei que preciso declarar variáveis. Vou declarar como int porque são números inteiros. Agora faço resultado = a / b. Para 10/2 = 5, funciona! Mas para 19/6… deu 3 em vez de 3.17. Ah, eu deveria ter usado double!”

O agente captura essa lógica e gera o cenário:

- id: "c-falso-positivo-inteiros"
  testType: MISCONCEPTION
  helpTip: "Erro na declaração de tipo de variável."
  targetLanguages: ["c", "cpp", "java"]

Fase 5: Montagem e Validação do YAML (Data Anchoring)

O agente monta o metadata.yaml final e valida contra o JSON Schema oficial do WOKDEX. Se algum campo estiver fora do formato (ex: o LLM inventou uma skill que não existe no enum), o validador rejeita e o agente tenta novamente automaticamente (Self-Healing).

🛠️ O que é Tool Calling?

Um LLM sozinho não acessa a internet e não se conecta a bancos de dados. Ele apenas gera texto. Para que o agente possa consultar as APIs do TP1 e TP2, usamos Tool Calling: o LLM recebe uma lista de “ferramentas” disponíveis (funções Python decoradas com @tool) e decide, durante o raciocínio, quando e qual ferramenta chamar.

Exemplo no LangChain:

@tool
def predict_skills(enunciado: str) -> dict:
    """Chama a API do TP1 para prever as skills de um enunciado."""
    response = requests.post("http://tp1-api:8000/predict", 
                             json={"enunciado": enunciado})
    return response.json()

@tool
def search_similar_cases(query: str, k: int = 3) -> dict:
    """Chama a API do TP2 para buscar exercícios similares."""
    response = requests.get(f"http://tp2-api:8080/search?q={query}&k={k}")
    return response.json()

O LLM lê a descrição dessas ferramentas e decide autonomamente: “Preciso saber as skills deste exercício. Vou chamar predict_skills().” Depois: “Agora preciso ver exercícios parecidos. Vou chamar search_similar_cases().”

⚓ O que é Data Anchoring (Ancoragem de Dados)?

O maior risco de usar um LLM para gerar o metadata.yaml é a alucinação de formato: o LLM pode inventar campos que não existem, usar skills fora do vocabulário controlado, ou gerar YAML sintaticamente inválido.

Data Anchoring é a técnica que “ancora” a I.A. aos dados reais:

O agente recebe o JSON Schema oficial do WOKDEX (wok-problem.json, disponível em trabalho/recursos/).
Antes de gerar o YAML, o LLM é instruído: “Você só pode usar skills que existam neste enum: [condicionais, loops, arrays, …]. Você só pode usar testTypes que existam neste enum: [SAMPLE, FUNCTIONAL, MISCONCEPTION, PERFORMANCE].”
Após a geração, um validador Python verifica o YAML contra o JSON Schema oficial (wok-problem.json, disponível em trabalho/recursos/). Se falhar, o erro exato é devolvido ao LLM para que ele corrija (Self-Healing).

[!WARNING] Sem Data Anchoring, os testes mostraram que o LLM inventa campos como testType: "LOGIC_ERROR" (que não existe no schema) ou skills como "programacao_basica" (que não está no enum). A ancoragem é o que transforma o LLM de um “escritor criativo” em um “engenheiro de dados confiável”.

👥 A Divisão de Tarefas na Equipe (4 Alunos)

Sua equipe deverá se dividir em duas grandes forças-tarefa.

🧠 Dupla 1: Orquestração e Tool Calling (A Ação)

Esta dupla é focada em ligar o Agente com o mundo exterior. Seu dever é ensinar a LLM a raciocinar, chamar APIs externas, e montar a lógica reflexiva da Ancoragem de Dados.

Aluno A (Tool Maker / Integrador de APIs):
- Trabalho Individual: Programa a interface de ferramentas. Mapeia e formaliza o código (@tool no LangChain, por exemplo) instruindo ao LLM que existe uma função predict_skills(enunciado) (que bate no FastAPI do TP1) e uma função search_similar_cases(query) (que bate no Spring Boot do TP2).
Aluno B (Arquiteto Cognitivo e Prompt Engineer):
- Trabalho Individual: Usa a técnica de Chain-of-Thought (CoT) para construir o cérebro (Prompt de Sistema) do agente. É ele quem força a Inteligência Artificial a pensar sobre “como um aluno humano novato cometeria o erro neste exercício”, mapeando as Misconceptions exigidas pelo WOKDEX.

🛡️ Dupla 2: Conformidade e Garantia de Qualidade (O Guardião)

A Inteligência Artificial é instável por natureza. Esta dupla cria a camisa de força matemática (O Juiz) que garante que a saída gerada seja sintaticamente imaculada, pronta para salvar em banco.

Aluno C (Desenvolvedor de Schema - Data Anchoring):
- Trabalho Individual: Recebe a reflexão do Aluno B e programa um OutputParser rigoroso. Ele escreve o Schema exato (usando Pydantic ou serialização YAML) que a LLM é forçada a obedecer na Fase 5 do Pipeline WOKDEX.
Aluno D (QA Engineer e Self-Healing):
- Trabalho Individual: É a última linha de defesa. Cria um script Python (HitL - Human in the Loop Simulator) que varre o metadata.yaml gerado pelo LLM. Se um colchete faltar, ou se o YAML corromper, o script deste aluno lança uma Exceção que captura o erro exato e devolve automaticamente para a IA consertar, em um laço fechado (Self-Healing).

[!TIP] 🤝 Dinâmica de Pareamento (Pair Programming) e Desenvolvimento Não-Bloqueante:
A Dupla 2 (Schema e Self-Healing) não precisa esperar o Agente da Dupla 1 estar 100% pronto para programar:
1. A Dupla 2 pode criar exemplos de YAML com erros sintáticos e estruturais intencionais para validar e depurar o validador Pydantic e o laço de Self-Healing imediatamente. 2. Enquanto isso, a Dupla 1 programa as @tools e constrói o prompt de raciocínio CoT. 3. As duplas trabalham em pareamento para fechar o ciclo de orquestração com testes de integração contínuos.

🎯 A Saída Esperada: O `metadata.yaml`

O produto final do agente é um arquivo metadata.yaml completo e válido. Abaixo está o gabarito (baseado no exercício “Divisão” real da tese) que o agente deve ser capaz de gerar:

version: "1.0"
id: 0003
name: "Divisão"
slug: "divisao"
description: "O algoritmo deve ler dois números e dividi-los, 
              mas é preciso ter cuidado com a formatação."
difficultyLevelId: "D"
timeComplexity: "O(1)"
skills:
  - "matematica"
  - "io"

testScenarios:
  - id: "d-sample"
    name: "Exemplos"
    level: "D"
    testType: SAMPLE
    description: "Verifica os exemplos do enunciado."
    helpTip: "Verifique os testes básicos do enunciado."
    skills:
      - { skill: io, points: 1 }
      - { skill: mathematics, points: 1 }

  - id: "c-simples"
    name: "Testes Simples"
    level: "C"
    testType: FUNCTIONAL
    description: "Verifica comportamentos não revelados ao aluno."
    helpTip: "Fizemos novos testes simples e algo deu errado."
    skills:
      - { skill: mathematics, points: 1 }

  - id: "c-falso-positivo-inteiros"
    name: "Inteiros - Falso Positivo"
    level: "C"
    testType: MISCONCEPTION
    description: "Detecta alunos que usaram int em vez de double."
    helpTip: "Erro na declaração de tipo de variável."
    targetLanguages: ["c", "cpp", "java"]
    skills:
      - { skill: mathematics, points: 1 }

  - id: "a-dizima"
    name: "Dízimas"
    level: "A"
    testType: FUNCTIONAL
    description: "Verifica arredondamento correto de dízimas."
    helpTip: "Qual seria a resposta correta para 1/3?"
    skills:
      - { skill: mathematics, points: 1 }

[!TIP] Observe que o cenário c-falso-positivo-inteiros tem testType: TDD_FALSE_GREEN. É o MISCONCEPTION — a armadilha que detecta o aluno que usou int em vez de double. O agente de vocês precisa ser capaz de inventar esse tipo de cenário autonomamente, usando Chain-of-Thought.

📝 A Entrega Global (O Grupo)

1. O Código Unificado (O Ecossistema)

O trabalho de engenharia culmina na integração total. O grupo terá de provar que a chamada principal do TP3 faz cascatear comandos até o TP1 e TP2. O projeto deverá rodar perante o público, do zero à emissão do documento pedagógico WOKDEX.

[!TIP] 🛡️ Rede de Segurança (APIs Golden de Fallback do Professor):
Como a orquestração do Agente no TP3 depende das chamadas de rede ao TP1 e TP2, o professor disponibilizará contêineres oficiais de referência (Golden APIs). Se o microsserviço do seu grupo no TP1 ou TP2 apresentar instabilidade crítica insuperável, a equipe poderá consumir temporariamente a API do professor (com pequeno desconto proporcional na nota de integração daquela etapa anterior), garantindo que 100% dos grupos consigam programar o Agente, o Tool Calling, o Self-Healing e defender no Demoday.

2. O Artigo Científico Consolidado (Formato SBC — 4 a 6 páginas)

A consolidação de toda a “Fábrica de Pesquisa” acontece aqui. O grupo reúne as métricas e diagramas documentados nos README.md do TP1 e TP2 e redige um Artigo Científico Completo no formato SBC (4 a 6 páginas): * Introdução e Trabalhos Relacionados: Contextualização do “Silêncio Pedagógico” e citações fundamentadas (Kim 2014, CodeBERT, Lewis 2020, ReAct). * Metodologia do Ecossistema WOKDEX: Descrição da arquitetura de 3 pilares (Classificador Keras + Oráculo RAG Spring AI + Agente Orquestrador). * Avaliação de Alucinação e Robustez: Taxas de erro no Tool Calling, taxa de conformidade sintática com o Schema WOKDEX e média de tentativas no ciclo de Self-Healing. * A Grande Batalha Científica (Rede Neural vs. RAG vs. LLM): O coração científico do artigo: 1. A Rede Neural (TP1) com inferência em ~2ms vs. o raciocínio emergente da LLM (TP3) com inferência em ~3s. 2. Onde a rede clássica falha pelo Abismo Semântico e onde a LLM consegue deduzir a estratégia algorítmica via Chain-of-Thought. 3. Estudo de Ablação: Pipeline com RAG (C1) vs. Pipeline sem RAG (C2). 4. Discussão crítica de engenharia: trade-offs entre precisão, custo financeiro e tempo de resposta.

3. O Demoday Final (A Defesa de Ouro) 🏅

Apresentação final ao vivo (Pitch). * A Banca: O grupo terá cerca de 3 a 5 minutos no telão para mostrar o Ecosistema completo consumindo o texto bruto de um problema novo (não visto durante as aulas), processando-o no Pipeline WOKDEX e gerando a meta-estrutura correta.

(As melhores arquiteturas e textos desta etapa formarão a equipe oficial de redação que juntará todos os rascunhos no “Mega-Artigo”.)

🎤 Roteiro Obrigatório do Pitch (Demoday)

Cada grupo terá exatamente 5 minutos no telão, seguidos de 3 minutos de perguntas da banca. A estrutura é obrigatória:

Fase	Tempo	Conteúdo	Quem fala
1. O Problema	30s	“Juízes online dão Wrong Answer sem explicação. Isso causa reprovação.”	Qualquer membro
2. Arquitetura	60s	Diagrama TP1→TP2→TP3 do grupo. Quem fez o quê.	Aluno A ou C
3. Demo ao Vivo	120s	Enunciado novo (não visto nas aulas) → Pipeline roda → YAML gerado.	Aluno B (opera o terminal)
4. Resultados	60s	F1 do TP1, Precision@3 do TP2, taxa de alucinação do TP3, tabela NN vs LLM.	Aluno D
5. Lições Aprendidas	30s	“O que faríamos diferente? O que surpreendeu?”	Qualquer membro

[!IMPORTANT] Lidando com falhas ao vivo: Se a demo travar, o grupo deve ter um vídeo de backup (gravação de tela da demo funcionando). A banca aceita o vídeo como evidência, mas a nota de “demo ao vivo” é reduzida em 50%.

⚔️ Testes Adversariais Obrigatórios

Além de testar com enunciados normais, o grupo deve documentar o comportamento do agente em 3 cenários adversariais:

#	Cenário	O que testar
1	Enunciado em inglês	O corpus é em português. O agente lida com a barreira linguística? Alucina? Traduz?
2	Enunciado ambíguo	Ex: “Manipule uma sequência de dados” — pode ser vetores, strings ou filas. O agente escolhe skills coerentes?
3	Enunciado fora do domínio	Ex: “Faça uma receita de bolo de chocolate.” O agente recusa? Gera YAML inválido? Qual é o guardrail?

O grupo deve documentar no Draft 3: - O input exato usado - O output gerado pelo agente - Se o YAML validou contra o schema - Quais guardrails foram implementados para mitigar os riscos

🔄 Validação Cruzada entre Grupos (Inspirado no Loop de Retroalimentação)

No mundo real da pesquisa, quem gera um artefato nunca é a mesma pessoa que o valida. Para simular isso, o Demoday inclui uma rodada de validação cruzada:

Sorteio de pares: Na semana do Demoday, o professor sorteia pares de grupos (ex: Grupo 3 valida o Grupo 7).
Enunciado surpresa: O grupo avaliador recebe 1 enunciado novo (nunca visto pelo grupo avaliado) e o submete ao pipeline do grupo avaliado.
Relatório de falhas: O grupo avaliador documenta:
- O YAML gerado validou contra o schema? (sim/não)
- As skills previstas fazem sentido para o enunciado? (sim/parcial/não)
- As misconceptions geradas são pedagogicamente plausíveis? (sim/não)
- A helpTip ajudaria um aluno real? (sim/não)
Feedback público: No Demoday, cada grupo avaliador apresenta o relatório de falhas do grupo avaliado (2 minutos, logo após a apresentação do grupo).

[!TIP] Este processo é inspirado no Loop de Retroalimentação da pesquisa WOKDEX: o Plano 2 (Simulated Students) da tese do professor valida os artefatos gerados pelo Plano 1 (Pipeline). Aqui, vocês são os Simulated Students do grupo parceiro.

🧪 Ablation Leve: Com vs. Sem RAG

Para que o Draft 3 tenha peso científico, cada grupo deve executar uma comparação ablativa simples:

Condição	Configuração	O que mede
C1: Pipeline Completo	TP1 (skills) + TP2 (RAG) + TP3 (agente)	Performance total do sistema
C2: Sem RAG	TP1 (skills) + TP3 (agente), sem chamar o TP2	Quanto o RAG contribui?

Para cada condição, o grupo roda o pipeline em 5 enunciados e reporta:

Quantos YAMLs validaram na 1ª tentativa?
Quantas skills foram previstas corretamente (vs. gabarito do professor)?
As misconceptions são mais genéricas sem RAG?

[!NOTE] Isso gera uma tabela comparativa de 2 condições no Draft 3 — simples o suficiente para ser executável em 50 minutos, mas robusto o suficiente para sustentar um argumento científico real: “O componente RAG reduziu a taxa de alucinação de X% para Y%.”

🎯 Critérios Objetivos para Avaliação de Misconceptions (Heurística HMD)

Para eliminar qualquer subjetividade na avaliação das dicas e cenários de erro pedagógicos gerados pelo Agente, o sistema de auditoria do professor aplicará 3 regras automatizadas e objetivas:

#	Regra de Validação	Como é calculada pelo script de teste	Critério de Sucesso
1	Regra Anti-Spoiler (Não-Revelação)	Mede a sobreposição léxica/tokens entre a `helpTip` gerada e o `solution_code_python` do dataset	Sobreposição $< 40\%$ (a dica guia o raciocínio sem entregar a linha de código)
2	Regra do Gatilho (Test Triggering)	Executa o caso de teste `MISCONCEPTION` contra o código com erro simulado e contra o gabarito	Reprova o código bugado e aprova o código gabarito oficial
3	Conformidade com Schema (Data Anchoring)	Valida o JSON gerado contra o `wok-problem.json`	$100\%$ de compliance (zero erros estruturais)

📊 Rubrica de Avaliação Detalhada (20 Pontos)

Nota Individual (10 pts)

Critério	Pontos	Detalhes
Commits individuais na branch correta	2	Avaliado via Git Blame
Tools funcionam (A) OU Prompts geram CoT (B) OU Schema valida (C) OU Self-Healing funciona (D)	6	O módulo individual funciona isoladamente
Qualidade e organização do código	2	Docstrings, separação de responsabilidades, cache local

Nota do Grupo (10 pts)

Critério	Pontos	Detalhes
Pipeline end-to-end funciona	3	Enunciado bruto entra → `metadata.yaml` válido sai
YAML gerado valida contra o JSON Schema	2	Zero erros de validação no schema oficial
Validação Objetiva de Misconceptions (HMD)	1.5	Atende às regras Anti-Spoiler e do Gatilho do Test Case
Testes adversariais documentados	0.5	3 cenários adversariais testados e documentados
Artigo Científico SBC Consolidado (NN vs. RAG vs. LLM)	1	Tabela comparativa, ablação com/sem RAG, gráficos e discussão crítica
Demoday: apresentação ao vivo	2	Clareza, domínio técnico, sistema roda sem travar

🏆 Bônus de Excelência (pontos extras)

Bônus	Valor	Critério
F1 ≥ 80% no TP1	+0.5 pt	Validado no dataset de teste do professor
Precision@3 ≥ 90% no TP2	+0.5 pt	Validado no Golden Test Set
YAML valida na 1ª tentativa (sem Self-Healing)	+0.5 pt	O agente gera YAML correto sem loop de correção
Ablation mostra delta significativo	+0.5 pt	Diferença mensurável entre C1 e C2, com discussão crítica
Relatório de validação cruzada excepcional	+0.5 pt	Feedback detalhado, construtivo e tecnicamente preciso
Artigo aceito em conferência	+5 pts	Publicação real com coautoria (creditado no semestre seguinte)

📅 Cronograma Sugerido (4 Semanas)

Para não acumular trabalho e perder a data de entrega, sugerimos o seguinte ritmo para a equipe:

Período	Foco da Equipe	Meta da Semana
Semana 1	Tools e Conexão	Construção das tools que chamam a API FastAPI (TP1) e a API Spring (TP2). O agente já consegue acessar o mundo externo.
Semana 2	Prompt Engineering	Construção do prompt do Agente, simulação do “Aluno Novato” e geração do CoT (Chain of Thought) para as misconceptions.
Semana 3	Data Anchoring	Implementação da validação via Pydantic/Instructor e loop de Self-Healing para garantir que o JSON gerado seja válido.
Semana 4	Ciência e Demoday	Execução do Ablation (Com vs Sem RAG), redação do Artigo Científico Consolidado (SBC) e ensaio para o Demoday.

De volta ao topo