Blog

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

Ashley Innocent

Ashley Innocent

26 março 2026

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

TL;DR / Resposta Rápida

A maneira prática mais rápida de usar o TradingAgents é executá-lo como um pacote Python, envolvê-lo em um pequeno serviço FastAPI e, em seguida, testar esse serviço no Apidog. Isso oferece um fluxo de trabalho repetível para acionar análises, verificar resultados, documentar o contrato de solicitação e compartilhar a configuração com sua equipe.

Introdução

O TradingAgents é fácil de admirar de fora. O repositório do GitHub mostra um fluxo de trabalho de negociação multiagente, uma CLI polida, suporte para vários provedores de modelos e um artigo de pesquisa que explica o design da estrutura. A parte mais difícil começa quando você tenta usá-lo em um fluxo de trabalho de engenharia real.

A maioria das equipes não quer um repositório que apenas um desenvolvedor possa executar localmente. Elas querem uma maneira repetível de acionar análises, passar um ticker e uma data, retornar um ID de trabalho, inspecionar o resultado posteriormente e entregar esse fluxo de trabalho para colegas de frontend, QA ou plataforma sem transformar cada pergunta em uma sessão de depuração de Python. E como qualquer sistema de pesquisa de negociação será eventualmente usado para informar decisões de dinheiro real, é ainda mais importante envolver o TradingAgents em uma API controlada e documentada, em vez de deixá-lo como um script único no laptop de alguém.

💡
O Apidog se encaixa naturalmente neste fluxo de trabalho. Você pode importar o esquema OpenAPI do FastAPI, salvar ambientes para implantações locais e remotas, extrair variáveis de respostas, encadear solicitações de pesquisa em um cenário e publicar documentação para o resto da sua equipe. Baixe o Apidog gratuitamente para acompanhar.
botão

O Que o TradingAgents É e Não É

Antes de começar a programar, é útil definir a ferramenta com precisão.

TradingAgents é um framework de negociação multiagente de código aberto. O repositório descreve um conjunto de funções especializadas que espelham a estrutura de uma empresa de trading:

O repositório também afirma que o framework é construído com LangGraph e suporta múltiplos provedores de modelos, incluindo OpenAI, Google, Anthropic, xAI, OpenRouter e Ollama. Na configuração padrão pública, o projeto atualmente usa valores como:

Isso importa porque informa com o que você realmente está trabalhando: um framework Python configurável, não uma API SaaS pronta para uso.

O repositório também é cuidadoso quanto ao escopo. O TradingAgents é apresentado como um framework de pesquisa, não como aconselhamento financeiro. Se você o usar internamente ou construir software em torno dele, mantenha essa delimitação visível em sua documentação e experiência do usuário.

Passo 1: Instalar o TradingAgents

Comece com a configuração do próprio repositório:

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

Se você também quiser construir o wrapper da API deste tutorial, adicione FastAPI e Uvicorn:

pip install fastapi uvicorn

O repositório do TradingAgents também inclui um .env.example com variáveis de provedor, tais como:

OPENAI_API_KEY=
GOOGLE_API_KEY=
ANTHROPIC_API_KEY=
XAI_API_KEY=
OPENROUTER_API_KEY=

Dependendo das suas escolhas de modelo e dados, você também pode precisar de outras credenciais de fornecedores, como Alpha Vantage.

Duas regras práticas importam aqui:

  1. Mantenha as credenciais em variáveis de ambiente ou em um gerenciador de segredos.
  2. Não passe segredos do provedor através do corpo da solicitação da sua API pública posteriormente.

Essa separação tornará seus ambientes Apidog mais limpos e seu modelo de segurança muito mais seguro.

Passo 2: Executar o TradingAgents em Python Primeiro

Antes de construir qualquer wrapper de API, prove que o framework principal funciona no seu ambiente.

O README mostra um padrão de uso mínimo de Python:

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)

Este é o primeiro ponto de verificação correto porque responde à única pergunta que importa desde o início: sua máquina, configuração de modelo e dependências podem realmente executar uma rodada do TradingAgents?

Se isso funcionar, você pode passar para a configuração controlada. O repositório também mostra que você pode sobrescrever a configuração padrão:

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)

Esse segundo exemplo é mais importante do que parece. Ele diz quais parâmetros vale a pena expor em uma API posteriormente:

Se você pular esta fase Python local e pular diretamente para HTTP, você torna a depuração mais difícil do que precisa ser.

Passo 3: Decida Como Você Quer Usar o TradingAgents

Neste ponto, você tem três maneiras comuns de usar o framework.

Opção 1: Apenas CLI

O repositório inclui uma CLI interativa onde você pode escolher ticker, data, provedor e profundidade da pesquisa. Esta é uma boa maneira de explorar o projeto rapidamente.

Use isso quando:

Não pare aqui se seu próximo passo for um frontend, ferramenta de administração, serviço compartilhado ou fluxo de trabalho de QA.

Opção 2: Apenas Python

Chamar TradingAgentsGraph diretamente do Python é melhor do que a CLI quando você precisa de orquestração personalizada ou scripts locais.

Use isso quando:

Isso ainda é insuficiente quando várias equipes precisam consumir o fluxo de trabalho.

Opção 3: Wrapper de API mais Apidog

Esta é a configuração de equipe mais útil. Você mantém o TradingAgents como motor de execução, o expõe através de um pequeno serviço FastAPI e usa o Apidog para testar e documentar o contrato.

Use isso quando:

Para a maioria das equipes, este é o ponto onde "como usar o TradingAgents" se torna uma resposta de implementação real em vez de apenas uma demonstração local.

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

O padrão mais limpo para um primeiro wrapper é uma API baseada em tarefas.

Por que baseada em tarefas? Porque uma análise multiagente pode demorar o suficiente para que manter uma solicitação aberta seja complicado para os clientes. Um padrão melhor é:

POST /analyses -> retorna analysis_id
GET /analyses/{id} -> retorna queued, running, completed, ou failed

Essa estrutura é mais fácil para navegadores, mais fácil para o QA e mais fácil de documentar no Apidog.

Criar o contrato da API

Um contrato mínimo se parece com isto:

EndpointPropósito
GET /healthverificação básica de saúde
POST /analysesacionar uma execução do TradingAgents
GET /analyses/{analysis_id}obter status da tarefa e resultado final

Construir o wrapper

Aqui está um exemplo compacto de 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

Iniciar o serviço:

uvicorn app:app --reload

Uma vez que o servidor esteja em funcionamento, o FastAPI irá expor:

Essa segunda URL é especialmente útil porque o Apidog pode importá-la diretamente.

Passo 5: Usar o TradingAgents Através da API

Agora você está pronto para usar o TradingAgents de uma forma que seja estável e repetível.

Acionar uma análise

Envie uma solicitação POST /analyses com um corpo como este:

{
 "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
}

A resposta deve ser rápida e pequena:

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

Isso é exatamente o que você quer. Seu cliente não precisa do relatório final imediatamente. Ele precisa de um identificador estável para a execução.

Pesquisar (Polling) pelo resultado

Use GET /analyses/{analysis_id} para verificar 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"
}

Quando o fluxo de trabalho terminar, a resposta pode incluir a decisão final:

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

Se algo falhar, retorne um estado de "falha" claro e uma mensagem de erro, em vez de deixar os clientes adivinhando.

Passo 6: Importar a API para o Apidog

É aqui que o fluxo de trabalho se torna muito mais fácil de manter.

No Apidog, importe o esquema OpenAPI de:

http://localhost:8000/openapi.json

Após a importação, você deve ver seus endpoints com a estrutura de solicitação e resposta já configurada.

Isso lhe dá algumas vantagens imediatas:

Se você está migrando de testes cURL ad hoc, esta é uma atualização significativa. Se você está migrando de uma ferramenta apenas de requisição, é aqui que o Apidog começa a importar mais, porque você pode manter design, testes, ambientes e documentação em um só lugar.

Passo 7: Criar um Ambiente Apidog

Uma vez que a API é importada, crie um ambiente para seu serviço local.

Variáveis de exemplo:

base_url = http://localhost:8000
analysis_id =

Se sua API usar autenticação, inclua isso também:

internal_api_key = your-local-dev-key

Este passo parece pequeno, mas evita muito atrito:

Esta é uma das razões mais simples pelas quais o Apidog é um forte companheiro para o TradingAgents. O próprio framework lida com a lógica de análise. O Apidog lida com o fluxo de trabalho compartilhado em torno dele.

Passo 8: Testar o Fluxo de Trabalho Completo no Apidog

Agora você pode usar o Apidog para testar o TradingAgents da mesma forma que um cliente real faria.

Requisição 1: Criar a análise

Configurar:

{
 "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
}

Adicione um script de teste que valida o status e armazena o ID:

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);

Requisição 2: Pesquisar (Polling) a análise

Configurar:

Então adicione uma asserção como:

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);
});

Se você também quiser uma verificação de caminho de sucesso:

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

Encadeie ambas as requisições em um cenário

É aqui que o Apidog se torna mais do que um cliente de API. Construa um cenário que:

  1. envia POST /analyses
  2. armazena analysis_id
  3. espera alguns segundos
  4. executa GET /analyses/{{analysis_id}}

Isso oferece às suas equipes de QA e engenharia uma maneira reprodutível de validar o ciclo de vida, em vez de apenas verificar se um endpoint retorna um 200.

Passo 9: Publicar Documentos Internos para Sua Equipe

Uma vez que as requisições funcionem, não pare nos testes.

Use o Apidog para publicar documentação interna que explica:

Esta é uma das partes mais importantes de usar o TradingAgents bem. O framework principal é inteligente, mas frameworks inteligentes se tornam gargalos para a equipe quando o contrato vive apenas na cabeça de um desenvolvedor.

Baixe o Apidog gratuitamente para transformar o TradingAgents em um fluxo de trabalho de API documentado com ambientes, asserções e cenários reutilizáveis prontos para a equipe.

Erros Comuns ao Usar o TradingAgents Desta Maneira

Tratar o framework como uma API hospedada

O TradingAgents não é um serviço público pronto. É um framework Python. Construa o contrato que você quer que sua equipe use, em vez de esperar que o repositório o forneça para você.

Passar segredos através dos corpos das requisições

Mantenha as chaves do provedor no gerenciamento de ambiente. Não as exponha em exemplos, chamadas de frontend ou capturas de tela compartilhadas.

Retornar uma única resposta síncrona longa

Para um fluxo de trabalho de agente multi-etapas, uma API baseada em tarefas geralmente é mais fácil de gerenciar do que uma solicitação de bloqueio longa.

Expor muitos parâmetros de configuração

O repositório possui opções de configuração úteis, mas sua API não precisa expor todas as configurações internas no primeiro dia. Comece com um contrato pequeno e estável.

Manter os resultados apenas na memória

O código do tutorial usa um dicionário em memória porque é fácil de entender. Em produção, armazene o estado da tarefa em Redis, Postgres ou outro backend durável.

Esconder o aviso de pesquisa

Se o seu serviço envolve o TradingAgents, mantenha o mesmo aviso que o projeto utiliza. O framework é para pesquisa e experimentação, não para aconselhamento financeiro.

Conclusão

A melhor forma de usar o TradingAgents depende do que você está tentando fazer. Se você está explorando o framework sozinho, a CLI e o pacote Python são suficientes. Se você deseja um fluxo de trabalho de equipe estável e repetível, envolva o TradingAgents em uma pequena API e use o Apidog para testá-lo e documentá-lo.

Se você quer passar de um repositório GitHub para um fluxo de trabalho de equipe utilizável rapidamente, instale o TradingAgents, confirme que o TradingAgentsGraph funciona localmente, adicione POST /analyses e GET /analyses/{id}, então importe o esquema para o Apidog e construa um cenário de ponta a ponta. Esse caminho é muito mais fácil de manter do que uma coleção de comandos de terminal e conhecimento tribal.

botão

FAQ

Como usar o TradingAgents pela primeira vez?

Comece instalando o repositório, configurando as variáveis de ambiente do provedor de modelo e executando o exemplo Python com TradingAgentsGraph. Uma vez que isso funcione, decida se você precisa apenas da CLI ou se deve envolvê-lo em uma API.

O TradingAgents vem com uma API REST oficial?

Não, com base nos materiais do repositório público revisados em 26 de março de 2026. O projeto é apresentado como uma CLI e um pacote Python, razão pela qual muitas equipes desejarão adicionar uma camada fina de FastAPI.

Qual é a maneira mais fácil de usar o TradingAgents em um aplicativo frontend?

Não chame o framework Python diretamente do frontend. Exponha-o através de uma API de backend que retorna um analysis_id, e então permita que o frontend faça polling pelos resultados.

Por que usar o Apidog com o TradingAgents?

O Apidog oferece um local limpo para importar o esquema OpenAPI, salvar valores de ambiente, armazenar exemplos de requisições, adicionar asserções e compartilhar o fluxo de trabalho com colegas de equipe que não precisam fazer engenharia reversa do código Python.

Quais configurações do TradingAgents valem a pena expor em uma API?

O conjunto inicial mais seguro é ticker, data de análise, provedor, escolhas de modelo e profundidade da pesquisa. Você sempre pode expandir mais tarde se o caso de uso for real.

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

Apenas para aprendizado ou prototipagem. Em produção, armazene o estado da tarefa e os resultados em um backend durável para que uma reinicialização do serviço não apague as análises ativas.

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

Os materiais públicos do projeto o descrevem como um framework de pesquisa e explicitamente afirmam que não é um conselho financeiro ou de investimento. Trate-o como um sistema de pesquisa e experimentação, a menos que você adicione seus próprios controles, validação e governança.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar
Como Transformar TradingAgents em um Fluxo de Trabalho de API de Negociação Real