Agente de IA para Análise Fundamentalista de Ações Brasileiras com Claude

O que muda ao transformar um chat em agente autônomo

A distinção prática aparece no estilo da instrução. "Qual o P/L do ITUB4?" é uma pergunta discreta: um turno, uma tool call, uma resposta. "Analise ITUB4 e diga se está cara ou barata" é um objetivo: requer consultar fundamentos atuais, comparar com histórico próprio, comparar com bancos pares, avaliar endividamento, qualidade e crescimento, e sintetizar o tudo em prosa defensável. O agente decide sozinho quantas chamadas fazer e em que ordem.

Três propriedades separam o padrão agente do padrão chatbot. Planejamento: o modelo quebra o objetivo em subtarefas antes de executar. Autonomia: o ciclo de tool call e análise repete sem intervenção humana até que o objetivo seja cumprido. Saída estruturada: o produto final segue um formato predefinido, não prosa livre. Os três pontos pressupõem tool use confiável e um contrato claro com as fontes de dados, papel que o bolsai-mcp cumpre para a B3.

O conceito não é novo em engenharia de software. O que mudou entre 2024 e 2026 foi a estabilidade da peça que faltava: modelos com tool use confiável, system prompts capazes de absorver regras de negócio densas e protocolos como MCP documentados em modelcontextprotocol.io. Antes disso, agentes financeiros existiam em papers e em demos que quebravam na terceira consulta. Hoje, o ciclo se fecha com código Python curto e custo previsível.

Arquitetura: Claude + MCP + bolsai API

A arquitetura proposta tem quatro camadas. A primeira é o orquestrador Python, responsável por inicializar a conversa, configurar o system prompt, gerenciar o loop de tool use e formatar a saída. A segunda é o cliente MCP, que abre uma conexão com o servidor bolsai-mcp e descobre as ferramentas disponíveis. A terceira é o próprio servidor MCP, processo local que traduz ferramentas em chamadas HTTP autenticadas. A quarta é a API pública da bolsai em api.usebolsai.com, que devolve dados da B3, CVM e BCB em JSON.

Nesse arranjo, o modelo (Claude 4.6 Sonnet via SDK da Anthropic) não acessa a internet diretamente. Todo dado numérico entra na conversa como retorno de tool call, garantindo auditabilidade. Cada análise produzida pelo agente pode ser rastreada até a ferramenta que forneceu o número, o que é essencial para controlar alucinação em contextos financeiros. O fluxo é: orçamento de tokens inicial → system prompt carregado → user prompt com objetivo → loop (tool calls + observações) → resposta final formatada.

Os três componentes externos conversam por meio de stdio. O Python SDK da Anthropic recebe as descrições das ferramentas do bolsai-mcp em tempo de inicialização, encaminha ao modelo no campo tools da API de mensagens e traduz os tool_use blocks da resposta em chamadas MCP. O design é linear e fácil de depurar: cada iteração pode ser salva em disco como linha de log JSON.

Setup: SDK da Anthropic, bolsai-mcp e chaves de API

O agente requer dois pacotes Python e duas chaves. Os pacotes são anthropic (cliente oficial da Anthropic) e mcp (SDK cliente do Model Context Protocol). As chaves são ANTHROPIC_API_KEY, obtida em console.anthropic.com, e BOLSAI_API_KEY, obtida em usebolsai.com/dashboard após login com Google. O pacote bolsai-mcp em si é executado via uvx, sem instalação manual.

# Instalação dos SDKs
pip install anthropic mcp

# Variáveis de ambiente
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export BOLSAI_API_KEY="sk_bolsai_..."

# Verificar acesso ao servidor MCP (sanity check)
uvx bolsai-mcp --help

O agente é inicializado com um arquivo de configuração JSON que descreve o servidor MCP a ser lançado, equivalente ao claude_desktop_config.json usado no Claude Desktop. A diferença é que agora o próprio script Python instancia o processo filho, sem depender de uma aplicação gráfica. O mesmo servidor pode ser reaproveitado entre scripts de research, APIs internas e pipelines agendados.

# Exemplo 1: setup mínimo — cliente Anthropic + MCP client
# apontando para bolsai-mcp via stdio
import os
import asyncio
from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="uvx",
    args=["bolsai-mcp"],
    env={"BOLSAI_API_KEY": os.environ["BOLSAI_API_KEY"]},
)

async def list_tools() -> None:
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            for t in tools.tools:
                print(f"- {t.name}: {t.description[:60]}")

asyncio.run(list_tools())

# Saída esperada (trecho):
# - get_stock_quote: Retorna cotação atual e variação diária...
# - get_fundamentals: Retorna 27 indicadores fundamentalistas...
# - get_price_history: Série histórica de preços OHLCV...
# - screen_stocks: Filtra ações por critérios fundamentalistas...

Com esse script rodando sem erro, a conexão com o servidor MCP está validada e o agente pode ser construído por cima. O próximo passo é o system prompt, que define persona e regras antes que qualquer ticker entre na conversa.

System prompt para um analista fundamentalista IA

O system prompt é o contrato que transforma Claude em analista. Um prompt genérico gera respostas genéricas; um prompt estruturado com persona, framework e regras gera relatórios consistentes e auditáveis. O padrão abaixo foi iterado em produção e cobre quatro dimensões de análise: valuation, qualidade, endividamento e crescimento. Também fixa formato de saída em Markdown e proíbe recomendações diretas de compra ou venda.

# System prompt do agente (trecho longo, em variável Python)
SYSTEM_PROMPT = """
Você é um analista fundamentalista sênior com aproximadamente
dez anos de experiência cobrindo ações listadas na B3.
Trabalha em uma casa de research independente e se comunica
em português do Brasil formal, evitando jargão desnecessário.

# Objetivo

Analisar ações brasileiras com base em dados verificáveis
fornecidos pelas ferramentas MCP da bolsai. Toda análise
produzida deve ser defensável em reunião de comitê.

# Framework de análise (4 dimensões)

Para cada ticker analisado, avaliar e comentar:

1. VALUATION: múltiplos P/L, P/VP, EV/EBITDA e Dividend Yield
   comparados ao histórico da própria empresa (5 anos) e aos
   pares setoriais quando aplicável.
2. QUALIDADE: ROE, ROIC, margem líquida, margem EBITDA.
   ROE acima de 15% e ROIC acima do custo de capital estimado
   caracterizam qualidade acima da média.
3. ENDIVIDAMENTO: dívida líquida/EBITDA, dívida líquida/PL,
   cobertura de juros. Acima de 3x em dívida/EBITDA é sinal
   de alerta em setores não regulados.
4. CRESCIMENTO: evolução de receita e lucro líquido nos
   últimos 2 a 3 anos. Queda consistente de receita real
   exige justificativa qualitativa explícita.

# Regras rígidas

- NUNCA inventar números. Todo dado numérico citado no
  relatório deve vir de uma tool call executada na conversa.
- NUNCA fazer recomendação explícita de compra ou venda.
  Usar linguagem descritiva: "múltiplo abaixo da média
  histórica", "endividamento compatível com o setor",
  "estrutura de capital sob pressão".
- SEMPRE citar a data de referência dos dados usados.
- Se uma ferramenta falhar ou retornar dados incompletos,
  indicar explicitamente no relatório em vez de omitir.
- Não usar dados externos à API da bolsai. Se faltar
  informação, apontar a lacuna.

# Ferramentas disponíveis

- get_stock_quote(ticker): cotação e variação diária.
- get_fundamentals(ticker, reference_date): 27 indicadores;
  passe reference_date para snapshots de trimestres passados.
- get_dividends(ticker): DY TTM e histórico de proventos.
- screen_stocks(filtros): filtragem por critérios.
- get_fii_details(ticker): dados específicos de FIIs.
- get_macro_indicator(indicator): Selic, CDI, IPCA, USD/BRL.
- search_companies(query, sector): empresas por nome ou setor.

# Formato de saída obrigatório

## Resumo executivo (até 3 parágrafos)
Tese central em prosa objetiva.

## Valuation
Múltiplos atuais versus histórico e pares. Tabela Markdown
com colunas: Indicador | Atual | Média 5 anos | Setor.

## Qualidade operacional
ROE, ROIC, margens. Comentário sobre tendência.

## Endividamento
Dívida líquida/EBITDA, estrutura de capital.

## Crescimento
Evolução de receita e lucro nos últimos trimestres.

## Pontos de atenção
Lista de riscos ou lacunas nos dados.

## Dados utilizados
Lista de ferramentas chamadas e data de referência.
"""

A parte mais sensível do prompt é a seção "Regras rígidas". Sem a proibição explícita de inventar números, modelos tendem a preencher lacunas com valores plausíveis quando uma ferramenta falha. Sem a proibição de recomendar compra e venda, o agente cruza o limite entre research educacional e recomendação de investimento, zona regulatoriamente sensível no Brasil. Ambas as regras precisam ser reforçadas via formato de saída: a seção "Dados utilizados" obriga o modelo a mostrar o rastro.

Para aprofundar o framework de análise fundamentalista que alimenta o prompt, o post análise fundamentalista para iniciantes detalha as quatro dimensões com exemplos práticos de interpretação.

Primeiro agente: análise automática de uma ação

O loop do agente é simples na estrutura e cuidadoso na implementação. O orquestrador inicializa a conversa com system prompt e user prompt, envia ao Claude com a lista de ferramentas, lê a resposta, e enquanto houver tool_use blocks, executa cada um via MCP e devolve os resultados como tool_result. Quando o modelo encerra com stop_reason = end_turn, o texto final é o relatório.

# Exemplo 2: agente completo de análise fundamentalista
# Objetivo: produzir relatório estruturado para um ticker
import asyncio, json, os
from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

MODEL = "claude-sonnet-4-6-20260301"
anthropic = Anthropic()

async def run_agent(objective: str) -> str:
    server_params = StdioServerParameters(
        command="uvx", args=["bolsai-mcp"],
        env={"BOLSAI_API_KEY": os.environ["BOLSAI_API_KEY"]},
    )
    async with stdio_client(server_params) as (r, w):
        async with ClientSession(r, w) as session:
            await session.initialize()
            tools_spec = await session.list_tools()
            tools = [{
                "name": t.name,
                "description": t.description,
                "input_schema": t.inputSchema,
            } for t in tools_spec.tools]

            messages = [{"role": "user", "content": objective}]

            while True:
                resp = anthropic.messages.create(
                    model=MODEL, max_tokens=4096,
                    system=SYSTEM_PROMPT, tools=tools, messages=messages,
                )
                messages.append({"role": "assistant", "content": resp.content})

                if resp.stop_reason == "end_turn":
                    return "".join(
                        b.text for b in resp.content if b.type == "text"
                    )

                tool_results = []
                for block in resp.content:
                    if block.type == "tool_use":
                        result = await session.call_tool(block.name, block.input)
                        tool_results.append({
                            "type": "tool_result",
                            "tool_use_id": block.id,
                            "content": json.dumps(
                                [c.text for c in result.content]
                            ),
                        })
                messages.append({"role": "user", "content": tool_results})

relatorio = asyncio.run(run_agent(
    "Analise ITUB4 e diga se está cara ou barata, "
    "em 3 parágrafos. Inclua comparação com BBAS3 e BBDC4."
))
print(relatorio)

Um agente assim inicializado normalmente faz entre 4 e 7 chamadas para cobrir o framework completo: get_fundamentals para ITUB4, BBAS3 e BBDC4, get_fundamentals repetido com reference_date para reconstruir a série histórica de ITUB4, get_dividends para confirmar DY e get_macro_indicator para Selic e CDI como âncora de custo de capital. A saída produzida segue o formato fixado no system prompt.

# Trecho do relatório produzido pelo agente

## Resumo executivo

ITUB4 negocia a 9.87x lucros e 2.08x patrimônio, com ROE
de 21.3% e Dividend Yield TTM de 5.8%. Os múltiplos
estão próximos da média dos últimos 5 anos (P/L médio 9.4,
P/VP médio 2.0), indicando que o mercado precifica o
papel em linha com sua relação histórica de qualidade.

Na comparação com pares, BBAS3 opera a P/L 4.56 e ROE
21.3% (maior rentabilidade relativa ao preço), enquanto
BBDC4 entrega ROE 13.8% a P/L 7.9. ITUB4 fica entre
os dois: prêmio de preço justificado por consistência,
mas sem o desconto agressivo de BBAS3.

## Valuation

| Indicador | Atual | Média 5 anos | Setor (bancos) |
|-----------|-------|--------------|----------------|
| P/L       | 9.87  | 9.40         | 7.12           |
| P/VP      | 2.08  | 2.00         | 1.45           |
| DY TTM    | 5.8%  | 5.2%         | 6.3%           |

## Endividamento

Estrutura específica de banco; métricas de dívida líquida/
EBITDA não se aplicam. Índice de Basileia e cobertura
de provisões seguem dentro de faixas regulatórias.

## Dados utilizados

- get_fundamentals(ITUB4, BBAS3, BBDC4) em 2026-04-18
- get_fundamentals(ITUB4, reference_date=...) por trimestre
- get_dividends(ITUB4) em 2026-04-18
- get_macro_indicator(selic) em 2026-04-18

O formato é estável entre execuções porque o system prompt fixa seções obrigatórias. Isso permite que o output seja consumido por sistemas downstream (geração de PDF, indexação em base de research, envio por e-mail) sem regex frágil. A metodologia dos indicadores usados no relatório é documentada em posts individuais, como P/L com API Python e ROE na API da bolsai.

Agente com memória: iteração sobre múltiplas ações

O mesmo orquestrador serve a objetivos mais amplos do que analisar um único ticker. Passando uma lista de ações no user prompt, o agente reutiliza o contexto: aprende padrões setoriais nas primeiras análises e aplica o aprendizado nas seguintes. O efeito prático é que o relatório do quinto ticker costuma ficar mais curto e mais preciso, porque o modelo já carrega referências internas de médias setoriais computadas em voo.

Uma precaução importante é o orçamento de contexto. Relatórios completos podem crescer rápido e o input do Claude 4.6 Sonnet suporta 200 mil tokens, mas com custo. Quando o objetivo é comparar cinco ou mais tickers, vale fragmentar: gerar relatórios individuais em paralelo (cada um com histórico próprio) e concatenar como user prompt em uma segunda chamada de agregação. Essa separação também facilita o cache — análises de nomes pouco voláteis podem ser reutilizadas por até uma semana antes de uma nova chamada.

Para casos em que o interesse é estratégia de dividendos ou construção de carteira a partir de critérios, o post como montar carteira de dividendos com a API mostra a versão determinística (sem IA) do mesmo problema, útil como baseline de comparação.

Screening guiado por IA: comparação com screener determinístico

Screening é a tarefa mais interessante porque o agente pode encadear ferramentas de formas não-triviais. Um pedido como "encontre 5 ações com ROE acima de 15% e P/L abaixo de 12" tem solução direta via screen_stocks. Mas "encontre 5 ações com ROE acima de 15%, P/L abaixo de 12, crescimento de receita nos últimos 2 anos e que não sejam bancos" combina filtros determinísticos com análise qualitativa pós-filtro, território natural para um agente.

# Exemplo 3: agente de screening multi-etapa
objetivo = (
    "Encontre 5 ações da B3 com ROE > 15% e P/L < 12. "
    "Descarte bancos. Para cada uma, verifique se a receita "
    "cresceu nos últimos 2 anos. Devolva tabela + comentário."
)

relatorio = asyncio.run(run_agent(objetivo))
print(relatorio)

# Rastreamento das tool calls feitas pelo agente:
#
# 1. screen_stocks({"roe_min": 15, "pl_max": 12, "limit": 20,
#    "sector_exclude": "Bancos", "sort": "roe_desc"})
#    -> 20 candidatos
#
# 2-21. get_fundamentals(ticker, reference_date=...) em loop
#       para cada candidato e cada trimestre, reconstruindo
#       a série de receita dos últimos 2 anos
#
# 22. Filtro interno: mantém apenas empresas com
#     receita TTM > receita TTM de 2 anos atrás
#
# 23. Ordena por ROE decrescente, pega top 5
#
# Saída final (trecho):

Ticker  ROE    P/L    Cresc. rec. 2a   Setor
VIVT3   18.7%  8.45   +6.2%            Telecom
EGIE3   17.4%  9.12   +14.8%           Elétrica
CPLE6   18.5%  5.89   +9.1%            Elétrica
TAEE11  19.8%  8.23   +11.5%           Transmissão
WEGE3   39.5%  28.46  +22.3%           Industrial

Obs.: WEGE3 atende ROE mas extrapola P/L de 12.
Substituída por TUPY3 (15.8% ROE, 9.1 P/L, +8%).

O ganho em relação ao screener determinístico aparece em dois pontos. Primeiro, o agente detectou que WEGE3 violava um critério numérico e trocou por um candidato válido, comportamento que um filtro SQL não reproduz sem código adicional. Segundo, o relatório final inclui comentário textual sobre cada escolha, enquanto o screener puro devolve apenas a linha. O custo é maior — o exemplo acima consumiu cerca de 80 mil tokens, mais o overhead de 20 tool calls — e para pipelines com muitos tickers, vale separar: screener determinístico para reduzir o universo inicial, agente apenas para a análise final.

O post screener de ações brasileiras em Python detalha a versão determinística que o agente usa como primitiva, incluindo sintaxe dos filtros de screen_stocks.

Avaliação: quando o agente acerta, quando alucina, como mitigar

Agentes de IA alucinam. Em contexto financeiro, isso significa inventar um número específico, misturar empresas homônimas ou atribuir a uma companhia dados que pertencem a outra. Três padrões de erro aparecem com frequência em produção e têm mitigações concretas.

Número inventado quando a tool falha

Se uma tool call retorna erro e o agente precisa completar o relatório, a tentação estatística do modelo é preencher o campo com algo plausível. A mitigação é dupla: regra explícita no system prompt ("se uma ferramenta falhar, indicar explicitamente no relatório em vez de omitir") e validação pós-hoc via regex nos números produzidos, cruzando cada valor citado com o conteúdo JSON das tool calls registradas na conversa. Um número que aparece no texto mas não aparece em nenhum tool result é evidência de alucinação.

Troca de ticker em contexto longo

Em análises comparativas, o modelo ocasionalmente atribui métrica de um ticker a outro. O risco cresce com o número de empresas comparadas. Mitigação: restringir cada tool_result a um único ticker por vez e usar formatadores de saída que força menção explícita do ticker ao lado de cada número. A estrutura "ITUB4: ROE 21.3% | BBAS3: ROE 21.3%" é menos propensa a confusão do que "ROE de 21.3% para ambos".

Interpretação questionável de sinal

Diferente dos dois anteriores, este erro é qualitativo. O agente pode descrever como "barato" um múltiplo que, no contexto setorial, está apenas em linha. Mitigação não é totalmente automática: exigir no prompt que toda avaliação qualitativa ("caro", "barato", "alto", "baixo") venha acompanhada da comparação numérica explícita reduz o problema. O controle final é humano, via revisão do relatório antes de qualquer decisão.

Uma prática de produção útil é manter uma base de testes com perguntas conhecidas e respostas esperadas. A suite roda o agente contra cada pergunta e calcula duas métricas: taxa de alucinação (números citados sem origem em tool call) e taxa de aderência ao formato (campos obrigatórios presentes na saída). Valores observados em bancadas internas ficam em torno de 0,5% de alucinação após regras no prompt e 98%+ de aderência ao formato.

Custo: tokens versus valor da análise

O custo operacional de um agente bem calibrado é baixo para uso individual e merece atenção em escala. A tabela abaixo resume estimativas para o Claude Sonnet 4.6 na tabela de preços de abril de 2026 (US$3 por milhão de tokens de input, US$15 por milhão de output, câmbio USD/BRL assumido em 5,10).

O custo do acesso a dados é marginal perto do custo dos tokens, desde que o plano da bolsai esteja adequado ao volume. No plano gratuito (200 req/dia), um agente de screening que faz 20 chamadas MCP consome 10% da cota diária. No plano Pro (R$49/mês, 10.000 req/dia), o mesmo agente pode rodar até 500 vezes por dia. O fator dominante no custo total de propriedade é o provedor do modelo, não o provedor dos dados. Para comparação objetiva entre APIs de dados da B3, o post bolsai versus brapi documenta as diferenças entre as opções disponíveis.

Duas otimizações reduzem custo sem perder qualidade. A primeira é usar um modelo menor para subtarefas auxiliares, deixando Sonnet apenas para a síntese final. A segunda é aplicar prompt caching em system prompts extensos, descontando até 90% do custo do input em chamadas subsequentes na mesma sessão. Ambas estão documentadas em docs.anthropic.com e cobertas também na página de modelos em anthropic.com/claude.

Perguntas frequentes

Qual a diferença entre MCP e function calling tradicional?

Function calling tradicional exige que cada provedor de LLM defina seu próprio formato de schema (OpenAI, Anthropic e Google usam estruturas distintas) e que a aplicação implemente o transporte, o parsing e a execução das chamadas. MCP padroniza tudo isso: o servidor expõe ferramentas em um contrato único via JSON-RPC sobre stdio ou HTTP, e qualquer cliente compatível (Claude Desktop, Claude Code, Cursor, SDKs da Anthropic) consome o mesmo servidor sem alterações. Um agente construído com MCP fica portável entre modelos, reduzindo lock-in.

Preciso pagar a Anthropic além da API da bolsai?

Sim. A API da bolsai cobra apenas pelo acesso aos dados de mercado (plano gratuito com 200 requisições/dia, Pro a R$49/mês com 10.000 requisições/dia, detalhes em /#pricing). O custo dos tokens consumidos pelo modelo é cobrado separadamente pela Anthropic, conforme tabela de preços da própria. Uma análise fundamentalista completa de um ticker no Claude Sonnet 4.6 custa em torno de R$0,15 em tokens; um agente de screening sobre 10 ações chega a R$1,20. O plano Claude Pro pessoal (US$20/mês) não cobre chamadas via API: é produto separado.

O agente substitui um analista humano?

Não. Um agente de IA acoplado à API bolsai acelera tarefas mecânicas de coleta e cruzamento de indicadores, padroniza a produção de relatórios e reduz o tempo entre pergunta e evidência. Decisões de alocação, interpretação qualitativa de setor, leitura de governança e contexto de macro estrutural continuam dependendo de julgamento humano. O uso mais honesto é tratar o agente como um analista júnior que entrega um rascunho auditável, revisado antes de qualquer ação. A responsabilidade pela decisão continua humana.

Posso usar GPT-4 ou Gemini em vez de Claude?

Sim, desde que o modelo suporte tool use estruturado. GPT-4.1 e GPT-5 aceitam function calling e podem consumir o bolsai-mcp via wrapper OpenAPI (GPT Actions) ou adaptador mcp-to-openai. Gemini 2.5 expõe tool use próprio, mas o ecossistema de clientes MCP para Gemini ainda é menos maduro. A escolha por Claude 4.6 Sonnet neste guia reflete três pontos concretos: suporte nativo a MCP, aderência forte a system prompts extensos e qualidade de raciocínio em análise financeira em português. A arquitetura proposta é desenhada para ser portável — o servidor MCP em si não muda.

Leia também

O conteúdo deste artigo tem caráter educacional e técnico. Os dados e estimativas de custo citados refletem valores públicos disponíveis no momento da publicação e podem mudar. Nada aqui constitui recomendação de compra ou venda de ativos financeiros. Nomes de produtos e marcas pertencem aos respectivos titulares; Claude, Anthropic e Model Context Protocol são marcas da Anthropic PBC. Por bolsai, 19 de abril de 2026.