From 6a032c30722bcda64483681fe5c144b1093b514a Mon Sep 17 00:00:00 2001 From: webbrain-one <295484252+webbrain-one@users.noreply.github.com> Date: Wed, 29 Jul 2026 21:21:09 +0300 Subject: [PATCH] docs: add Spanish README --- README.es-ES.md | 228 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 README.es-ES.md diff --git a/README.es-ES.md b/README.es-ES.md new file mode 100644 index 0000000..ef3906c --- /dev/null +++ b/README.es-ES.md @@ -0,0 +1,228 @@ + + +# Agente de Ejecución de Código + +Una plantilla avanzada de Mastra que proporciona un agente de programación capaz de planificar, escribir, ejecutar e iterar código en entornos sandbox seguros y aislados, con capacidades integrales de gestión de archivos y flujos de trabajo de desarrollo. + +## Descripción general + +Esta plantilla demuestra cómo construir un asistente de programación con IA que puede trabajar con entornos de desarrollo reales. El agente puede crear sandbox, gestionar archivos y directorios, ejecutar código en múltiples lenguajes y monitorear flujos de trabajo de desarrollo, todo dentro de entornos sandbox seguros y aislados. + +## Características + +- **Ejecución segura de código**: Ejecuta código en Python, JavaScript y TypeScript en sandbox aislados +- **Gestión completa de archivos**: Crea, lee, escribe y elimina archivos y directorios con operaciones por lotes +- **Soporte multilingüe**: Ejecuta código en entornos de Python, JavaScript y TypeScript +- **Monitoreo en tiempo real del desarrollo**: Observa cambios en directorios y monitorea flujos de trabajo de desarrollo +- **Ejecución de comandos**: Ejecuta comandos de shell, instala paquetes y gestiona dependencias +- **Sistema de memoria**: Memoria de conversación persistente con recuperación semántica y memoria de trabajo +- **Flujos de trabajo de desarrollo**: Patrones profesionales de desarrollo con automatización de compilación + +## Requisitos previos + +- Node.js 22.13.0 o posterior +- Clave API para tu proveedor de sandbox elegido ([Daytona](https://www.daytona.io/) o [E2B](https://e2b.dev)) +- Clave API para tu proveedor de modelos elegido + +## Configuración + +1. **Clona e instala las dependencias:** + + ```bash + git clone https://github.com/mastra-ai/template-coding-agent.git + cd template-coding-agent + pnpm install + ``` + +2. **Configura las variables de entorno:** + + ```bash + cp .env.example .env + # Edit .env and add your API keys + ``` + + **Elige tu proveedor de sandbox** estableciendo la clave API correspondiente: + + ```env + # Option 1: Use Daytona (set DAYTONA_API_KEY) + DAYTONA_API_KEY="your-daytona-api-key-here" + + # Option 2: Use E2B (set E2B_API_KEY) + # E2B_API_KEY="your-e2b-api-key-here" + + + # Model provider (required) + OPENAI_API_KEY="your-openai-api-key-here" + ``` + + **Nota:** Establece solo UNA clave API de proveedor de sandbox. El agente utilizará automáticamente el proveedor que configures. + +3. **Inicia el servidor de desarrollo:** + + ```bash + pnpm run dev + ``` + +## Configuración del modelo + +Esta plantilla es compatible con cualquier proveedor de modelos de IA a través del enrutador de modelos de Mastra. Puedes utilizar modelos de: + +- **OpenAI**: `openai/gpt-4o-mini`, `openai/gpt-4o` +- **Anthropic**: `anthropic/claude-sonnet-4-5-20250929`, `anthropic/claude-haiku-4-5-20250929` +- **Google**: `google/gemini-2.5-pro`, `google/gemini-2.0-flash-exp` +- **Groq**: `groq/llama-3.3-70b-versatile`, `groq/llama-3.1-8b-instant` +- **Cerebras**: `cerebras/llama-3.3-70b` +- **Mistral**: `mistral/mistral-medium-2508` + +Establece la variable de entorno `MODEL` en tu archivo `.env` con el modelo que prefieras. + +## Arquitectura + +### Componentes principales + +#### **Agente de Código** (`src/mastra/agents/coding-agent.ts`) + +El agente principal con capacidades integrales de desarrollo: + +- **Gestión de Sandbox**: Crea y gestiona entornos de ejecución aislados +- **Ejecución de código**: Ejecuta código con captura de salida en tiempo real +- **Operaciones de archivos**: Operaciones CRUD completas para archivos y directorios +- **Monitoreo de desarrollo**: Observa cambios y monitorea flujos de trabajo +- **Integración de memoria**: Mantiene el contexto de la conversación y el historial del proyecto + +#### **Herramientas de Sandbox** (`src/mastra/tools/`) + +Kit de herramientas completo para la interacción con sandbox con soporte para múltiples proveedores: + +**Selección de proveedor:** + +- Utiliza automáticamente **Daytona** o **E2B** según la clave API que configures + +**Gestión de Sandbox:** + +- `createSandbox` - Inicializa nuevos entornos aislados +- Gestión de conexiones con manejo de tiempo de espera (timeout) + +**Ejecución de código:** + +- `runCode` - Ejecuta código en Python, JavaScript y TypeScript +- Captura de salida en tiempo real y manejo de errores +- Configuración de variables de entorno y timeout + +**Operaciones de archivos:** + +- `writeFile` - Crea archivos individuales +- `writeFiles` - Crea en lote múltiples archivos para la configuración del proyecto +- `readFile` - Lee el contenido de archivos para análisis y validación +- `listFiles` - Explora estructuras de directorios +- `deleteFile` - Limpia archivos y directorios +- `createDirectory` - Configura estructuras de proyecto + +**Información y monitoreo de archivos:** + +- `getFileInfo` - Obtiene metadatos detallados del archivo +- `checkFileExists` - Valida la existencia del archivo para lógica condicional +- `getFileSize` - Monitorea tamaños de archivos y rastrea cambios +- `watchDirectory` - Monitoreo en vivo de cambios en el sistema de archivos + +**Flujo de trabajo de desarrollo:** + +- `runCommand` - Ejecuta comandos de shell, scripts de compilación y gestión de paquetes + +### Sistema de memoria + +El agente incluye un sistema de memoria configurado: + +- **Gestión de hilos**: Generación automática de títulos de conversación +- **Recuperación semántica**: Búsqueda en interacciones anteriores +- **Memoria de trabajo**: Mantiene el contexto entre interacciones +- **Almacenamiento vectorial**: Capacidades de búsqueda semántica con `LibSQLVector` + +## Configuración + +### Variables de entorno + +**Proveedor de Sandbox (elige uno):** + +```bash +# Option 1: Daytona +DAYTONA_API_KEY=your_daytona_api_key_here + +# Option 2: E2B +E2B_API_KEY=your_e2b_api_key_here + +``` + +> [!Note] +> El agente detectará y utilizará automáticamente el proveedor de sandbox según la clave API que configures. + +**Proveedor de modelo (requerido):** + +```bash +OPENAI_API_KEY=your_openai_api_key_here +``` + +### Personalización + +Puedes personalizar el comportamiento del agente modificando las instrucciones en `src/mastra/agents/coding-agent.ts`: + +```typescript +export const codingAgent = new Agent({ + id: 'coding-agent', + name: 'Coding Agent', + instructions: ` + // Customize agent instructions here + // Focus on specific languages, frameworks, or development patterns + `, + model: openai('gpt-4.1'), + // ... other configuration +}); +``` + +## Problemas comunes + +### "Please set either DAYTONA_API_KEY or E2B_API_KEY environment variable" + +- Debes configurar un proveedor de sandbox estableciendo una de las claves API +- Agrega `DAYTONA_API_KEY` o `E2B_API_KEY` a tu archivo `.env` +- Establece solo UNA clave API de proveedor (no ambas) +- Reinicia el servidor de desarrollo después de agregar la clave + +### "Sandbox creation failed" + +- Verifica tu clave API del proveedor de sandbox y el estado de tu cuenta +- Asegúrate de no haber excedido los límites de sandbox para tu proveedor +- Verifica la conectividad de red a los servicios de tu proveedor de sandbox + +### "Code execution timeout" + +- Aumenta los valores de timeout para operaciones de larga duración +- Divide las operaciones complejas en pasos más pequeños +- Monitorea el uso de recursos y optimiza el código + +### "File operation errors" + +- Valida las rutas de archivos y los permisos +- Verifica los límites del sistema de archivos del sandbox +- Asegúrate de que los directorios existan antes de realizar operaciones con archivos + +### "Agent stopping with tool-call reason" + +- Aumenta `maxSteps` en la configuración del agente + +## Desarrollo + +### Estructura del proyecto + +```text +src/mastra/ + agents/ + coding-agent.ts # Main coding agent with development capabilities + tools/ + index.ts # Provider-agnostic tool exports + e2b.ts # E2B sandbox implementation + daytona/ + tools.ts # Daytona sandbox implementation + utils.ts # Daytona helper functions + index.ts # Mastra configuration with storage and logging +```