Como construir agentes de terminal com Python e Ollama — sem pagar nada

Crie agentes de terminal com Python e Ollama — sem pagar nada

Agentes de CLI (Command-Line Interface) são a evolução mais recente das ferramentas de desenvolvimento. Eles combinam o poder dos LLMs com acesso direto ao terminal, sistema de arquivos e ferramentas externas do computador — tudo sem precisar de interface web.

O melhor: você pode construir o seu próprio agente de terminal completamente offline e gratuito, usando Python e Ollama com modelos open-source como Llama 3, Mistral ou Qwen.

Prós e Contras

✅ O que você ganha:

• Execução 100% local — sem enviar código ou dados para APIs de terceiros
• Custo zero de API — sem limites de tokens ou faturas surpresa
• Latência previsível — sem filas de API ou rate limiting
• Personalização total — escolha o modelo, ajuste o prompt, integre com qualquer ferramenta
• Privacidade garantida — código proprietário nunca sai da sua máquina

⚠️ Limitações:

• Modelos locais são menos capazes que GPT-4 ou Claude em tarefas complexas
• Requer hardware com pelo menos 8 GB de RAM para modelos de 7B parâmetros
• Não substitui agentes de coding completos como Claude Code ou GitHub Copilot

Requisitos

Passo a passo

1. Instale o Ollama

No Linux:

curl -fsSL https://ollama.com/install.sh | sh

No macOS, baixe o app em ollama.com. No Windows, use WSL2.

2. Baixe um modelo

ollama pull llama3.1:8b

Você pode usar qualquer modelo compatível: mistral, qwen2.5:14b, deepseek-coder:6.7b.

3. Estruture o agente em Python

O coração do agente é um loop que recebe comandos do usuário, envia para o LLM com o contexto do terminal, e executa as ações retornadas. Use a biblioteca ollama para Python:

import ollama
import subprocess

def run_command(cmd):
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    return result.stdout + result.stderr

def agent_loop():
    messages = [{"role": "system", "content": "Você é um agente CLI..."}]
    while True:
        user_input = input("> ")
        messages.append({"role": "user", "content": user_input})
        response = ollama.chat(model="llama3.1:8b", messages=messages)
        print(response["message"]["content"])

4. Adicione acesso ao sistema de arquivos

Expanda o agente com funções que permitam ler e escrever arquivos, listar diretórios e executar comandos shell — sempre com confirmação do usuário para operações destrutivas.

Troubleshooting

• ❌ Ollama não encontra o modelo: execute ollama list para verificar modelos instalados.
• ❌ Resposta muito lenta: use modelo menor (llama3.2:3b) ou ative aceleração GPU com ollama serve.
• ❌ Erro de memória: feche outros aplicativos; modelos 7B precisam de ~5 GB livres.
• ❌ Agente executa comandos perigosos: sempre use allowlist de comandos permitidos e confirmação explícita.
• ❌ Encoding quebrado no terminal: use encoding='utf-8' no subprocess.run().

FAQ

Preciso de GPU? Não. Modelos de 7B-8B rodam em CPU com performance aceitável (3-8 tokens/s).

Posso usar em produção? Para tarefas internas e automação de desenvolvimento, sim. Para produtos voltados ao cliente, modelos locais exigem mais engenharia de confiabilidade.

Qual a diferença para Claude Code? Claude Code é um produto completo com integrações profundas. O agente local é mais simples, mas totalmente privado e customizável.

Funciona no Windows? Sim, via WSL2. O Ollama para Windows está em preview.

Posso usar modelos via API também? Sim. O padrão de código é o mesmo — troque ollama.chat() por openai.ChatCompletion() e aponte para qualquer endpoint compatível.

O futuro dos agentes CLI

Com a aceleração dos modelos open-source e a redução dos requisitos de hardware, agentes CLI locais estão se tornando viáveis para qualquer desenvolvedor. Em 2027, é provável que ter um agente de terminal pessoal seja tão comum quanto ter um editor de código — e a curva começa agora.