Agent Loop

Un agente de IA con seguridad opcional de intervención humana e integración del Protocolo de Contexto del Modelo (MCP).

Documentación

Agent Loop

Un Agente de IA con Seguridad Opcional de Humano en el Bucle, integración con el Protocolo de Contexto de Modelo (MCP) y una salida CLI hermosa y personalizable

Herramientas

Requisitos

Python: >= 3.12
Dependencias principales de 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 la instalación:
- uv (para instalación rápida de dependencias)
Opcional/para soporte completo de herramientas:
- Node.js (para algunas integraciones de servidores MCP, por ejemplo, Brave Search, Obsidian)
- Docker, Git, AWS CLI, kubectl, etc. (para soporte completo de herramientas)
Plataforma:
- Linux, macOS o Subsistema de Windows para Linux (WSL)
Claves de API (para funcionalidad completa):
- Clave de API de Anthropic (para modelos Claude)
- Clave de API de OpenAI (para modelos GPT)
- (Opcional) Claves de API de Jira y Confluence para esas integraciones

Descripción General

Agent Loop es un asistente de IA de línea de comandos. Aprovecha los modelos Claude de Anthropic o GPT de OpenAI y un conjunto de herramientas potentes para automatizar, inspeccionar y gestionar tu entorno de desarrollo, manteniéndote en control con confirmación humana opcional para cada acción.

Humano en el Bucle: Agrega --safe para requerir confirmación antes de que se ejecute cualquier herramienta.
Programación Funcional: Código limpio, componible y comprobable.
Listo para DevOps: Se integra con Bash, Python, Docker, Git, Kubernetes, AWS y más.
Multi-Proveedor: Soporta tanto modelos de Anthropic Claude como de OpenAI GPT.
Integración MCP: Carga y utiliza dinámicamente herramientas/servicios de cualquier servidor compatible con MCP (ver más abajo).

Estructura del Código

main.py — Bucle principal de eventos y orquestación
cli_input.py — Manejo de entrada del terminal (CTRL+C, CTRL+Q, retroceso, etc.)
signals.py — Manejo de señales (SIGINT para interrupción)
constants.py — Cadenas visibles para el usuario y mensajes de ayuda
exceptions.py — Excepciones personalizadas para salida limpia y manejo de errores

Todos los componentes están diseñados para la modularidad, el minimalismo y el estilo de programación funcional.

Control del Bucle y Detención Pragmática

Agent Loop incluye mecanismos inteligentes de detención para prevenir iteraciones descontroladas y uso excesivo de tokens:

Límites de Iteración

Iteraciones máximas: Límite duro configurable (predeterminado: 20) previene bucles infinitos
Visualización de progreso: Muestra el número de iteración actual en tiempo real
Configuración: Se establece mediante la variable de entorno MAX_ITERATIONS o la bandera CLI --max-iterations

Detección de Finalización

El agente detecta automáticamente cuándo una tarea está completa reconociendo:

Frases explícitas de finalización ("tarea completa", "terminado", "hecho")
Respuestas breves sin llamadas adicionales a herramientas
Agentes que proporcionan resúmenes sin solicitar más acciones

Cuando se detecta la finalización, el sistema te solicita confirmar antes de detenerse, permitiéndote:

Detener: Finalizar la sesión si la tarea está realmente completa
Continuar: Dar al agente más iteraciones si se necesita trabajo adicional

Detección de Repetición

Previene bucles infinitos detectando patrones sensibles a argumentos:

La misma herramienta con argumentos idénticos llamada 5+ veces consecutivas
Patrones alternantes con llamadas idénticas (por ejemplo, el mismo comando bash → la misma escritura de archivo → repetir...)
Secuencias repetidas de llamadas a herramientas con argumentos idénticos

Importante: La detección es sensible a argumentos, lo que significa:

✅ Llamar a bash con comandos diferentes (investigación legítima) está permitido
❌ Llamar a bash con el mismo comando 5+ veces está bloqueado

Esto previene falsos positivos mientras sigue capturando comportamientos de bloqueo reales.

Cuando se detecta repetición, el agente se detiene inmediatamente con una explicación clara.

Configuración

# 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

Guía del Prompt del Sistema

Se instruye al agente para:

Completar las tareas solicitadas con precisión y luego detenerse
Evitar mejoras "ya que estoy aquí"
No agregar características, documentación o pruebas no solicitadas
Proporcionar resúmenes cuando el trabajo esté completo en lugar de continuar

Esto asegura que el agente se mantenga enfocado en tu solicitud real y no desperdicie tokens en elaboraciones innecesarias.

Salida Elegante y Manejo de Señales

CTRL+C: Interrumpe la operación actual y regresa al prompt (no sale).
CTRL+D o escribir exit/quit en el prompt: Sale de la aplicación limpiamente, sin traceback ni error.
Solo SIGINT (CTRL+C) se maneja como señal para seguridad asíncrona; la salida se maneja en el prompt para un apagado robusto y seguro asíncronamente.

Soporte de LLM Consciente de Asincronía

Agent Loop soporta automáticamente funciones LLM tanto síncronas como asíncronas, asegurando rendimiento y compatibilidad óptimos. El bucle principal de eventos llamará a tu función LLM de la manera más eficiente, ya sea síncrona o asíncrona.

Características

Agente de IA conversacional impulsado por Anthropic Claude u OpenAI GPT
Proveedor de IA y temperatura configurables mediante variables de entorno
Control pragmático del bucle con límites de iteración y detección de finalización
Ejecución de herramientas con confirmación humana opcional (modo --safe)
Modo de depuración para transparencia (--debug)
Soporte de herramientas personalizadas con descubrimiento y visualización automáticos
Diferenciación visual de herramientas con iconos distintivos para herramientas integradas, MCP y personalizadas
Sistema de herramientas modular y extensible
Estilo de programación funcional en todo el código
Manejo de errores mejorado con información de diagnóstico detallada
Configuración flexible con prioridad del archivo local .env
Integración con MCP (Protocolo de Contexto de Modelo) para descubrimiento y uso de herramientas/servicios externos

Integración con MCP (Protocolo de Contexto de Modelo)

¡Nuevo en v2.0!

Agent Loop ahora puede conectarse a cualquier número de servidores compatibles con MCP, descubriendo y utilizando dinámicamente sus servicios como herramientas. Esto significa que puedes:

Agregar nuevas capacidades (búsqueda, conocimiento, automatización, etc.) simplemente ejecutando o configurando un servidor MCP.
Usar herramientas de servidores MCP remotos o locales como si fueran integradas.
Agregar servicios de múltiples fuentes (por ejemplo, Brave Search, Obsidian, servidores personalizados) en un solo agente.

ℹ️ El formato de configuración del servidor MCP es idéntico al utilizado por Cursor AI IDE. Consulta la documentación de MCP de Cursor para más detalles y opciones avanzadas.

Cómo funciona

Al iniciar, Agent Loop lee tu configuración de servidores MCP desde ~/.config/agent-loop/mcp.json.
Para cada servidor, inicia una sesión y lista los servicios disponibles.
Cada servicio se registra como una herramienta (nombrada <server>-<service>) y puede ser llamada por el agente o el usuario.
Todas las herramientas MCP están disponibles junto con las herramientas integradas.

Ejemplo de configuración 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/"]
    }
  }
}

Coloca este archivo en ~/.config/agent-loop/mcp.json.
Cada servidor puede ser un servicio local o remoto compatible con MCP.
Todos los servicios/herramientas de estos servidores estarán disponibles en tu sesión de agente.
Para más detalles, consulta la documentación de MCP de Cursor.

Herramientas Disponibles

Agent Loop viene con herramientas integradas y soporta herramientas personalizadas. La aplicación distingue automáticamente entre diferentes tipos de herramientas con indicadores visuales:

🛠️ Herramientas Integradas: Herramientas principales de la aplicación
🔌 Herramientas MCP: Herramientas externas de servidores del Protocolo de Contexto de Modelo
🔧 Herramientas Personalizadas: Herramientas definidas por el usuario cargadas desde ~/.config/agent-loop/tools/

Al iniciar, Agent Loop mostrará cualquier herramienta personalizada que se haya cargado:

🔧 [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

Herramienta	Descripción
bash	Ejecutar comandos bash
python	Evaluar código Python en un subproceso aislado
node	Evaluar código Node.js en un subproceso aislado
sympy	Realizar operaciones matemáticas simbólicas usando SymPy
cli_plot	Renderizar gráficos y diagramas avanzados de terminal usando plotext
filesystem	Leer, crear, actualizar, agregar, eliminar archivos con codificación UTF-8
list_dir	Listar el contenido de un directorio para descubrimiento rápido de archivos
codebase_search	Búsqueda semántica de código para fragmentos relevantes en el proyecto
file_search	Búsqueda difusa rápida de archivos por nombre o fragmento de ruta
grep_search	Buscar cadenas exactas o patrones regex en archivos
http	Realizar solicitudes HTTP usando HTTPie con manejo fácil de JSON
curl	Realizar solicitudes HTTP usando curl
git	Ejecutar comandos Git en el repositorio actual
docker	Ejecutar comandos CLI de Docker
project_inspector	Inspeccionar el directorio del proyecto actual y previsualizar archivos fuente
kubectl	Ejecutar comandos kubectl para interactuar con un clúster de Kubernetes
aws_cli	Ejecutar comandos de solo lectura de AWS CLI v2 para interactuar con servicios de AWS
jira	Consultar JIRA mediante API REST usando endpoints seguros de solo lectura
confluence	Consultar Atlassian Confluence Cloud mediante API REST (solo lectura)
MCP	Todos los servicios de servidores MCP configurados (ver arriba)
Personalizadas	Herramientas definidas por el usuario desde `~/.config/agent-loop/tools/`

Consulta la Guía de Creación de Herramientas para instrucciones sobre cómo crear tus propias herramientas.

Instalación

Opción 1: Usando el script de instalación (Recomendado)

Descarga el paquete de instalación:

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

Ejecuta el script de instalación:
```
./install.sh
```
Este script:
- Creará un entorno virtual en ~/.local/share/agent-loop/venv
- Instalará todas las dependencias requeridas
- Instalará el paquete agent-loop
- Creará un envoltorio de comando en ~/.local/bin/agent-loop

Agrega a tu PATH (si es necesario):

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

Opción 2: Instalación manual

Clona el repositorio:

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

Instala las dependencias:

Usando uv, un gestor de paquetes de Python mucho más rápido:
```
uv pip install -r requirements.txt
```
Si no tienes uv instalado, puedes instalarlo con:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Desinstalación

Para desinstalar Agent Loop, simplemente ejecuta:

./install.sh uninstall

Esto eliminará el envoltorio de comando y el entorno virtual.

Instalación en el Subsistema de Windows para Linux (WSL)

Agent Loop funciona muy bien en Windows a través de WSL. Así es como configurarlo:

Instala WSL si aún no lo tienes:
- Abre PowerShell como Administrador y ejecuta:
```
wsl --install
```
- Reinicia tu computadora después de que la instalación se complete
- Para instrucciones detalladas, consulta la guía de instalación de WSL de Microsoft
Instala Agent Loop en WSL:
- Abre tu terminal WSL
- Sigue las mismas instrucciones de instalación que arriba:
```
git clone https://github.com/your-org/agent-loop.git
cd agent-loop
./install.sh
```
Configuración en WSL:
- Crea el directorio de configuración en tu directorio de inicio de WSL:
```
mkdir -p ~/.config/agent-loop
```
- Agrega tus claves de API al archivo .env:
```
nano ~/.config/agent-loop/.env
```
- Opcional: Agrega un prompt de sistema personalizado:
```
nano ~/.config/agent-loop/SYSTEM_PROMPT.txt
```
Consideraciones específicas para WSL:
- El agent-loop puede acceder tanto a archivos de Linux como de Windows
- Los archivos de Windows están montados en /mnt/c/, /mnt/d/, etc.
- Para acceder a directorios de Windows, use rutas como /mnt/c/Users/YourName/Documents
- Para un mejor rendimiento, mantenga sus proyectos dentro del sistema de archivos de WSL

Configuración

Claves API y Variables de Entorno

Cree un archivo .env en el directorio ~/.config/agent-loop con sus claves API y otra configuración:

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

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

También puede crear un archivo .env local en el directorio de su proyecto, que tendrá prioridad sobre la configuración global.

Puede usar el archivo .env.example del repositorio fuente como plantilla. Como mínimo, incluya una de estas claves 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

Prioridad de Configuración:

Archivo .env local en su directorio actual (mayor prioridad)
Archivo .env global en ~/.config/agent-loop/ (respaldo)

Selección del Proveedor de IA:

Establezca AI_PROVIDER=anthropic para usar modelos Claude (predeterminado)
Establezca AI_PROVIDER=openai para usar modelos GPT
Si falta la clave API del proveedor preferido, la aplicación cambiará automáticamente al proveedor disponible

Control de Temperatura:

AI_TEMPERATURE controla la creatividad y aleatoriedad de las respuestas (0.0 = determinista, 1.0 = creativo)
Rango válido: 0.0 a 2.0
Predeterminado: 0.7 (equilibrado)

Prompt de Sistema Personalizado

Puede personalizar el prompt de sistema creando un archivo SYSTEM_PROMPT.txt en el mismo directorio:

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

Esto le permite dar instrucciones específicas o personalidad al asistente. Si este archivo no existe, se usará el prompt de sistema predeterminado.

Configuración del Servidor MCP

Para habilitar la integración MCP, cree un archivo en ~/.config/agent-loop/mcp.json como se muestra arriba. Cada entrada de servidor debe especificar el comando, los argumentos y cualquier variable de entorno requerida. Todos los servicios de estos servidores estarán disponibles como herramientas en su sesión de agente.

Uso

Básico

agent-loop

Selección de Modelo

agent-loop --model gpt-4o

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

Modo Seguro (Confirmación Humana)

agent-loop --safe

Se le mostrará cada comando y se le pedirá confirmación antes de ejecutarlo.

Modo Depuración

agent-loop --debug

Imprime la entrada/salida de las herramientas para mayor transparencia.

Combinado

agent-loop --safe --debug

Sesión de Ejemplo

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   ...

✨ Salida CLI Hermosa y Personalizable

Agent Loop usa Rich para renderizar todas las respuestas y notificaciones del agente en la terminal. De forma predeterminada, todas las respuestas del agente se formatean en Markdown y se renderizan con color, estilo y estructura para máxima legibilidad.

Predeterminado: Las respuestas se renderizan como Markdown (encabezados, listas, bloques de código, etc.)
Temas: Los colores y estilos son totalmente personalizables mediante un archivo de tema JSON
Modo Texto Plano: Use --simple-text o -s para deshabilitar Rich/Markdown y obtener salida ASCII pura (ideal para tuberías o terminales mínimas)

Ejemplo (Salida Markdown)

💬 Agent:
# Docker Containers

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

Ejemplo (Salida Texto Plano)

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

🎨 Personalización del Tema

Puede personalizar completamente la apariencia de la CLI editando el archivo de tema:

Ubicación: ~/.config/agent-loop/theme.json
Formato: Mapeo JSON de nombres de estilos a cadenas de estilo Rich
Respaldo: Si el archivo falta o es inválido, se usa un tema predeterminado hermoso

Ejemplo de theme.json:

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

¡Cambie colores, agregue énfasis o cree su propio estilo! Consulte la guía de estilos de Rich para ver las opciones.

🚀 Banderas de CLI

Banderas	Descripción
`--simple-text`, `-s`	Salida de texto ASCII plano (sin Rich, sin Markdown)
`--safe`	Requiere confirmación antes de ejecutar cualquier herramienta
`--debug`	Muestra la entrada/salida de las herramientas para transparencia
`--model`	Selecciona el modelo LLM (p. ej., `gpt-4o`, `claude-3-7-sonnet-latest`)
`--max-iterations N`	Establece los ciclos máximos de iteración del agente (predeterminado: 20)
`--no-prompt-on-completion`	Deshabilita la solicitud cuando se detecta finalización (auto-detención en su lugar)

🛠️ Creación de Sus Propias Herramientas

¡Agent Loop es totalmente extensible! Puede agregar sus propias herramientas en minutos, sin necesidad de modificar el código central.

Módulos Python de inserción directa (funciones puras, estilo de programación funcional)
Auto-descubrimiento: Simplemente coloque su archivo .py en agent_loop/tools/ (incorporado) o ~/.config/agent-loop/tools/ (herramientas de usuario)
Sin dependencias adicionales para herramientas de usuario—consulte la política en la guía

👉 Vea la guía completa: CREATING_TOOLS.md

Licencia

Este proyecto está licenciado bajo la Licencia Pública General Affero de GNU v3.0, con términos adicionales que prohíben el uso comercial y requieren atribución.

Consulte LICENSE para más detalles.