Agent Loop

Um Agente de IA com Segurança opcional de Humano no Circuito e integração ao Protocolo de Contexto de Modelo (MCP).

Documentação

Agent Loop

Um Agente de IA com Segurança Humana no Circuito opcional, integração com Model Context Protocol (MCP) e saída de CLI bonita e personalizável

Ferramentas

Requisitos

Python: >= 3.12
Dependências principais do Python:
- anthropic >= 0.51.0
- halo >= 0.0.31
- mcp[cli] >= 1.9.2
- openai >= 1.79.0
- plotext >= 5.3.2
- python-dotenv >= 1.1.0
- requests >= 2.32.3
- sympy >= 1.14.0
Recomendado para instalação:
- uv (para instalação rápida de dependências)
Opcional/para suporte completo de ferramentas:
- Node.js (para algumas integrações de servidor MCP, ex.: Brave Search, Obsidian)
- Docker, Git, AWS CLI, kubectl, etc. (para suporte completo de ferramentas)
Plataforma:
- Linux, macOS ou Subsistema Windows para Linux (WSL)
Chaves de API (para funcionalidade completa):
- Chave de API da Anthropic (para modelos Claude)
- Chave de API da OpenAI (para modelos GPT)
- (Opcional) Chaves de API do Jira e Confluence para essas integrações

Visão Geral

O Agent Loop é um assistente de IA de linha de comando. Ele utiliza os modelos Claude da Anthropic ou GPT da OpenAI e um conjunto de ferramentas poderosas para automatizar, inspecionar e gerenciar seu ambiente de desenvolvimento—mantendo você no controle com confirmação humana opcional para cada ação.

Humano no circuito: Adicione --safe para exigir confirmação antes de qualquer ferramenta ser executada.
Programação Funcional: Código limpo, componível e testável.
Pronto para DevOps: Integra-se com Bash, Python, Docker, Git, Kubernetes, AWS e mais.
Multi-Provedor: Suporta tanto os modelos Claude da Anthropic quanto os GPT da OpenAI.
Integração MCP: Carrega e usa dinamicamente ferramentas/serviços de qualquer servidor compatível com MCP (veja abaixo).

Estrutura do Código

main.py — Loop de eventos principal e orquestração
cli_input.py — Tratamento de entrada do terminal (CTRL+C, CTRL+Q, backspace, etc.)
signals.py — Tratamento de sinais (SIGINT para interrupção)
constants.py — Strings voltadas ao usuário e mensagens de ajuda
exceptions.py — Exceções personalizadas para saída limpa e tratamento de erros

Todos os componentes são projetados para modularidade, minimalismo e estilo de programação funcional.

Controle de Loop e Parada Pragmática

O Agent Loop inclui mecanismos inteligentes de parada para evitar iterações descontroladas e uso excessivo de tokens:

Limites de Iteração

Máximo de iterações: Limite rígido configurável (padrão: 20) evita loops infinitos
Exibição de progresso: Mostra a contagem atual de iterações em tempo real
Configuração: Defina via variável de ambiente MAX_ITERATIONS ou flag de CLI --max-iterations

Detecção de Conclusão

O agente detecta automaticamente quando uma tarefa está concluída reconhecendo:

Frases explícitas de conclusão ("tarefa concluída", "finalizado", "pronto")
Respostas breves sem chamadas adicionais de ferramentas
Agente fornecendo resumos sem solicitar mais ações

Quando a conclusão é detectada, o sistema solicita que você confirme antes de parar, permitindo que você:

Parar: Encerrar a sessão se a tarefa estiver realmente concluída
Continuar: Dar mais iterações ao agente se trabalho adicional for necessário

Detecção de Repetição

Evita loops infinitos detectando padrões conscientes de argumentos:

Mesma ferramenta com argumentos idênticos chamada 5+ vezes consecutivas
Padrões alternados com chamadas idênticas (ex.: mesmo comando bash → mesma escrita de arquivo → repetir...)
Sequências repetidas de chamadas de ferramentas com argumentos idênticos

Importante: A detecção é consciente de argumentos, ou seja:

✅ Chamar bash com comandos diferentes (investigação legítima) é permitido
❌ Chamar bash com o mesmo comando 5+ vezes é bloqueado

Isso evita falsos positivos enquanto ainda captura comportamentos realmente travados.

Quando a repetição é detectada, o agente para imediatamente com uma explicação clara.

Configuração

# In ~/.config/agent-loop/.env or local .env
MAX_ITERATIONS=20              # Maximum thinking cycles
PROMPT_ON_COMPLETION=true      # Ask before stopping on completion

# Via CLI
agent-loop --max-iterations 50                # Override iteration limit
agent-loop --no-prompt-on-completion          # Auto-stop without prompting

Orientação do Prompt do Sistema

O agente é instruído a:

Concluir as tarefas solicitadas com precisão e depois parar
Evitar melhorias do tipo "já que estou aqui"
Não adicionar recursos, documentação ou testes não solicitados
Fornecer resumos quando o trabalho estiver concluído em vez de continuar

Isso garante que o agente permaneça focado na sua solicitação real e não desperdice tokens com elaborações desnecessárias.

Saída Graciosa e Tratamento de Sinais

CTRL+C: Interrompe a operação atual e retorna ao prompt (não sai).
CTRL+D ou digitar exit/quit no prompt: Sai do aplicativo de forma limpa, sem traceback ou erro.
Apenas SIGINT (CTRL+C) é tratado como sinal para segurança assíncrona; a saída é tratada no prompt para um desligamento robusto e seguro em relação a assincronia.

Suporte a LLM Ciente de Assincronia

O Agent Loop suporta automaticamente funções de LLM síncronas e assíncronas, garantindo desempenho e compatibilidade ideais. O loop de eventos principal chamará sua função de LLM da maneira mais eficiente, seja ela síncrona ou assíncrona.

Recursos

Agente de IA conversacional alimentado por Anthropic Claude ou OpenAI GPT
Provedor de IA e temperatura configuráveis via variáveis de ambiente
Controle de loop pragmático com limites de iteração e detecção de conclusão
Execução de ferramentas com confirmação humana opcional (modo --safe)
Modo de depuração para transparência (--debug)
Suporte a ferramentas personalizadas com descoberta e exibição automáticas
Diferenciação visual de ferramentas com ícones distintos para ferramentas integradas, MCP e personalizadas
Sistema de ferramentas modular e extensível
Estilo de programação funcional em todo o projeto
Tratamento de erros aprimorado com informações detalhadas de diagnóstico
Configuração flexível com prioridade para o arquivo local .env
Integração MCP (Model Context Protocol) para descoberta e uso de ferramentas/serviços externos

Integração MCP (Model Context Protocol)

Novo na v2.0!

O Agent Loop agora pode se conectar a qualquer número de servidores compatíveis com MCP, descobrindo e usando dinamicamente seus serviços como ferramentas. Isso significa que você pode:

Adicionar novas capacidades (busca, conhecimento, automação, etc.) simplesmente executando ou configurando um servidor MCP.
Usar ferramentas de servidores MCP remotos ou locais como se fossem integradas.
Agregar serviços de múltiplas fontes (ex.: Brave Search, Obsidian, servidores personalizados) em um único agente.

ℹ️ O formato de configuração do servidor MCP é idêntico ao usado pelo Cursor AI IDE. Consulte a documentação MCP do Cursor para mais detalhes e opções avançadas.

Como funciona

Na inicialização, o Agent Loop lê sua configuração de servidor MCP de ~/.config/agent-loop/mcp.json.
Para cada servidor, ele inicia uma sessão e lista os serviços disponíveis.
Cada serviço é registrado como uma ferramenta (nomeada <server>-<service>) e pode ser chamado pelo agente ou pelo usuário.
Todas as ferramentas MCP estão disponíveis junto com as ferramentas integradas.

Exemplo de configuração MCP

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "..." }
    },
    "mcp-obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-obsidian", "/path/to/obsidian-vault/"]
    }
  }
}

Coloque este arquivo em ~/.config/agent-loop/mcp.json.
Cada servidor pode ser um serviço local ou remoto compatível com MCP.
Todos os serviços/ferramentas desses servidores estarão disponíveis na sua sessão de agente.
Para mais detalhes, consulte a documentação MCP do Cursor.

Ferramentas Disponíveis

O Agent Loop vem com ferramentas integradas e suporta ferramentas personalizadas. O aplicativo distingue automaticamente entre diferentes tipos de ferramentas com indicadores visuais:

🛠️ Ferramentas Integradas: Ferramentas principais do aplicativo
🔌 Ferramentas MCP: Ferramentas externas de servidores Model Context Protocol
🔧 Ferramentas Personalizadas: Ferramentas definidas pelo usuário carregadas de ~/.config/agent-loop/tools/

Na inicialização, o Agent Loop exibirá quaisquer ferramentas personalizadas que tenham sido carregadas:

🔧 [Custom Tools] Loaded 2 custom tool(s) from ~/.config/agent-loop/tools:
  • hello (hello.py) - Returns a friendly greeting
  • my_tool (my_tool.py) - Custom automation tool

Ferramenta	Descrição
bash	Executar comandos bash
python	Avaliar código Python em um subprocesso isolado
node	Avaliar código Node.js em um subprocesso isolado
sympy	Realizar operações matemáticas simbólicas usando SymPy
cli_plot	Renderizar gráficos e plotagens avançados no terminal usando plotext
filesystem	Ler, criar, atualizar, anexar, excluir arquivos com codificação UTF-8
list_dir	Listar o conteúdo de um diretório para descoberta rápida de arquivos
codebase_search	Busca semântica de código para trechos relevantes no projeto
file_search	Busca difusa rápida de arquivos por nome ou fragmento de caminho
grep_search	Buscar strings exatas ou padrões regex em arquivos
http	Fazer requisições HTTP usando HTTPie com fácil manipulação de JSON
curl	Fazer requisições HTTP usando curl
git	Executar comandos Git no repositório atual
docker	Executar comandos da CLI do Docker
project_inspector	Inspecionar o diretório do projeto atual e pré-visualizar arquivos de código
kubectl	Executar comandos kubectl para interagir com um cluster Kubernetes
aws_cli	Executar comandos somente leitura da AWS CLI v2 para interagir com serviços AWS
jira	Consultar JIRA via API REST usando endpoints seguros e somente leitura
confluence	Consultar Atlassian Confluence Cloud via API REST (somente leitura)
MCP	Todos os serviços de servidores MCP configurados (veja acima)
Custom	Ferramentas definidas pelo usuário de `~/.config/agent-loop/tools/`

Consulte o Guia de Criação de Ferramentas para instruções sobre como criar suas próprias ferramentas.

Instalação

Opção 1: Usando o script de instalação (Recomendado)

Baixe o pacote de instalação:

git clone https://github.com/your-org/agent-loop.git
cd agent-loop

Execute o script de instalação:
```
./install.sh
```
Este script irá:
- Criar um ambiente virtual em ~/.local/share/agent-loop/venv
- Instalar todas as dependências necessárias
- Instalar o pacote agent-loop
- Criar um wrapper de comando em ~/.local/bin/agent-loop

Adicione ao seu PATH (se necessário):

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc

Opção 2: Instalação manual

Clone o repositório:

git clone https://github.com/your-org/agent-loop.git
cd agent-loop

Instale as dependências:

Usando uv, um gerenciador de pacotes Python muito mais rápido:
```
uv pip install -r requirements.txt
```
Se você não tiver o uv instalado, pode instalá-lo com:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Desinstalação

Para desinstalar o Agent Loop, basta executar:

./install.sh uninstall

Isso removerá o wrapper de comando e o ambiente virtual.

Instalação no Subsistema Windows para Linux (WSL)

O Agent Loop funciona muito bem no Windows através do WSL. Veja como configurá-lo:

Instale o WSL se você ainda não o tiver:
- Abra o PowerShell como Administrador e execute:
```
wsl --install
```
- Reinicie o computador após a conclusão da instalação
- Para instruções detalhadas, consulte o guia de instalação do WSL da Microsoft
Instale o Agent Loop no WSL:
- Abra seu terminal WSL
- Siga as mesmas instruções de instalação acima:
```
git clone https://github.com/your-org/agent-loop.git
cd agent-loop
./install.sh
```
Configuração no WSL:
- Crie o diretório de configuração no seu home do WSL:
```
mkdir -p ~/.config/agent-loop
```
- Adicione suas chaves de API ao arquivo .env:
```
nano ~/.config/agent-loop/.env
```
- Opcional: Adicione um prompt de sistema personalizado:
```
nano ~/.config/agent-loop/SYSTEM_PROMPT.txt
```
Considerações específicas do WSL:
- O agent-loop pode acessar arquivos tanto do Linux quanto do Windows
- Arquivos do Windows são montados em /mnt/c/, /mnt/d/, etc.
- Para acessar diretórios do Windows, use caminhos como /mnt/c/Users/YourName/Documents
- Para melhor desempenho, mantenha seus projetos dentro do sistema de arquivos do WSL

Configuração

Chaves de API e Variáveis de Ambiente

Crie um arquivo .env no diretório ~/.config/agent-loop com suas chaves de API e outras configurações:

# Create the config directory if it doesn't exist
mkdir -p ~/.config/agent-loop

# Create your .env file
nano ~/.config/agent-loop/.env

Você também pode criar um arquivo .env local no diretório do seu projeto, que terá prioridade sobre a configuração global.

Você pode usar o arquivo .env.example do repositório de origem como modelo. No mínimo, inclua uma destas chaves de API:

# AI Configuration
AI_PROVIDER=anthropic  # Choose: anthropic (default) or openai
AI_TEMPERATURE=0.7     # Model temperature: 0.0-2.0 (default: 0.7)

# Anthropic
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_MODEL=claude-sonnet-4-20250514  # Optional, defaults to claude-3-7-sonnet-latest

# OpenAI
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4o  # Optional, defaults to gpt-4o

# Jira (Optional)
JIRA_BASE_URL=your_jira_instance_url
JIRA_EMAIL=your_jira_email
JIRA_API_TOKEN=your_jira_api_token

# Confluence (Optional)
CONFLUENCE_BASE_URL=your_confluence_instance_url
CONFLUENCE_EMAIL=your_confluence_email
CONFLUENCE_API_TOKEN=your_confluence_api_token

Prioridade de Configuração:

Arquivo .env local no seu diretório atual (prioridade mais alta)
Arquivo .env global em ~/.config/agent-loop/ (fallback)

Seleção de Provedor de IA:

Defina AI_PROVIDER=anthropic para usar modelos Claude (padrão)
Defina AI_PROVIDER=openai para usar modelos GPT
Se a chave de API do provedor preferido estiver ausente, o aplicativo usará automaticamente o provedor disponível

Controle de Temperatura:

AI_TEMPERATURE controla a criatividade e a aleatoriedade das respostas (0.0 = determinístico, 1.0 = criativo)
Intervalo válido: 0.0 a 2.0
Padrão: 0.7 (equilibrado)

Prompt de Sistema Personalizado

Você pode personalizar o prompt do sistema criando um arquivo SYSTEM_PROMPT.txt no mesmo diretório:

nano ~/.config/agent-loop/SYSTEM_PROMPT.txt

Isso permite dar instruções específicas ou personalidade ao assistente. Se este arquivo não existir, o prompt de sistema padrão será usado.

Configuração do Servidor MCP

Para habilitar a integração MCP, crie um arquivo em ~/.config/agent-loop/mcp.json como mostrado acima. Cada entrada de servidor deve especificar o comando, os argumentos e quaisquer variáveis de ambiente necessárias. Todos os serviços desses servidores estarão disponíveis como ferramentas na sua sessão de agente.

Uso

Básico

agent-loop

Seleção de Modelo

agent-loop --model gpt-4o

agent-loop --model claude-3-7-sonnet-latest

Modo Seguro (Confirmação Humana)

agent-loop --safe

Cada comando será exibido e você será solicitado a confirmar antes da execução.

Modo de Depuração

agent-loop --debug

Exibe entrada/saída das ferramentas para transparência.

Combinado

agent-loop --safe --debug

Exemplo de Sessão

dev@agent-loop:~$ agent-loop --safe
> List all Docker containers
Agent: I will use the docker tool to list all containers.
[CONFIRMATION REQUIRED]
Tool: docker
Description: Run Docker CLI commands
Input: {'args': 'ps -a'}
Do you want to execute this command? [y/N]: y
STDOUT:
CONTAINER ID   IMAGE   ...

✨ Saída CLI Bonita e Personalizável

O Agent Loop usa Rich para renderizar todas as respostas e notificações do agente no terminal. Por padrão, todas as respostas do agente são formatadas em Markdown e renderizadas com cor, estilo e estrutura para máxima legibilidade.

Padrão: As respostas são renderizadas como Markdown (títulos, listas, blocos de código, etc.)
Temas: Cores e estilos são totalmente personalizáveis por meio de um arquivo de tema JSON
Modo Texto Simples: Use --simple-text ou -s para desativar Rich/Markdown e obter saída ASCII pura (ótimo para pipes ou terminais mínimos)

Exemplo (Saída Markdown)

💬 Agent:
# Docker Containers

| CONTAINER ID | IMAGE | STATUS |
|--------------|-------|--------|
| 123abc       | nginx | Up     |
| ...          | ...   | ...    |

Exemplo (Saída em Texto Simples)

💬 Agent:
Docker Containers
----------------
CONTAINER ID   IMAGE   STATUS
123abc         nginx   Up
...            ...     ...

🎨 Personalizando o Tema

Você pode personalizar totalmente a aparência da CLI editando o arquivo de tema:

Localização: ~/.config/agent-loop/theme.json
Formato: JSON mapeando nomes de estilos para strings de estilo Rich
Fallback: Se o arquivo estiver ausente ou for inválido, um belo tema padrão é usado

Exemplo theme.json:

{
  "agent.reply": "bold cyan",
  "agent.tool": "bold magenta",
  "agent.confirm": "bold yellow",
  "agent.error": "bold red",
  "agent.info": "dim white"
}

Altere cores, adicione ênfase ou crie seu próprio estilo! Consulte o guia de estilos do Rich para ver as opções.

🚀 Flags da CLI

Flag	Descrição
`--simple-text`, `-s`	Saída de texto ASCII puro (sem Rich, sem Markdown)
`--safe`	Exigir confirmação antes de executar qualquer ferramenta
`--debug`	Mostrar entrada/saída das ferramentas para transparência
`--model`	Selecionar o modelo LLM (ex.: `gpt-4o`, `claude-3-7-sonnet-latest`)
`--max-iterations N`	Definir o número máximo de ciclos de iteração do agente (padrão: 20)
`--no-prompt-on-completion`	Desativar a solicitação quando a conclusão for detectada (parada automática em vez disso)

🛠️ Criando Suas Próprias Ferramentas

O Agent Loop é totalmente extensível! Você pode adicionar suas próprias ferramentas em minutos—sem necessidade de modificar o código principal.

Módulos Python plug-and-play (funções puras, estilo de programação funcional)
Descoberta automática: Basta colocar seu arquivo .py em agent_loop/tools/ (integrado) ou ~/.config/agent-loop/tools/ (ferramentas do usuário)
Sem dependências extras para ferramentas do usuário—consulte a política no guia

👉 Veja o guia completo: CREATING_TOOLS.md

Licença

Este projeto é licenciado sob a GNU Affero General Public License v3.0, com termos adicionais que proíbem uso comercial e exigem atribuição.

Consulte LICENSE para obter detalhes completos.