Laboratório: Agente Multi-LLM para Classificação e Conciliação Contábil com MCP

Roteiro para estudo em ambiente de laboratório ou de teste. Execute apenas em equipamentos, redes e contas que você tenha autorização para usar, com backup e homologação próprios. Comandos podem causar indisponibilidade ou perda de dados. Software e marcas citados pertencem aos seus titulares. Termos de Uso.

Duração estimada

120 min

Passos

13

Validações

4

Versões da documentação consultada

Python 3.10 ou superior · Claude Agent SDK a versão estável atual · OpenAI Agents SDK a versão estável atual · Model Context Protocol (MCP) 2026-07-28 · FastAPI a versão estável atual · Pydantic a versão estável atual

Topologia

Uma máquina local (192.168.56.10) executa o agente Python, que orquestra requisições para Claude e OpenAI usando seus SDKs. O MCP roda como servidor local, expondo ferramentas para classificação e conciliação. Dados de teste são arquivos CSV locais. O agente registra logs e avaliações em disco, e toda decisão sensível exige aprovação manual.

+-------------------+
|   Usuário (CLI)   |
+---------+---------+
          |
          v
+-----------------------+
|  Agente Python (MCP)  |
+----+-----------+------+
     |           |
     v           v
Claude SDK   OpenAI SDK
(REST API)   (REST API)

Equipamentos e software

Roteiro

1. Preparar ambiente Python isolado

   Isolar dependências evita conflitos e facilita a limpeza. Crie um ambiente virtual.

   python3 -m venv venv
   source venv/bin/activateCopiar

   O que você deve ver: (venv) aparece no prompt

2. Instalar SDKs e dependências

   Instale as bibliotecas necessárias para Claude, OpenAI, MCP, FastAPI e Pydantic.

   pip install claude-agent-sdk openai-agents fastapi pydantic uvicornCopiar

   O que você deve ver: Pacotes baixados e instalados sem erro

3. Configurar variáveis de ambiente para segredos

   Nunca exponha chaves de API em código. Exporte as chaves das APIs Claude e OpenAI.

   export ANTHROPIC_API_KEY='SUA_CHAVE_CLAUDE'
   export OPENAI_API_KEY='SUA_CHAVE_OPENAI'Copiar

   O que você deve ver: Variáveis ANTHROPIC_API_KEY e OPENAI_API_KEY disponíveis

4. Criar prompt de sistema versionado para classificação contábil

   Defina o prompt do agente para classificar lançamentos conforme plano de contas EXEMPLO.

   cat > prompts/classificacao_v1.txt <<EOF
   Você é um agente contábil. Classifique cada lançamento no plano de contas EXEMPLO:
   1. Receitas
   2. Despesas
   3. Ativos
   4. Passivos
   5. Patrimônio Líquido
   Retorne sempre o número e o nome da categoria.
   EOFCopiar

   O que você deve ver: Arquivo prompts/classificacao_v1.txt criado

5. Definir ferramenta MCP para classificação

   Implemente uma ferramenta MCP que recebe um lançamento e retorna a classificação.

   cat > mcp_tools/classify.py <<EOF
   from pydantic import BaseModel
   class Input(BaseModel):
       descricao: str
       valor: float
   class Output(BaseModel):
       categoria: str
       codigo: int
   
   def classify(input: Input) -> Output:
       # Lógica EXEMPLO: receitas se valor > 0, despesas se < 0
       if input.valor > 0:
           return Output(categoria='Receitas', codigo=1)
       elif input.valor < 0:
           return Output(categoria='Despesas', codigo=2)
       else:
           return Output(categoria='Ativos', codigo=3)
   EOFCopiar

   O que você deve ver: Arquivo mcp_tools/classify.py criado

6. Definir ferramenta MCP para conciliação bancária

   Implemente ferramenta que sugere conciliação simples entre extrato e lançamentos.

   cat > mcp_tools/reconcile.py <<EOF
   from pydantic import BaseModel
   class Input(BaseModel):
       extrato: list
       lancamentos: list
   class Output(BaseModel):
       conciliados: list
       nao_conciliados: list
   
   def reconcile(input: Input) -> Output:
       # Lógica EXEMPLO: concilia valores iguais
       conciliados = []
       nao_conciliados = []
       for e in input.extrato:
           if e in input.lancamentos:
               conciliados.append(e)
           else:
               nao_conciliados.append(e)
       return Output(conciliados=conciliados, nao_conciliados=nao_conciliados)
   EOFCopiar

   O que você deve ver: Arquivo mcp_tools/reconcile.py criado

7. Configurar servidor MCP local

   Implemente um servidor FastAPI que expõe as ferramentas MCP.

   cat > mcp_server.py <<EOF
   from fastapi import FastAPI
   from mcp_tools.classify import classify, Input as ClassifyInput
   from mcp_tools.reconcile import reconcile, Input as ReconcileInput
   app = FastAPI()
   @app.post('/classify')
   def classify_endpoint(input: ClassifyInput):
       return classify(input)
   @app.post('/reconcile')
   def reconcile_endpoint(input: ReconcileInput):
       return reconcile(input)
   EOFCopiar

   O que você deve ver: Arquivo mcp_server.py criado

8. Rodar servidor MCP

   Inicie o servidor local para expor as ferramentas via HTTP.

   uvicorn mcp_server:app --host 0.0.0.0 --port 8000Copiar

   O que você deve ver: Servidor ouvindo em http://0.0.0.0:8000

9. Implementar agente Python orquestrador

   Crie script que lê lançamentos de um CSV, chama Claude e OpenAI para classificar e conciliar via MCP, registra logs e sugere revisão.

   cat > agente_contabil.py <<EOF
   import csv, os
   from openai_agents import Agent, Runner
   from claude_agent_sdk import ClaudeAgent
   import requests
   API_URL = 'http://localhost:8000'
   with open('dados/lancamentos.csv') as f:
       reader = csv.DictReader(f)
       lancamentos = list(reader)
   resultados = []
   for l in lancamentos:
       payload = {'descricao': l['descricao'], 'valor': float(l['valor'])}
       r = requests.post(f'{API_URL}/classify', json=payload)
       cat = r.json()
       resultados.append({**l, **cat})
   with open('resultados/classificados.csv', 'w') as f:
       writer = csv.DictWriter(f, fieldnames=resultados[0].keys())
       writer.writeheader()
       writer.writerows(resultados)
   EOFCopiar

   O que você deve ver: Arquivo agente_contabil.py criado

10. Criar dados de teste

    Monte um CSV de lançamentos para testar a classificação e conciliação.

    mkdir -p dados resultados
    cat > dados/lancamentos.csv <<EOF
    descricao,valor
    Venda produto,1000
    Pagamento fornecedor,-500
    Depósito bancário,2000
    EOFCopiar

    O que você deve ver: Arquivo dados/lancamentos.csv criado

11. Executar agente e registrar logs

    Rode o agente, verifique logs e saída dos resultados.

    python agente_contabil.pyCopiar

    O que você deve ver: Arquivo resultados/classificados.csv gerado com categorias

12. Implementar avaliação automática

    Crie script de teste que compara saída do agente com resultados esperados.

    cat > testes/test_classificacao.py <<EOF
    import csv
    esperados = [
        {'descricao': 'Venda produto', 'categoria': 'Receitas'},
        {'descricao': 'Pagamento fornecedor', 'categoria': 'Despesas'},
        {'descricao': 'Depósito bancário', 'categoria': 'Receitas'}
    ]
    with open('resultados/classificados.csv') as f:
        reader = csv.DictReader(f)
        saida = list(reader)
    for e in esperados:
        assert any(s['descricao'] == e['descricao'] and s['categoria'] == e['categoria'] for s in saida), f"Falha: {e}"
    print('Todos os testes passaram')
    EOFCopiar

    O que você deve ver: Arquivo testes/test_classificacao.py criado

13. Rodar avaliação automática

    Execute o teste e valide se o agente classificou corretamente.

    python testes/test_classificacao.pyCopiar

    O que você deve ver: Saída: Todos os testes passaram

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca exponha chaves de API em código ou logs
• Restrinja o acesso ao servidor MCP à rede local
• Remova dados de teste sensíveis após o laboratório
• Use variáveis de ambiente para segredos
• Valide entradas para evitar injeção de comandos

Checklist final

• Ambiente Python isolado criado
• SDKs instalados sem erro
• Servidor MCP rodando e respondendo
• Prompt de sistema versionado salvo
• Ferramentas MCP implementadas
• Agente Python executado com sucesso
• Arquivo de resultados gerado
• Avaliação automática passou