DEV Community

Cover image for Como Transformar TradingAgents em um Fluxo de Trabalho de API de Negociação Real
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Transformar TradingAgents em um Fluxo de Trabalho de API de Negociação Real

TL;DR / Resposta Rápida

A forma mais prática e rápida de integrar o TradingAgents a um fluxo de trabalho de engenharia é rodá-lo como um pacote Python, envolvê-lo em um serviço FastAPI simples e testar essa API usando o Apidog. Assim, você cria um fluxo repetível para acionar análises, inspecionar resultados, documentar o contrato da API e compartilhar a configuração com a equipe.

Experimente o Apidog hoje

Introdução

TradingAgents é um framework de negociação multiagente fácil de admirar no GitHub: possui uma CLI bem feita, suporta múltiplos provedores de modelos e oferece documentação acadêmica sólida. Porém, o desafio real começa quando você quer usá-lo de verdade em um ambiente de engenharia.

Se sua equipe precisa acionar análises por API, monitorar resultados, documentar contratos e entregar esse fluxo para frontend, QA ou plataforma, envolver o TradingAgents em uma API controlada e documentada é essencial. Isso evita dependência de scripts locais e melhora a segurança, auditabilidade e colaboração.

💡 O Apidog encaixa perfeitamente aqui: basta importar o OpenAPI do FastAPI, salvar ambientes, extrair variáveis de respostas, encadear requisições e publicar documentação para a equipe. Baixe o Apidog gratuitamente para acompanhar.

O Que o TradingAgents É e Não É

Antes de começar, entenda o escopo da ferramenta.

Estrutura TradingAgents

TradingAgents é um framework open-source para negociação multiagente. Ele mapeia funções típicas de uma empresa de trading:

  • Analistas de fundamentos, sentimento, notícias e sinais técnicos
  • Pesquisadores otimistas e pessimistas
  • Agente trader
  • Funções de gerenciamento de risco
  • Gestor de portfólio

Fluxo de agentes

O framework utiliza LangGraph, suporta diversos LLMs (OpenAI, Google, Anthropic, xAI, OpenRouter, Ollama), e sua configuração padrão usa, por exemplo:

  • llm_provider = "openai"
  • deep_think_llm = "gpt-5.2"
  • quick_think_llm = "gpt-5-mini"
  • backend_url = "https://api.openai.com/v1"
  • max_debate_rounds = 1

Ou seja, é um framework Python configurável – não uma API SaaS pronta.

O projeto é explícito: é um framework de pesquisa, não consultoria financeira. Mantenha esse aviso visível em qualquer software ou documentação que utilize o TradingAgents.

Passo 1: Instalar o TradingAgents

Clone o repositório e instale as dependências:

git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents
conda create -n tradingagents python=3.13
conda activate tradingagents
pip install .
Enter fullscreen mode Exit fullscreen mode

Para criar o wrapper de API, adicione FastAPI e Uvicorn:

pip install fastapi uvicorn
Enter fullscreen mode Exit fullscreen mode

Configure as variáveis de ambiente (exemplo do .env.example):

OPENAI_API_KEY=
GOOGLE_API_KEY=
ANTHROPIC_API_KEY=
XAI_API_KEY=
OPENROUTER_API_KEY=
Enter fullscreen mode Exit fullscreen mode

Dicas práticas:

  1. Guarde credenciais em variáveis de ambiente ou em um gerenciador de segredos.
  2. Nunca envie segredos pelo corpo da API pública.

Isso simplifica ambientes no Apidog e protege sua aplicação.

Passo 2: Execute o TradingAgents em Python Localmente

Antes de qualquer API, certifique-se de que o TradingAgents funciona no seu ambiente:

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)
Enter fullscreen mode Exit fullscreen mode

Para customizar parâmetros:

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "openai"
config["deep_think_llm"] = "gpt-5.2"
config["quick_think_llm"] = "gpt-5-mini"
config["max_debate_rounds"] = 2

ta = TradingAgentsGraph(debug=True, config=config)
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)
Enter fullscreen mode Exit fullscreen mode

Principais parâmetros a expor futuramente via API:

  • ticker
  • analysis_date
  • llm_provider
  • deep_think_llm
  • quick_think_llm
  • research_depth (profundidade da pesquisa)

Testar localmente evita dores de cabeça na depuração de API.

Passo 3: Escolha Como Usar o TradingAgents

Você pode usar o framework de três formas:

Opção 1: CLI

A CLI é ideal para aprender, experimentar sozinho ou explorar rapidamente. Não use se pretende entregar para frontend, QA ou outros times.

Opção 2: Python Direto

Use scripts Python quando precisar de automação local, notebooks ou controle programático. Ainda não é suficiente para múltiplas equipes.

Opção 3: API Wrapper + Apidog

Exponha o TradingAgents via FastAPI e use o Apidog para testar, documentar e compartilhar o fluxo de trabalho. Ideal para times, frontends, QA e ambientes colaborativos.

Passo 4: Envolva o TradingAgents em um Serviço FastAPI

Utilize o padrão de API baseada em tarefas (task-based):

POST /analyses     -> retorna analysis_id
GET /analyses/{id} -> retorna status/resultados
Enter fullscreen mode Exit fullscreen mode

Contrato mínimo da API

Endpoint Propósito
GET /health Verificação de saúde
POST /analyses Aciona uma execução do TradingAgents
GET /analyses/{analysis_id} Obtém status e resultado da análise

Exemplo de wrapper FastAPI 

from concurrent.futures import ThreadPoolExecutor
from datetime import date, datetime
from uuid import uuid4

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

from tradingagents.default_config import DEFAULT_CONFIG
from tradingagents.graph.trading_graph import TradingAgentsGraph

app = FastAPI(title="TradingAgents API", version="0.1.0")
executor = ThreadPoolExecutor(max_workers=2)
jobs: dict[str, dict] = {}

class AnalysisRequest(BaseModel):
    ticker: str = Field(..., min_length=1, examples=["NVDA"])
    analysis_date: date
    llm_provider: str = Field(default="openai")
    deep_think_llm: str = Field(default="gpt-5.2")
    quick_think_llm: str = Field(default="gpt-5-mini")
    research_depth: int = Field(default=1, ge=1, le=5)

def run_analysis(job_id: str, payload: AnalysisRequest) -> None:
    jobs[job_id]["status"] = "running"
    jobs[job_id]["started_at"] = datetime.utcnow().isoformat()

    config = DEFAULT_CONFIG.copy()
    config["llm_provider"] = payload.llm_provider
    config["deep_think_llm"] = payload.deep_think_llm
    config["quick_think_llm"] = payload.quick_think_llm
    config["max_debate_rounds"] = payload.research_depth
    config["max_risk_discuss_rounds"] = payload.research_depth

    try:
        graph = TradingAgentsGraph(debug=False, config=config)
        _, decision = graph.propagate(
            payload.ticker,
            payload.analysis_date.isoformat(),
        )
        jobs[job_id].update(
            {
                "status": "completed",
                "finished_at": datetime.utcnow().isoformat(),
                "result": decision,
            }
        )
    except Exception as exc:
        jobs[job_id].update(
            {
                "status": "failed",
                "finished_at": datetime.utcnow().isoformat(),
                "error": str(exc),
            }
        )

@app.get("/health")
def health() -> dict:
    return {"status": "ok"}

@app.post("/analyses", status_code=202)
def create_analysis(payload: AnalysisRequest) -> dict:
    analysis_id = str(uuid4())
    jobs[analysis_id] = {
        "status": "queued",
        "ticker": payload.ticker,
        "analysis_date": payload.analysis_date.isoformat(),
        "created_at": datetime.utcnow().isoformat(),
    }
    executor.submit(run_analysis, analysis_id, payload)
    return {"analysis_id": analysis_id, "status": "queued"}

@app.get("/analyses/{analysis_id}")
def get_analysis(analysis_id: str) -> dict:
    job = jobs.get(analysis_id)
    if not job:
        raise HTTPException(status_code=404, detail="Analysis not found")
    return job
Enter fullscreen mode Exit fullscreen mode

Inicie o serviço:

uvicorn app:app --reload
Enter fullscreen mode Exit fullscreen mode

Endpoints disponíveis:

  • http://localhost:8000/docs
  • http://localhost:8000/openapi.json (para importar no Apidog)

Passo 5: Use o TradingAgents Pela API

Acionar uma análise

Envie um POST /analyses com:

{
  "ticker": "NVDA",
  "analysis_date": "2026-03-26",
  "llm_provider": "openai",
  "deep_think_llm": "gpt-5.2",
  "quick_think_llm": "gpt-5-mini",
  "research_depth": 2
}
Enter fullscreen mode Exit fullscreen mode

Resposta esperada:

{
  "analysis_id": "88f9f0f5-7315-4c73-8ed5-d0a71f613d31",
  "status": "queued"
}
Enter fullscreen mode Exit fullscreen mode

Polling do resultado

Use GET /analyses/{analysis_id} para acompanhar o progresso:

{
  "status": "running",
  "ticker": "NVDA",
  "analysis_date": "2026-03-26",
  "created_at": "2026-03-26T06:00:00.000000",
  "started_at": "2026-03-26T06:00:01.000000"
}
Enter fullscreen mode Exit fullscreen mode

Ao finalizar:

{
  "status": "completed",
  "ticker": "NVDA",
  "analysis_date": "2026-03-26",
  "result": {
    "decision": "hold"
  }
}
Enter fullscreen mode Exit fullscreen mode

Em caso de erro, retorne "status": "failed" e mensagem clara.

Passo 6: Importe a API no Apidog

No Apidog, importe o esquema OpenAPI:

http://localhost:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Vantagens:

  • Documentação sempre alinhada ao código
  • Parâmetros e exemplos prontos para uso
  • Colegas não precisam reconstruir a coleção manualmente
  • Facilita design, testes, ambientes e documentação centralizada

Passo 7: Crie um Ambiente no Apidog

Configure variáveis como:

base_url = http://localhost:8000
analysis_id =
Enter fullscreen mode Exit fullscreen mode

Se precisar de autenticação:

internal_api_key = sua-chave-dev-local
Enter fullscreen mode Exit fullscreen mode

Isso permite alternar facilmente entre ambientes (local, staging, produção) e reutilizar requisições.

Passo 8: Teste o Fluxo Completo no Apidog

Requisição 1: Criar análise

  • Método: POST
  • URL: {{base_url}}/analyses
  • Corpo: 
{
  "ticker": "NVDA",
  "analysis_date": "2026-03-26",
  "llm_provider": "openai",
  "deep_think_llm": "gpt-5.2",
  "quick_think_llm": "gpt-5-mini",
  "research_depth": 2
}
Enter fullscreen mode Exit fullscreen mode

Script de teste:

pm.test("Status é 202", function () {
    pm.response.to.have.status(202);
});

const data = pm.response.json();
pm.expect(data.analysis_id).to.exist;
pm.environment.set("analysis_id", data.analysis_id);
Enter fullscreen mode Exit fullscreen mode

Requisição 2: Polling

  • Método: GET
  • URL: {{base_url}}/analyses/{{analysis_id}}

Teste de status válido:

pm.test("Análise tem um status válido", function () {
    const data = pm.response.json();
    pm.expect(["queued", "running", "completed", "failed"]).to.include(data.status);
});
Enter fullscreen mode Exit fullscreen mode

Teste de resultado ao completar:

pm.test("Tarefas concluídas incluem um resultado", function () {
    const data = pm.response.json();
    if (data.status === "completed") {
        pm.expect(data.result).to.exist;
    }
});
Enter fullscreen mode Exit fullscreen mode

Encadeie as requisições em cenários

Monte um cenário no Apidog:

  1. Envia POST /analyses
  2. Armazena analysis_id
  3. Aguarda alguns segundos
  4. Executa GET /analyses/{{analysis_id}}

Assim, QA e devs validam todo o ciclo de vida, não apenas respostas pontuais.

Passo 9: Publique Documentação Interna para a Equipe

Depois dos testes, publique docs no Apidog explicando:

  • Provedores permitidos
  • Significado do research_depth
  • Possíveis status de tarefa
  • Duração média das execuções
  • Quais erros podem ser reprocessados
  • Aviso de uso “apenas para pesquisa”

Transforme o TradingAgents em um workflow de API documentado e compartilhado.

Erros Comuns ao Usar o TradingAgents Desta Forma

Tratar o framework como uma API hospedada

TradingAgents não é uma SaaS pronta. Projete o contrato de API que sua equipe precisa.

Passar segredos no corpo das requisições

Sempre use gerenciamento de ambiente para chaves. Nunca exponha segredos em exemplos, frontend ou screenshots.

Retornar resposta síncrona longa

Evite endpoints que bloqueiam por muito tempo. Use APIs baseadas em tarefas (job/task pattern).

Expor excesso de parâmetros de configuração

Comece expondo só o essencial. Expanda conforme o caso de uso amadurecer.

Manter resultados apenas em memória

O exemplo usa dicionário em memória. Em produção, armazene tarefas em Redis, Postgres, etc.

Esconder o aviso de pesquisa

Seja claro: TradingAgents é para pesquisa, não para decisões financeiras automáticas.

Conclusão

A melhor forma de usar o TradingAgents depende do seu objetivo. Para fluxos colaborativos, envolva-o em uma API, teste e documente tudo com o Apidog.

Resumo do caminho mais prático:

  1. Instale o TradingAgents.
  2. Teste o TradingAgentsGraph localmente.
  3. Crie endpoints POST /analyses e GET /analyses/{id}.
  4. Importe o OpenAPI no Apidog.
  5. Construa cenários ponta a ponta e compartilhe com a equipe.

Esse fluxo é muito mais sustentável do que scripts isolados ou conhecimento tribal de terminal.

FAQ

Como usar o TradingAgents pela primeira vez?

Instale o repositório, configure as variáveis de ambiente do provedor e rode o exemplo Python com TradingAgentsGraph. Só depois avalie se precisa de uma API.

O TradingAgents vem com uma API REST oficial?

Não. O projeto fornece CLI e pacote Python. A FastAPI é necessária para equipes que desejam API.

Qual a melhor forma de usar o TradingAgents em um frontend?

Não chame o Python direto do frontend. Exponha via API backend que retorna um analysis_id e permita polling pelo resultado.

Por que usar o Apidog com o TradingAgents?

O Apidog permite importar o OpenAPI, salvar ambientes, adicionar exemplos, scripts de teste, asserções e documentar o fluxo de trabalho para toda a equipe, sem depender de engenharia reversa.

Quais configurações do TradingAgents devo expor na API?

Comece com: ticker, data de análise, provedor, modelos e profundidade de pesquisa. Expanda a API conforme a necessidade real.

Posso manter o estado da tarefa em memória como no exemplo?

Apenas para prototipagem. Em produção, use um backend durável (Redis, Postgres etc).

O TradingAgents é adequado para decisões financeiras em tempo real?

Não. O projeto é para pesquisa e experimentação, não para decisões finais de investimento. Se precisar disso, adicione controles e validação próprios.

Top comments (0)