Criando seu Primeiro Agente de IA com APIs Brasileiras

Ao final deste tutorial, você vai ter um agente de IA funcional em Python que:

• Consulta informações de empresas pelo CNPJ
• Valida CEPs e retorna dados de endereço
• Consulta informações de bancos brasileiros
• Usa um LLM (GPT-4o-mini) pra interpretar e responder em linguagem natural
• Roda com uma única chave de API (Axon) — sem precisar se cadastrar em 10 serviços

Tempo total: 30 minutos. Linhas de código: ~40. Custo pra rodar 100 perguntas: menos de $0.05.

O que você vai construir

Um agente que responde perguntas como:

• “Me conta sobre a empresa com CNPJ 00.000.000/0001-91”
• “Qual o endereço do CEP 01310-100?”
• “Me fala sobre o banco código 237”

E retorna respostas naturais, usando dados reais e atualizados.

Pré-requisitos

• Python 3.11+ instalado
• Conhecimento básico de Python (saber o que é função e import basta)
• Uma conta no Axon (criamos agora, leva 10 segundos)
• Uma chave OpenAI (ou pode usar Claude / Gemini / Ollama — veremos depois)

Passo 1 — Criando a conta Axon

Vai em axon-5zf.pages.dev, digita seu email, e pronto. Em 10 segundos você tem:

• Uma chave de API (formato ax_live_...)
• $0.50 de crédito grátis pra testar
• Uma wallet USDC na Base L2 (gerada automaticamente)

Copia a chave — vamos usar em breve.

Passo 2 — Setup do ambiente Python

Crie uma pasta pro projeto e configure um ambiente virtual:

mkdir agente-brasil && cd agente-brasil
python -m venv venv
source venv/bin/activate   # Linux/Mac
# ou: venv\Scripts\activate   (Windows)

Instale as dependências:

pip install openai requests python-dotenv

Passo 3 — Configurando credenciais

Crie um arquivo .env na pasta do projeto:

AXON_KEY=ax_live_cole_sua_chave_aqui
OPENAI_API_KEY=sk-cole_sua_chave_openai_aqui
AXON_URL=https://axon-kedb.onrender.com

echo ".env" >> .gitignore

Passo 4 — Criando as ferramentas (tools)

Cria o arquivo tools.py:

import os
import requests
from dotenv import load_dotenv

load_dotenv()

AXON_KEY = os.getenv("AXON_KEY")
AXON_URL = os.getenv("AXON_URL", "https://axon-kedb.onrender.com")

def call_axon(api: str, endpoint: str, params: dict = None):
    """Chama qualquer API através do Axon com uma única chave."""
    url = f"{AXON_URL}/v1/call/{api}/{endpoint}"
    headers = {"Authorization": f"Bearer {AXON_KEY}"}
    response = requests.get(url, headers=headers, params=params or {})
    response.raise_for_status()
    return response.json()


def consultar_cnpj(cnpj: str) -> dict:
    """Consulta dados de empresa pelo CNPJ. Aceita com ou sem formatação."""
    cnpj_limpo = cnpj.replace(".", "").replace("/", "").replace("-", "")
    return call_axon("brasilapi", "cnpj", {"cnpj": cnpj_limpo})


def consultar_cep(cep: str) -> dict:
    """Consulta endereço pelo CEP."""
    cep_limpo = cep.replace("-", "")
    return call_axon("brasilapi", "cep", {"cep": cep_limpo})


def consultar_bank(code: str) -> dict:
    """Consulta banco pelo código (ex: '001' = Banco do Brasil)."""
    return call_axon("brasilapi", "bank", {"code": code})

Testa rápido no terminal pra ver se funciona:

python -c "from tools import consultar_cnpj; import json; print(json.dumps(consultar_cnpj('00000000000191'), indent=2))"

Ou melhor — testa aqui mesmo no browser antes de escrever o código. Essa é a mesma chamada que sua função Python vai fazer, com sua chave real:

Passo 5 — Criando o agente com OpenAI function calling

Cria o arquivo agente.py:

import json
import os
from openai import OpenAI
from dotenv import load_dotenv
from tools import consultar_cnpj, consultar_cep, consultar_bank

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "consultar_cnpj",
            "description": "Consulta dados de empresa brasileira pelo CNPJ",
            "parameters": {
                "type": "object",
                "properties": {"cnpj": {"type": "string", "description": "CNPJ com ou sem formatação"}},
                "required": ["cnpj"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "consultar_cep",
            "description": "Consulta endereço pelo CEP",
            "parameters": {
                "type": "object",
                "properties": {"cep": {"type": "string"}},
                "required": ["cep"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "consultar_bank",
            "description": "Consulta banco brasileiro pelo código (ex: '237' = Bradesco, '001' = Banco do Brasil)",
            "parameters": {
                "type": "object",
                "properties": {"code": {"type": "string"}},
                "required": ["code"],
            },
        },
    },
]

FUNCTION_MAP = {
    "consultar_cnpj": consultar_cnpj,
    "consultar_cep": consultar_cep,
    "consultar_bank": consultar_bank,
}


def rodar_agente(pergunta: str) -> str:
    messages = [
        {
            "role": "system",
            "content": "Você é um assistente que responde perguntas sobre empresas brasileiras, endereços e veículos. Use as ferramentas quando necessário. Responda em português, de forma natural e concisa.",
        },
        {"role": "user", "content": pergunta},
    ]

    for _ in range(5):  # máximo 5 iterações pra evitar loop infinito
        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
            tools=TOOLS,
        )

        msg = response.choices[0].message
        messages.append(msg.model_dump(exclude_none=True))

        if not msg.tool_calls:
            return msg.content  # LLM decidiu responder sem chamar ferramenta

        for call in msg.tool_calls:
            fn_name = call.function.name
            fn_args = json.loads(call.function.arguments)
            try:
                result = FUNCTION_MAP[fn_name](**fn_args)
            except Exception as e:
                result = {"erro": str(e)}

            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result, ensure_ascii=False),
            })

    return "Não consegui responder em tempo hábil."


if __name__ == "__main__":
    import sys
    pergunta = " ".join(sys.argv[1:]) or "Me conta sobre a empresa com CNPJ 00.000.000/0001-91"
    print(rodar_agente(pergunta))

Passo 6 — Rodando o agente

python agente.py "me fala sobre a empresa Banco do Brasil, CNPJ 00.000.000/0001-91"

Saída esperada:

O Banco do Brasil S.A. é uma empresa com sede em Brasília/DF, registrada sob o
CNPJ 00.000.000/0001-91. Trata-se de uma sociedade anônima de grande porte,
atuando principalmente no setor bancário. A empresa está ativa e possui diversos
estabelecimentos pelo Brasil.

Experimenta outras perguntas:

python agente.py "qual é o endereço do CEP 01310-100?"
python agente.py "me fala sobre o CNPJ 11.222.333/0001-81 e depois qual o CEP da sede"

Ou, de novo, testa a chamada CEP direto aqui antes:

O que acabou de acontecer, em detalhe

1. Pergunta do usuário chega pro LLM junto com a lista de ferramentas disponíveis.
2. LLM decide se precisa chamar alguma ferramenta. Se sim, retorna tool_calls.
3. Executamos a ferramenta localmente (que bate no Axon).
4. Axon bate na API real (BrasilAPI, nesse caso — 100% gratuita, zero margem de custo pra você).
5. Resultado volta pro LLM como nova mensagem.
6. LLM gera resposta final em linguagem natural, baseada nos dados.

Quanto custou?

Axon retorna o header x-axon-cost-usdc em cada chamada. Pra ver:

# em tools.py, adicione prints no call_axon:
print(f"Custo: ${response.headers.get('x-axon-cost-usdc', '?')}")
print(f"Cache: {response.headers.get('x-axon-cache', 'miss')}")

Custos típicos:

Ou seja: $1 dá pra rodar 125-330 perguntas. Sua conta nova no Axon com $0.50 grátis já dá pra testar bastante.

Por que Axon em vez de chamar BrasilAPI direto?

Nesse tutorial você poderia substituir call_axon por requests.get("https://brasilapi.com.br/...") e funcionaria. Então por que usar Axon?

Porque em produção real:

1. Você vai querer rate limiting — BrasilAPI limita rápido. Axon tem cache agressivo que reduz chamadas ao upstream em ~50-70%.
2. Você vai querer mais APIs — só a OpenAI já duplica o problema. Com 5+ APIs, gerenciar chaves vira pesadelo. Com Axon: 1 chave.
3. Você vai querer métricas — Axon dá dashboard com custo, latência, cache hit rate. Grátis.
4. Você vai querer trocar APIs — quer mudar de BrasilAPI paga pra Receita Federal direto? Muda um string. Sem refactor.

Próximos passos

1. Adicionar mais ferramentas

• feriados — saber se data é feriado nacional
• bancos — consultar código de banco
• ddd — listar cidades de um DDD

Todas disponíveis no brasilapi do Axon. É copiar uma das funções existentes e trocar o endpoint.

2. Deploy

Empacota em Docker + uvicorn com FastAPI, joga no Render (plano gratuito). Em 15 minutos vira API pública.

3. Interface

Plug no Telegram Bot, WhatsApp Business API, ou site simples. O agente mesmo não muda.

4. Memória de conversa

Troca o loop por LangChain com ConversationBufferMemory e o agente passa a lembrar perguntas anteriores.

Código completo

O template rodável tá em github.com/axondevi/axon/tree/main/templates/agente-brasil-py. Clona, roda pip install -r requirements.txt, configura .env, e pronto.

Se construir algo em cima disso, queremos ver. DM pra @axondevia ou email hello@axon.dev.