TP3.5: Trilha Avancada Opcional - Agentes, LLMs e Tool Calling

Extensao experimental do Dossie de Integracao

Desafios opcionais, nao avaliados no nucleo do TP3, para equipes que desejam experimentar orquestracao baseada em LLM.

Natureza da trilha

O TP3.5 e uma trilha opcional e experimental. Ela nao adiciona requisitos ao TP3, nao substitui itens da rubrica de 20 pontos e nao deve bloquear a entrega principal. A equipe so deve inicia-la depois de o nucleo do TP3 estar executavel: contratos integrados, resposta RAG citada, abstencao, observabilidade e seis casos de avaliacao.

O objetivo e investigar se uma LLM ou um orquestrador baseado em ferramentas melhora a experiencia do assistente sem enfraquecer rastreabilidade, seguranca, controle de custos ou qualidade da evidencia.

Pre-requisitos

Antes de qualquer desafio, a equipe deve ter:

1. Uma versao marcada do nucleo TP3 e testes passando.
2. Um caminho deterministico de fallback que continue funcionando sem LLM, agente ou ferramenta externa.
3. Contratos TP1/TP2 documentados e mocks para execucao local.
4. Politica de abstencao e verificacao de citacoes ativas no caminho experimental.
5. Registro de custo, latencia e erros por requisicao experimental.

Mantenham codigo, configuracao e resultados desta trilha em diretorio, perfil ou flag claramente separados, por exemplo experimental/ ou --mode advanced. Nao transformem o agente em dependencia obrigatoria da demo do TP3.

Regras de seguranca e custo

• Nunca enviem chaves, tokens, dados pessoais, codigo privado ou corpus nao autorizado a provedores externos.
• A LLM nao recebe permissao para executar comandos de sistema, gravar arquivos arbitrarios, acessar rede livremente ou chamar URLs escolhidas pelo proprio modelo.
• Usem uma lista fechada de ferramentas: somente consultas de leitura aos adaptadores TP1 e TP2 e funcoes locais de verificacao de citacao.
• Definam limite de requisicoes, limite de tokens/custo e timeout por demonstracao. Ao atingir um limite, encerrem a tentativa e retornem ao fluxo deterministico.
• Registrem modelo, versao, parametros, estimativa de custo, latencia, falhas e decisao de fallback. Nunca registrem segredo em logs.
• Toda resposta final continua sujeita a verificacao de fontes: nenhuma citacao pode ser aceita se nao vier da recuperacao da requisicao corrente.

Nivel 1: LLM fundamentada

Use uma LLM somente para redigir a resposta final a partir de skills e trechos ja recuperados pelo TP1/TP2. A sequencia de chamadas permanece deterministica e controlada pelo programa.

Entregas experimentais:

• Instrucao/prompt versionado que proiba usar conhecimento externo e exija citacoes [E#].
• Validador que rejeite citacoes inexistentes ou resposta sem evidencia quando a politica exigir abstencao.
• Comparacao com a resposta deterministica em pelo menos tres dos seis casos do TP3.
• Tabela de qualidade humana, latencia e custo estimado.

Nivel 2: Tool calling controlado

Permita que a LLM escolha, dentro de um fluxo limitado, entre consultar_skills, buscar_evidencias, pedir_esclarecimento e responder_com_evidencia. As ferramentas devem ser wrappers tipados dos contratos existentes; o modelo nao escolhe URLs, parametros fora do schema ou comandos.

Entregas experimentais:

• Especificacao das ferramentas, seus schemas de entrada/saida e limites de chamada.
• Limite pequeno e fixo de passos por requisicao, com encerramento seguro e fallback deterministico.
• Log da sequencia de chamadas, sem expor cadeia de raciocinio interna.
• Testes para chamada invalida, repeticao excessiva, timeout e tentativa de resposta sem evidencia.
• Comparacao entre Nivel 1 e Nivel 2 em pelo menos tres casos, incluindo um ambiguo ou fora do dominio.

Nivel 3: Orquestracao avaliada

Implemente um orquestrador com estado explicito que possa planejar, consultar ferramentas permitidas, verificar cobertura de evidencia e decidir responder, pedir esclarecimento ou abster-se. A avaliacao deve medir o efeito da orquestracao, e nao apenas exibir uma demo.

Entregas experimentais:

• Diagrama de estados e regras de transicao auditaveis.
• Conjunto adicional de pelo menos seis consultas, separado do conjunto principal do TP3.
• Comparacao Nivel 2 versus Nivel 3 em taxa de citacoes validas, abstencoes apropriadas, latencia, numero de chamadas e custo.
• Analise de dois comportamentos indesejados e dos guardrails que os contiveram.
• Video curto ou roteiro reproduzivel da execucao experimental.

Formato dos resultados

Documentem a trilha em uma secao opcional do README.md ou em experimental/README.md. Para cada nivel concluido, indiquem objetivo, versao do modelo/provedor, configuracao, limites, dados usados, resultados, custos, falhas e como reproduzir ou desabilitar a extensao.

O resultado valido desta trilha pode ser negativo: demonstrar que o mecanismo aumentou custo, latencia ou respostas sem evidencia, com experimento reproduzivel, e uma conclusao de nao adota-lo no nucleo e uma contribuicao tecnica honesta.