← Voltar a studyAI — Documentação do Projeto

🤖 Agentes LangGraph

studyAI — Documentação do Projeto

Apresentação

Agentes LangGraph — studyAI

Documento de referência de todos os agentes: core, RAG QA, e opcionais. Inclui o grafo de orquestração com edges e conditional edges.

Índice

Agentes Core
Agentes Opcionais
Grafo de Orquestração
Fluxos por Intent
RAG por Agente

Agentes Core

1. Router

Papel: Orquestrador central. Interpreta o pedido do utilizador e decide para onde encaminhar.

Campo	Valor
Input	Mensagem do utilizador + contexto (project_id, histórico)
Output	`Intent` (enum) + metadados opcionais
Quando	Sempre no início de cada pedido

Intents:

generate_content — criar material sobre um tópico
qa — perguntar sobre o material (chat)
evaluate — avaliar resposta do utilizador a uma pergunta
summarize — resumir documento ou secção
expand — expandir secção existente
generate_questions — gerar mais perguntas
general — fallback, conversa geral

Implementação: Hybrid Router — rules + LLM.

Rules: Keywords para casos óbvios (ex: "avalia" → evaluate, "resume" → summarize)
LLM: Para ambiguidades, classificação com confidence score
Fallback: Se confidence < 0.7 → encaminhar para qa (RAG QA Agent)
Output: { intent, confidence?, metadata? }

2. Content Planner

Papel: Decide que documentos/tópicos criar e o que pesquisar.

Campo	Valor
Input	Tópico pedido + ficheiros indexados (project_id) + user_profile (opcional)
Output	`{ sections, confidence?, missing_topics? }`
Quando	Intent `generate_content`

Tarefas:

Analisar chunks relevantes via RAG
Propor estrutura lógica (títulos, sub-títulos)
Definir ordem de escrita
Identificar lacunas (se ficheiros não cobrirem o tópico)
Decidir que sub-tópicos pesquisar nos docs do user
Adaptar a user_profile.weak_topics (mais detalhe nesses tópicos)

Output expandido:

{
  "sections": [{ "title": "...", "subsections": [...] }],
  "confidence": 0.82,
  "missing_topics": ["complicações pós-operatórias"]
}

RAG: Retrieval sobre ficheiros do projeto. Top-k chunks por secção planeada.

3. Content Writer

Papel: Recebe os tópicos do Planner e escreve o conteúdo.

Campo	Valor
Input	Secção a escrever + estrutura + chunks RAG + mode
Output	Markdown da secção
Quando	Após Content Planner (uma chamada por secção)

Modos de escrita:

Mode	Comportamento	Quando usar
strict	RAG only — cita apenas o que está nos chunks. Não inventa.	Material técnico, exames, quando precisão é crítica
hybrid	RAG + general knowledge — pode complementar com conhecimento geral quando chunks são insuficientes	Material introdutório, quando chunks têm lacunas

Tarefas:

Escrever uma secção de cada vez
Fundamentar em chunks recuperados (sempre)
Tom didático
Em mode=strict: zero invenção. Em mode=hybrid: complementar com cuidado, indicar quando extrapola.

RAG: Tem acesso ao RAG dos documentos que o user carregou na app. Recebe chunks pré-filtrados por secção; pode fazer retrieval adicional.

4. Question Generator

Papel: Após os tópicos estarem criados, gera X perguntas por tópico.

Campo	Valor
Input	Documento (ou secção) + tipo de pergunta + quantidade + user_profile.level
Output	Lista de `{ question, solution, spoken?, difficulty }`
Quando	Após Content Writer terminar, ou intent `generate_questions`

Tarefas:

Gerar perguntas de recall (o que é X?)
Perguntas de aplicação (como faria Y?)
Perguntas de comparação (diferença entre A e B?)
Incluir solution (resposta modelo) e opcionalmente spoken (versão para dizer em voz alta)
Adicionar difficulty: easy | medium | hard — adaptado ao user_level

Distribuição por nível: beginner → mais easy; advanced → mais hard.

RAG: Pode usar o documento gerado ou chunks do material original como contexto.

5. Question Evaluator

Papel: Avalia e corrige as respostas que o utilizador dá às perguntas.

Campo	Valor
Input	Resposta do user + pergunta + solution + material + user_profile
Output	Score + feedback por critério + correções
Quando	Intent `evaluate`

Implementação: Hybrid evaluation (reduz inconsistência do LLM):

Rule-based baseline: Keywords overlap, length ratio, estrutura. Score 0–100.
LLM evaluation: Feedback qualitativo, critérios (accuracy, completeness, clarity).
Combine: final_score = 0.3 * rule_score + 0.7 * llm_score (ou weighted average configurável).

Tarefas:

Comparar resposta com solution e material
Avaliar por critérios separados
Dar feedback adaptado (mais pormenorizado em weak_topics)
Sugerir melhorias concretas

Output expandido (critérios separados):

{
  "score": 80,
  "rule_score": 75,
  "llm_score": 82,
  "accuracy": 85,
  "completeness": 70,
  "clarity": 90,
  "feedback": "...",
  "corrections": ["..."]
}

RAG: Material de referência pode ser chunks relevantes ou documento completo.

6. RAG QA / Chat Agent

Papel: Responde a perguntas abertas sobre o material durante o estudo.

Campo	Valor
Input	Pergunta do utilizador + project_id
Output	Resposta fundamentada + citações (fontes)
Quando	Intent `qa`

Tarefas:

Embed da pergunta
Retrieval (vector search nos docs do projeto)
Construir contexto com top-k chunks
Gerar resposta fundamentada nos chunks
Indicar fontes (doc, secção)

RAG: Core do agente. Vector search no índice do projeto. Opcional: hybrid (BM25 + dense), reranking.

Exemplo:

User: "O que é uma colonoscopia?"
  → Router: qa
  → RAG QA Agent: retrieval + resposta
  → "A colonoscopia é um exame endoscópico que..."

Agentes Opcionais

7. Summarizer

Papel: Resume documento ou secção.

Campo	Valor
Input	Documento ou secção + tipo de resumo (bullet, parágrafo)
Output	Resumo em Markdown
Quando	Intent `summarize`

Alternativa: Content Writer com prompt diferente. Agente dedicado se quiseres lógica específica (ex: resumo por secção, flashcards a partir do resumo).

8. Research Agent

Papel: Pesquisa na web para enriquecer o material.

Campo	Valor
Input	Query de pesquisa + contexto (tópico, lacunas)
Output	Conteúdo relevante (texto, links)
Quando	Chamado pelo Content Planner quando há lacunas nos docs do user

Nota: Só faz sentido se quiseres ir além dos ficheiros carregados. Para MVP, pode ficar de fora (Content Planner indica lacunas sem pesquisar).

9. Expand Agent

Papel: Expande uma secção existente com mais detalhes.

Campo	Valor
Input	Secção atual + pedido de expansão ("adiciona mais sobre complicações")
Output	Secção expandida em Markdown
Quando	Intent `expand`

Alternativa: Content Writer com contexto da secção e prompt "expandir".

10. Flashcard Generator

Papel: Gera flashcards a partir do material.

Campo	Valor
Input	Documento ou secção
Output	Lista de `{ front, back }`
Quando	Intent `generate_flashcards` ou após gerar documento

Nota: Feature futura. Pode ser variante do Question Generator (perguntas curtas = front, resposta = back).

11. Spaced Repetition Scheduler

Papel: Decide o que o utilizador deve rever hoje.

Campo	Valor
Input	Histórico de respostas (scores, datas)
Output	Lista de perguntas/tópicos para rever
Quando	Intent `what_to_review` ou dashboard

Nota: Feature futura. Mais lógica de negócio do que agente LLM — pode ser regras (SM-2, etc.) ou LLM para personalização.

Grafo de Orquestração

Diagrama Mermaid

A carregar diagrama…

Grafo com Conditional Edges (LangGraph)

Estrutura conceptual em pseudocódigo LangGraph:

NODES:
  - router
  - content_planner
  - content_writer
  - question_generator
  - rag_qa_agent
  - question_evaluator
  - summarizer
  - expand_agent
  - research_agent (opcional)

EDGES:
  - START → router

CONDITIONAL EDGES (from router):
  - router --[intent==generate_content]--> content_planner
  - router --[intent==qa]--> rag_qa_agent
  - router --[intent==evaluate]--> question_evaluator
  - router --[intent==summarize]--> summarizer
  - router --[intent==expand]--> expand_agent
  - router --[intent==generate_questions]--> question_generator
  - router --[intent==general]--> rag_qa_agent  # fallback

CONDITIONAL EDGES (from content_planner):
  - content_planner --[has_gaps]--> research_agent
  - content_planner --[no_gaps]--> content_writer
  - research_agent --> content_writer

CONDITIONAL EDGES (from content_writer):
  - content_writer --[has_next_section]--> content_writer  # loop
  - content_writer --[no_next_section]--> question_generator

TERMINAL NODES (go to END):
  - rag_qa_agent
  - question_evaluator
  - summarizer
  - expand_agent
  - question_generator

Diagrama Detalhado — Fluxo generate_content

                    ┌─────────────┐
                    │   Router    │
                    └──────┬──────┘
                           │ intent=generate_content
                           ▼
                    ┌─────────────────┐
                    │ Content Planner │
                    └──────┬──────────┘
                           │
              ┌────────────┴────────────┐
              │ has_gaps?               │ no_gaps
              ▼                         ▼
     ┌─────────────────┐        ┌─────────────────┐
     │ Research Agent  │───────►│ Content Writer  │
     └─────────────────┘        └────────┬────────┘
                                          │
                              ┌───────────┴───────────┐
                              │ has_next_section?     │
                              ▼                       ▼
                     ┌─────────────────┐      ┌──────────────────┐
                     │ Content Writer  │      │ Question Generator│
                     │ (loop)          │      └─────────┬──────────┘
                     └────────┬────────┘                │
                              │                          │
                              └──────────┬───────────────┘
                                          │
                                          ▼
                                    ┌──────────┐
                                    │   END    │
                                    └──────────┘

Diagrama Detalhado — Fluxo qa e evaluate

                    ┌─────────────┐
                    │   Router    │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │ intent=qa │            │ intent=evaluate
              ▼           │            ▼
     ┌─────────────────┐   │   ┌─────────────────────┐
     │ RAG QA Agent    │   │   │ Question Evaluator   │
     └────────┬────────┘   │   └──────────┬──────────┘
              │             │              │
              └─────────────┴──────────────┘
                            │
                            ▼
                      ┌──────────┐
                      │   END    │
                      └──────────┘

Fluxos por Intent

Intent	Fluxo	Agentes
`generate_content`	Planner → [Research?] → Writer (loop) → Question Gen	4–5
`qa`	RAG QA Agent	1
`evaluate`	Question Evaluator	1
`summarize`	Summarizer	1
`expand`	Expand Agent	1
`generate_questions`	Question Generator	1
`general`	RAG QA Agent (fallback)	1

RAG por Agente

Agente	Usa RAG?	Fonte	Notas
Router	Não	—	Só classifica
Content Planner	Sim	Ficheiros do projeto	Retrieval para planejar estrutura
Content Writer	Sim	Ficheiros do projeto	Chunks por secção
Question Generator	Opcional	Doc gerado ou chunks	Contexto para gerar perguntas
Question Evaluator	Opcional	Material de referência	Comparar com solution
RAG QA Agent	Sim (core)	Ficheiros + docs gerados	Retrieval + resposta
Summarizer	Opcional	Doc a resumir	Se doc longo
Research Agent	Não (web)	Web search	Externo
Expand Agent	Sim	Secção + docs	Contexto para expandir

Resumo

#	Agente	Tipo	RAG
1	Router	Core	Não
2	Content Planner	Core	Sim
3	Content Writer	Core	Sim
4	Question Generator	Core	Opcional
5	Question Evaluator	Core	Opcional
6	RAG QA / Chat Agent	Core	Sim (core)
7	Summarizer	Opcional	Opcional
8	Research Agent	Opcional	Não (web)
9	Expand Agent	Opcional	Sim
10	Flashcard Generator	Opcional	Opcional
11	Spaced Repetition Scheduler	Opcional	Não

Zona de prática

Sem perguntas. Clica em Editar para adicionar.