TP3: O Agente Autônomo e Demoday

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

Published

25/07/2026

Modified

25/07/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)

📖 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: ["matematica", "io", "variaveis"]).

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: TDD_FALSE_GREEN
  helpTip: "Erro na declaração de tipo de variável."

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 (o mesmo arquivo wok-scheme.json da tese do professor).
Antes de gerar o YAML, o LLM é instruído: “Você só pode usar skills que existam neste enum: [condicionais, lacos, vetores, …]. Você só pode usar testTypes que existam neste enum: [INPUT, TDD, TDD_FALSE_GREEN, PERFORMANCE].”
Após a geração, um validador Python verifica o YAML contra o JSON Schema. 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).

🎯 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: TDD
    helpTip: "Verifique os testes básicos do enunciado."
    skills:
      - { skill: io, points: 1 }
      - { skill: matematica, points: 1 }
      - { skill: operadores, points: 1 }

  - id: "c-simples"
    name: "Testes Simples"
    level: "C"
    testType: TDD
    helpTip: "Fizemos novos testes simples e algo deu errado."
    skills:
      - { skill: matematica, points: 1 }

  - id: "c-falso-positivo-inteiros"
    name: "Inteiros - Falso Positivo"
    level: "C"
    testType: TDD_FALSE_GREEN
    helpTip: "Erro na declaração de tipo de variável."
    skills:
      - { skill: matematica, points: 1 }

  - id: "a-dizima"
    name: "Dízimas"
    level: "A"
    testType: TDD
    helpTip: "Qual seria a resposta correta para 1/3?"
    skills:
      - { skill: matematica, 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.

2. O Rascunho Científico (Draft 3)

A última rodada de avaliação da “Fábrica de Pesquisa”. * Avaliação de Alucinação do Agente: O grupo documentará as taxas de erro no Tool Calling e a quantidade de tentativas necessárias para o ciclo de Self-Healing passar na malha de validação do Schema. * A Grande Batalha (Rede Neural vs LLM): O coração científico do projeto. O grupo usará o YAML Original (Ground Truth) dos arquivos para medir quem teve a melhor performance na classificação de Habilidades: a Rede Neural customizada construída no TP1 ou o raciocínio emergente do Agente Autônomo construído agora no TP3. Discussão crítica sobre precisão, custo 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”.)

📊 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

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
Misconceptions geradas são pedagogicamente plausíveis	2	A helpTip faz sentido para o cenário descrito
Draft 3 com comparativo NN vs LLM	1	Tabela comparativa, gráficos, discussão
Demoday: apresentação ao vivo	2	Clareza, domínio técnico, sistema roda sem travar