TradingAgents: Framework Open Source de LLM para Negociação

A maioria dos frameworks LLM multi-agente promete mais do que entrega. TradingAgents é uma das raras exceções: um projeto open source da Tauric Research, acompanhado de um artigo no arXiv, atualmente na versão 0.2.4. Ele implementa uma decomposição clara de papéis: analistas de fundamentos, sentimento, notícias e análise técnica alimentam um debate Bull/Bear; depois um Trader gera um plano; um comitê de Gerenciamento de Risco revisa; e a decisão final é registrada para auditoria.

Experimente o Apidog hoje

Este guia mostra o que o TradingAgents faz na prática, o que mudou na v0.2.4, como executar uma análise mínima e como testar as camadas de LLM e dados de mercado com Apidog. Se você já trabalha com contratos de agentes, o guia agents.md para equipes de API complementa bem este fluxo.

TL;DR

• TradingAgents é um framework LLM multi-agente para pesquisa de negociação, publicado pela Tauric Research e descrito no arXiv 2412.20138.
• Ele divide o fluxo em agentes especialistas: Fundamentos, Sentimento, Notícias, Técnico, Pesquisadores Bull/Bear, Trader e Gerenciamento de Risco.
• A v0.2.4 adiciona saída estruturada, retomada por checkpoint do LangGraph, logs persistentes de decisão e suporte a provedores como DeepSeek, Qwen, GLM e Azure OpenAI.
• O framework funciona com endpoints LLM compatíveis com OpenAI, permitindo trocar entre modelos hospedados, locais e auto-hospedados.
• Use Apidog para simular APIs de dados de mercado, reproduzir tráfego de provedores LLM e validar respostas estruturadas antes de escalar execuções.
• Baixe o Apidog para integrar esses testes ao seu fluxo local ou CI.

O que o TradingAgents realmente é

TradingAgents é um pacote Python com CLI que modela uma mesa de pesquisa financeira usando agentes LLM especializados. Cada agente recebe:

• uma função clara;
• um prompt específico;
• um conjunto limitado de ferramentas;
• uma etapa definida dentro do grafo de execução.

O fluxo geral é:

1. coletar dados;
2. gerar relatórios por especialista;
3. debater cenários Bull/Bear;
4. sintetizar a recomendação;
5. gerar plano de negociação;
6. revisar risco;
7. registrar a decisão.

O README deixa claro que o projeto é código de pesquisa, não conselho financeiro. Esse ponto importa: o objetivo é estudar colaboração multi-agente, não colocar um bot para operar dinheiro real sem validação.

A parte mais útil para desenvolvedores é a separação de responsabilidades:

• Analista de Fundamentos: avalia finanças da empresa.
• Analista de Sentimento: analisa sinais sociais.
• Analista de Notícias: acompanha eventos e indicadores macroeconômicos.
• Analista Técnico: calcula indicadores como MACD e RSI.
• Pesquisador Bull: constrói a tese otimista.
• Pesquisador Bear: constrói a tese pessimista.
• Trader: lê os relatórios e produz um plano.
• Gerenciamento de Risco: contesta e valida o plano.
• Gerente de Portfólio: aprova ou envia para revisão.

Esse padrão é reutilizável em outros domínios: especialistas, debate, decisão e auditoria.

O que a v0.2.4 entregou

A versão 0.2.4 é relevante porque adiciona recursos que aproximam o projeto de um ambiente mais testável e observável.

1. Saídas estruturadas

O Gerente de Pesquisa, o Trader e o Gerente de Portfólio agora retornam saídas estruturadas usando a API de Respostas da OpenAI ou o uso de ferramentas da Anthropic.

Na prática, isso reduz parsing frágil de texto livre e permite validar JSON tipado no pipeline.

Exemplo de validação esperada:

{
  "decision": "buy",
  "confidence": 0.72,
  "rationale": "Resumo da tese usada pelo Trader",
  "risks": ["volatilidade", "resultado trimestral"]
}

2. Checkpoints com LangGraph

Execuções longas podem pausar e retomar a partir de um checkpoint salvo.

Isso é útil quando:

• uma API de mercado retorna 429;
• o provedor LLM falha temporariamente;
• uma execução multiagente consome muitos minutos;
• você quer retomar sem repetir todas as chamadas anteriores.

3. Log persistente de decisões

Cada decisão do Trader é gravada em SQLite com entradas, raciocínio e timestamp. Isso cria uma trilha de auditoria para:

• revisar decisões;
• comparar provedores LLM;
• medir regressões;
• reproduzir execuções antigas.

4. Suporte a múltiplos provedores

A v0.2.4 adicionou suporte a DeepSeek, Qwen, GLM e Azure OpenAI, além de OpenAI, Anthropic, Gemini e Grok.

Se você quer testar custo menor por raciocínio, pode usar DeepSeek V4 por endpoint compatível com OpenAI. Se precisa de contexto longo ou visão, pode alternar para Gemini.

5. Docker e correções Windows

O projeto também adicionou Dockerfile e corrigiu um problema de codificação UTF-8 no Windows. Não é chamativo, mas ajuda bastante em execução local e CI.

Arquitetura do agente em detalhes

Uma execução completa segue este pipeline:

1. A CLI recebe um ticker e uma data.
2. A equipe de analistas busca dados separadamente.
3. Cada analista escreve um relatório.
4. O Pesquisador Bull escreve uma tese de alta.
5. O Pesquisador Bear escreve uma tese de baixa.
6. Os dois pesquisadores debatem.
7. O Gerente de Pesquisa sintetiza a recomendação.
8. O Trader gera um plano de negociação.
9. Os agentes de risco revisam o plano.
10. O Gerente de Portfólio aprova ou solicita revisão.
11. A decisão final é registrada em SQLite.

O maior custo de LLM normalmente aparece nas fases de debate:

• debate Bull/Bear;
• revisão de risco;
• síntese final.

Modelos menores podem gerar debates repetitivos ou rasos. Modelos com melhor capacidade de raciocínio tendem a produzir argumentos mais úteis e estruturados.

Como executar o TradingAgents localmente

Um fluxo mínimo se parece com isto:

git clone https://github.com/TauricResearch/TradingAgents
cd TradingAgents
pip install -r requirements.txt

export OPENAI_API_KEY="sk-..."
export FINNHUB_API_KEY="..."

python -m tradingagents.cli \
  --ticker AAPL \
  --date 2026-04-30 \
  --models gpt-5.5 \
  --rounds 2

Duas rodadas de debate são um bom mínimo para observar o comportamento multi-agente. A saída é gravada em:

tradingagents/results/

Normalmente você verá:

• JSON com dados da execução;
• resumo em Markdown;
• logs de decisão;
• artefatos intermediários dos agentes.

Como alternar para DeepSeek

Para testar DeepSeek V4 Pro nas funções que exigem mais raciocínio:

export DEEPSEEK_API_KEY="sk-..."

python -m tradingagents.cli \
  --ticker AAPL \
  --date 2026-04-30 \
  --models deepseek-v4-pro \
  --provider deepseek \
  --rounds 2

O mesmo padrão se aplica a Qwen, GLM ou modelos locais servidos por Ollama, vLLM ou LM Studio, desde que exponham endpoint compatível com OpenAI.

Para modelos locais, veja também a publicação sobre os melhores LLMs locais de 2026.

Por que testar a camada LLM com uma ferramenta de API

Ao rodar TradingAgents, duas superfícies quebram com frequência:

1. APIs de dados de mercado.
2. APIs de provedores LLM.

No lado dos dados de mercado, problemas comuns incluem:

• limites de taxa inconsistentes;
• campos renomeados;
• respostas incompletas;
• diferenças entre dias úteis e fins de semana;
• fornecedores com formatos ligeiramente diferentes.

Exemplo de quebra silenciosa:

{
  "regularMarketTime": 1714420800
}

vira:

{
  "regular_market_time": 1714420800
}

Se seu parser espera apenas regularMarketTime, o agente pode falhar ou inferir dados incorretos.

No lado dos LLMs, os problemas são diferentes:

• custo variável por modo de raciocínio;
• diferenças entre APIs compatíveis com OpenAI;
• blocos de conteúdo específicos da Anthropic;
• JSON malformado;
• uso de ferramentas com estrutura inesperada.

O que você precisa é uma coleção reproduzível de requisições com asserções. É aí que Apidog entra. O mesmo padrão aparece no manual de teste de servidor MCP.

Simulando APIs de dados de mercado no Apidog

Use mocks para tornar seus testes determinísticos.

Passo 1: defina os endpoints upstream

No Apidog, crie um projeto e adicione os endpoints usados pelo TradingAgents, por exemplo:

• Yahoo Finance;
• FinnHub;
• Polygon;
• OpenBB.

Salve cada endpoint como uma requisição com exemplos reais de resposta.

Exemplo de estrutura esperada:

{
  "symbol": "AAPL",
  "regularMarketPrice": 182.52,
  "regularMarketTime": 1714420800,
  "currency": "USD"
}

Passo 2: ative o servidor mock

No Apidog, habilite o mock server para retornar as respostas salvas.

Depois, aponte a configuração do TradingAgents para a URL mock em vez do fornecedor real.

Resultado:

• os testes deixam de depender do Yahoo, FinnHub ou Polygon;
• os dados ficam estáveis;
• execuções locais e no CI ficam mais rápidas;
• você evita consumir limite de taxa.

Passo 3: monitore drift de contrato

Uma vez por semana, rode os endpoints reais e compare com as fixtures salvas.

Procure por:

• campos removidos;
• campos renomeados;
• tipos alterados;
• arrays vazios;
• respostas com erro inesperado.

Esse é o mesmo princípio usado em desenvolvimento de API contract-first.

Testando a camada do provedor LLM

Antes de rodar lotes grandes, teste três aspectos.

1. Custo por função

Execute um ticker e capture o consumo por agente:

• Analista de Fundamentos;
• Analista de Sentimento;
• Analista de Notícias;
• Analista Técnico;
• Debate Bull/Bear;
• Trader;
• Gerenciamento de Risco.

O debate Bull/Bear costuma custar mais do que os analistas. Se estiver muito barato, talvez o modelo esteja encurtando a resposta ou ignorando parte do raciocínio.

Use o histórico de requisições do Apidog para comparar chamadas e tamanhos de payload.

2. Formato de saída

Os agentes com saída estruturada devem retornar JSON válido.

Adicione asserções JSONPath como:

$.decision
$.confidence
$.rationale
$.risks

E valide tipos:

$.confidence deve ser number
$.risks deve ser array
$.decision deve ser string

Esse teste evita que uma regressão de prompt quebre o código downstream.

3. Paridade entre provedores

Ao trocar OpenAI por DeepSeek, Qwen ou outro provedor, não espere respostas idênticas. Mas, em um lote maior, as conclusões devem ser comparáveis.

Um fluxo prático:

1. Escolha 50 tickers.
2. Rode com OpenAI.
3. Rode com DeepSeek.
4. Compare os logs SQLite.
5. Meça divergência por decisão, confiança e justificativa.

Use o guia da API DeepSeek V4 para o formato de requisição e o guia da API GPT-5.5 para o lado OpenAI.

Checklist de implementação

Antes de confiar em qualquer resultado, valide:

• [ ] O ticker executa com dados mockados.
• [ ] O cache de dados de mercado está ativo.
• [ ] O provedor LLM retorna JSON válido nos agentes estruturados.
• [ ] O log SQLite registra a decisão final.
• [ ] O custo por execução é registrado.
• [ ] A execução pode ser retomada por checkpoint.
• [ ] O mesmo ticker foi testado em pelo menos dois provedores.
• [ ] O resultado foi tratado como hipótese, não como recomendação financeira.

Armadilhas comuns

Usar um modelo pequeno demais

Modelos locais pequenos podem entrar em loops ou produzir argumentos repetitivos no debate Bull/Bear.

O framework se beneficia de modelos com capacidade intermediária ou alta de raciocínio. DeepSeek V4 Flash, Qwen 3.6 32B, GPT-5.5 e Claude 4.5 são exemplos citados como pisos mais realistas.

Ignorar cache de dados

Cada analista pode chamar a camada de dados separadamente. Sem cache, uma execução simples pode gerar várias chamadas aos fornecedores.

Ative cache para:

• reduzir custo;
• evitar rate limit;
• melhorar reprodutibilidade;
• acelerar testes.

Tratar como bot de negociação

TradingAgents é código de pesquisa. Backtests são sensíveis a:

• modelo usado;
• prompt;
• número de rodadas;
• qualidade dos dados;
• data escolhida;
• seed e variação do provedor.

Use as saídas como hipóteses para análise, não como ordens automáticas.

Não registrar custo de tokens

Uma execução de ticker pode variar bastante em custo dependendo do modelo e do número de rodadas.

Registre:

• tokens de entrada;
• tokens de saída;
• custo por agente;
• custo total;
• tempo de execução.

Um loop na fase de debate pode gerar custo real em poucos minutos.

Fixar um único provedor

A v0.2.4 facilita alternar provedores. Use isso para testar:

• custo;
• latência;
• qualidade;
• robustez do JSON;
• consistência das decisões.

Onde o Apidog entra no ciclo de desenvolvimento

Há três pontos práticos para usar Apidog com TradingAgents.

1. Design da superfície de dados

Antes de conectar fornecedores reais, modele cada endpoint no Apidog com exemplos de resposta.

Isso força você a responder:

• quais campos o framework realmente usa?
• quais campos são opcionais?
• quais tipos precisam ser estáveis?
• quais endpoints são redundantes?

Muitas equipes descobrem que pagam por dados que quase não consomem.

2. CI local com mocks

Substitua fornecedores reais por mocks durante testes unitários.

Benefícios:

• testes mais rápidos;
• sem dependência de mercado aberto;
• sem rate limit;
• sem instabilidade externa;
• fixtures versionadas.

Esse padrão também é descrito em testes de API sem Postman.

3. Detecção de regressão

Rode verificações semanais contra endpoints reais e compare com fixtures salvas.

Quando um fornecedor altera o contrato, você descobre antes que os agentes passem a gerar conclusões com dados errados.

Por que isso importa além da negociação

TradingAgents é útil mesmo que você não esteja construindo nada financeiro. O padrão se transfere para workflows multi-agente como:

• triagem de suporte;
• revisão de código;
• revisão de conformidade;
• análise de incidentes;
• resumo de pesquisa;
• análise de risco;
• revisão jurídica interna.

A estrutura é sempre parecida:

1. agentes especialistas produzem relatórios;
2. agentes com posições diferentes debatem;
3. um sintetizador consolida;
4. um decisor produz saída estruturada;
5. um log persistente registra tudo.

Esse padrão é testável, auditável e mais fácil de depurar do que um único prompt gigante.

Casos de uso reais

• Um estudante de pesquisa quantitativa compara DeepSeek V4, GPT-5.5 e Claude 4.5 na mesma cesta de 30 tickers. O Apidog captura requisições e respostas para tornar a comparação reproduzível.
• Um engenheiro fintech reutiliza o padrão multi-agente para revisão de código: agentes verificam segurança, desempenho e nomenclatura; um sintetizador escreve o comentário do PR.
• Um desenvolvedor solo roda TradingAgents todas as noites em 10 tickers e grava decisões em Postgres para inspeção posterior. Nos testes de fim de semana, usa mocks do Apidog no lugar dos fornecedores reais.

Conclusão

TradingAgents é um exemplo funcional de como construir um sistema LLM multi-agente que produz decisões estruturadas, não apenas chat. A v0.2.4 adiciona recursos importantes: saídas estruturadas, checkpoints, logs persistentes e múltiplos provedores.

Mas a parte crítica é testar as camadas externas:

• dados de mercado;
• provedores LLM;
• contratos JSON;
• custo por execução;
• paridade entre modelos.

Cinco pontos principais:

• TradingAgents decompõe negociação em agentes especialistas com funções claras.
• A v0.2.4 adiciona saídas estruturadas, checkpoints LangGraph e novos provedores.
• Mocks no Apidog tornam execuções de teste determinísticas.
• Testes de contrato evitam que mudanças em fornecedores quebrem agentes silenciosamente.
• O padrão especialistas → debate → decisão → log se aplica a muitos workflows além de negociação.

Próximo passo: clone o repositório, execute um ticker com seu LLM preferido e direcione as chamadas upstream para um mock server do Apidog. Em menos de uma hora você terá uma boa noção se o framework se encaixa no seu fluxo.

Perguntas Frequentes

É seguro usar o TradingAgents com dinheiro real?

O repositório afirma que é código de pesquisa e não conselho financeiro. Trate a saída como hipótese. Qualquer uso com corretora ativa é responsabilidade de quem opera.

Qual provedor LLM oferece melhor equilíbrio entre custo e qualidade?

Para muitas cargas de trabalho no início de 2026, DeepSeek V4 Flash com modo de pensamento oferece custo competitivo e boa qualidade no debate Bull/Bear. Veja o guia da API DeepSeek V4 para detalhes de requisição.

Posso executar o TradingAgents em modelos locais?

Sim. A v0.2.0 adicionou suporte a múltiplos provedores, e ferramentas como Ollama, vLLM e LM Studio podem expor endpoints compatíveis com OpenAI. Veja a publicação sobre os melhores LLMs locais de 2026.

Como simular APIs de dados de mercado?

Defina cada endpoint no Apidog, ative o mock server e aponte a configuração do TradingAgents para a URL mock. O padrão também aparece em ferramentas de teste de API para engenheiros de QA.

Qual é o hardware mínimo?

Se você usa LLMs hospedados, qualquer laptop com Python 3.10+ deve ser suficiente. Para modelos locais, o requisito depende do modelo escolhido. Modelos menores rodam em hardware mais simples, mas tendem a reduzir a qualidade do debate e da decisão.

Ele suporta simulação após o horário de negociação e nos fins de semana?

Sim, desde que os fornecedores retornem dados históricos para a data escolhida. Trading ao vivo é um problema diferente e não é o objetivo declarado do framework.

Como ele se compara a outros frameworks multi-agente?

TradingAgents é específico para o domínio de negociação. CrewAI, AutoGen e LangGraph são mais gerais. Se você quer aprender um padrão multi-agente concreto, TradingAgents é uma boa referência. Se quer construir um sistema genérico, comece pelo LangGraph e adapte o padrão.