Como construir um agente de pesquisa de investimentos: mercados, fundamentos, SEC e dados econômicos em uma única API
Um agente de pesquisa de investimentos precisa de cinco camadas de dados distintas — preços, fundamentos, filings, macro e notícias — cada uma normalmente um fornecedor, uma chave e um schema à parte. Veja como conectar as cinco por trás de um único conjunto de endpoints, com código funcional e a conta de custo.
TL;DR
- •Um agente financeiro útil precisa de cinco camadas de dados: mercados em tempo real (preços), fundamentos de empresas (demonstrações financeiras), filings da SEC, indicadores econômicos e notícias. Costurado a partir de fornecedores distintos, são 5 contratos, 5 chaves e 5 schemas.
- •A API Pick expõe as cinco como endpoints de busca JSON consistentes — /search/markets, /search/financials, /search/sec, /search/economic, /search/news — além de /extract para documentos completos. Uma única chave, já formatada para o tool calling de LLM.
- •O padrão do agente: rode os endpoints relevantes em paralelo como ferramentas, mescle o JSON e deixe o modelo raciocinar sobre dados ancorados em vez de alucinar números.
- •O preço em créditos é só-no-sucesso: markets 120, financials 200, sec 120, economic 50, news 15 por chamada. Um turno típico de pesquisa multiferramenta custa bem abaixo de $0.01–$0.10 conforme a profundidade.
- •Construir-vs-comprar: montar você mesmo Polygon + um fornecedor de fundamentos + SEC EDGAR + FRED + uma API de notícias são semanas de integração e 5 faturas mensais; o caminho de um único endpoint é um dia.
O problema das cinco camadas
Pergunte a um LLM "a NVIDIA está cara agora?" e ele vai inventar um índice P/L com total convicção. A correção não é um modelo maior — é a ancoragem. Um agente de research que conquista confiança precisa trazer dados vivos e citados ao longo de cinco camadas, e então raciocinar sobre eles:
- Mercados — o preço atual, o valor de mercado e como ele se moveu. Cripto, forex, ETFs e os que mais se movem no dia quando for relevante.
- Fundamentos — balanço patrimonial, demonstração de resultados, fluxo de caixa, dividendos e transações de insiders. A camada do "o negócio está realmente saudável".
- Filings da SEC — fatores de risco do 10-K, detalhe do 10-Q, eventos do 8-K, linguagem das earnings calls. A dimensão qualitativa que os números não captam.
- Indicadores econômicos — juros, inflação, emprego, PIB do FRED, BLS, Banco Mundial e IMF. O pano de fundo macro dentro do qual toda tese se assenta.
- Notícias — o catalisador oportuno: um rebaixamento de rating, um lançamento de produto, uma ação regulatória.
Costurado a partir de fornecedores distintos, são cinco contratos, cinco chaves de API, cinco regimes de rate-limit e cinco schemas de resposta que você precisa normalizar antes que um modelo possa tocá-los. A integração é onde os projetos de agentes financeiros empacam.
Um conjunto de endpoints, cinco camadas
A API Pick expõe cada camada como um endpoint de busca JSON consistente, de modo que o agente fala com uma única chave e um único formato de resposta:
- Markets Search — ações globais e dos EUA, cripto, forex, ETFs, fundos, commodities e os papéis que mais se movem nos EUA.
- Financials Search — balanços, demonstrações de resultados, fluxo de caixa, dividendos, transações de insiders.
- SEC Filings Search — 10-K/10-Q/8-K, transcrições de resultados, estatísticas de equity.
- Economic Data Search — FRED, BLS, Banco Mundial, IMF, USAspending, Destatis.
- News Search — notícias filtradas por data dos principais veículos.
- Extract — traz um filing ou artigo completo para markdown limpo quando um trecho não basta.
A arquitetura do agente
Registre cada endpoint como uma ferramenta. Quando uma pergunta chega, o agente decide de quais camadas precisa, as chama em paralelo, mescla o JSON e raciocina sobre o resultado ancorado. Uma pergunta sobre um ticker toca markets + fundamentos + notícias; uma pergunta de "como o setor está posicionado" toca economic + notícias + alguns comparáveis.
import asyncio, httpx, os
API = "https://api.apipick.com/v1"
HEADERS = {"x-api-key": os.environ["APIPICK_KEY"], "Content-Type": "application/json"}
async def search(client, path, query, **kw):
r = await client.post(f"{API}/{path}", headers=HEADERS,
json={"query": query, **kw})
r.raise_for_status()
return r.json()["results"]
async def research(ticker: str):
async with httpx.AsyncClient(timeout=30) as c:
markets, fundamentals, filings, macro, news = await asyncio.gather(
search(c, "search/markets", f"{ticker} price and market cap"),
search(c, "search/financials", f"{ticker} latest balance sheet and cash flow"),
search(c, "search/sec", f"{ticker} 10-K risk factors", end_date="2026-06-16"),
search(c, "search/economic", "US interest rates and inflation latest"),
search(c, "search/news", f"{ticker} latest news", end_date="2026-06-16"),
)
return {"markets": markets, "fundamentals": fundamentals,
"filings": filings, "macro": macro, "news": news}
# Feed the merged JSON back to your LLM as grounding, with the source URLs,
# and ask it to synthesize — never to recall numbers.
context = asyncio.run(research("NVDA"))Cada resultado carrega uma URL source. Repasse-as até a resposta final para que um humano possa auditar cada afirmação — e para que a saída do agente seja citável, que é o que a torna útil em um fluxo de trabalho real.
Construir vs. comprar
| Montar você mesmo | API Pick | |
|---|---|---|
| Fornecedores / chaves | ~5 (Polygon, fundamentos, EDGAR, FRED, notícias) | 1 |
| Formatos de resposta | 5 a normalizar | 1 formato de JSON |
| Tempo até o primeiro agente | Semanas de integração | Um dia |
| Faturamento | 5 assinaturas mensais | Por chamada, só no sucesso |
| Pronto para LLM | Você formata cada um | Trechos pré-formatados + URLs de origem |
Para um único tipo de dado, ir direto é razoável. Para um agente que precisa dos cinco e explora de forma imprevisível, o caminho de um único endpoint é lançado em um dia e só fatura quando uma chamada tem sucesso.
O que isso desbloqueia
As mesmas cinco ferramentas alimentam muito mais do que lookups de tickers: agentes de briefing de temporada de resultados, screens setoriais ancorados em fundamentos, comentário de carteira consciente da macro e assistentes de diligence que leem o 10-K de verdade via Extract. O padrão é sempre o mesmo — chamadas de ferramentas ancoradas, recuperação em paralelo, síntese sobre dados reais com as fontes anexadas.
Comece com uma chave gratuita (100 créditos, sem cartão) e conecte as cinco ferramentas ao framework de agentes de sua preferência. A partir daí é engenharia de prompts, não encanamento.
Perguntas Frequentes
De quais dados um agente de pesquisa de investimentos realmente precisa?
Cinco camadas. (1) Mercados em tempo real — preços, cripto, forex, ETFs, os que mais se movem, para a pergunta de 'o que está fazendo agora'. (2) Fundamentos — balanço patrimonial, demonstração de resultados, fluxo de caixa, dividendos, transações de insiders. (3) Filings da SEC — texto de 10-K/10-Q/8-K e transcrições de resultados para sinais qualitativos. (4) Indicadores econômicos — FRED, BLS, Banco Mundial, IMF para o pano de fundo macro. (5) Notícias — catalisadores oportunos. A maioria dos agentes falha porque tem preços mas não fundamentos, ou fundamentos mas não contexto macro.
Por que não chamar diretamente Polygon, FRED e SEC EDGAR?
Você pode — e para um único tipo de dado tudo bem. A dor é que o agente precisa dos cinco: são cinco fornecedores, cinco esquemas de autenticação, cinco regimes de rate-limit, cinco formatos de resposta que você precisa normalizar antes que o LLM possa usá-los, e cinco faturas. A abordagem de um único endpoint troca um pequeno prêmio por chamada por uma chave, um formato de JSON e faturamento só-no-sucesso — que, para um agente fazendo chamadas exploratórias multiferramenta, costuma ser o caminho mais barato e muito mais rápido para lançar.
Como evito que o LLM alucine números financeiros?
Nunca deixe o modelo produzir números de memória. Transforme cada fonte de dados em uma ferramenta, obrigue o agente a chamá-la e passe de volta o JSON retornado como ancoragem. O trabalho do modelo é raciocinar e sintetizar sobre valores recuperados, não recordá-los. Cite a URL de origem de cada resultado para que a saída seja auditável — é isso também que torna a resposta confiável para um revisor humano.
A saída serve para operar ou aconselhar de verdade?
Não. A saída de uma API de recuperação é informativa. Ela ancora o raciocínio de um analista ou agente em dados reais; não é aconselhamento de investimento e não deve ser usada como sinal de trading automatizado sem um humano qualificado e controles de risco adequados. Trate o agente como um acelerador de research, não como quem decide.
Quanto custa um turno de pesquisa?
O faturamento é por chamada bem-sucedida: markets 120 créditos, financials 200, sec 120, economic 50, news 15 (1000 créditos ≈ $1). Um turno focado que toca markets + fundamentos + notícias são ~335 créditos (~$0.34); um turno mais leve de macro+notícias são ~65 créditos. Você só paga em HTTP 200, então chamadas que falham ou vêm vazias não custam nada — algo que importa quando um agente explora.
APIs usadas neste artigo
Sarah Choy é a CEO da API Pick. Ela escreve sobre a construção de APIs prontas para produção para agentes de IA e fluxos de trabalho com LLMs.