Acceso a archivos en agente IA local: herramientas

Acceso a Archivos para Agentes IA Locales: Herramientas y Correcciones

Nuestro agente IA local, Doka, ahora tiene capacidades de acceso a archivos, pero no antes de corregir un error crítico en la caché KV de llama.cpp. El prompt del sistema empezaba con Session started: ${new Date().toISOString()}, que cambiaba en cada iteración. Esto invalidaba toda la caché: el modelo recalculaba 2000 tokens del prompt desde cero en 10 iteraciones, desperdiciando 20.000 tokens extra.

Mover la marca de tiempo al final del prompt o del turno del usuario restauró la caché. Las tareas multistep se aceleraron 2–3 veces en bucles con 8+ iteraciones. Este patrón sigue las recomendaciones de Anthropic para Claude, pero es crucial también para modelos locales.

Acceso Seguro a Archivos con Puertas de Permiso

Las herramientas de lectura de archivos son sencillas, pero la escritura necesita salvaguardas. Cada herramienta en la caja de herramientas tiene una bandera dangerous:

const fileTools: Tool[] = [
  {
    name: 'read_file',
    dangerous: false,
  },
  {
    name: 'write_file',
    dangerous: true,
  },
  {
    name: 'edit_file',
    dangerous: true,
  },
  {
    name: 'delete_file',
    dangerous: true,
  },
];

Cuando se invoca una herramienta peligrosa, aparece un diálogo que muestra los argumentos: ruta y contenido (primeros 500 caracteres). El botón "Permitir" no es el predeterminado. Las denegaciones devuelven un error al agente:

{
  "error": "El usuario denegó permiso para write_file",
  "canRetry": false,
  "suggestion": "Pide al usuario que confirme la ruta del archivo prevista"
}

Conjunto Completo de Herramientas de Archivos

Hemos implementado seis herramientas:

• read_file(path: string): string
• write_file(path: string, content: string): void (peligrosa)
• edit_file(path: string, instruction: string): void (peligrosa)
• list_dir(path: string): FileEntry[]
• move_file(from: string, to: string): void (peligrosa)
• delete_file(path: string): void (peligrosa)

edit_file aplica un parche basado en la instrucción (leer → parchear → escribir → verificar), evitando pasar archivos grandes por el contexto.

Corrección de Errores Relacionados con Rutas

El agente confundía archivos con nombres iguales en directorios distintos por rutas relativas. La solución:

• Directorio de trabajo predeterminado especificado en el prompt del sistema.
• Validación de rutas: salir de los límites activa un error.
• Instrucción: preguntar al usuario si las rutas son ambiguas.

El error apareció en las pruebas 3–4: el agente eligió notes.md de la raíz en lugar de la carpeta objetivo.

Tras write_file o edit_file, agregamos verificación automática: una comprobación read_file automática. Esto añade un paso pero previene fallos silenciosos (permisos, problemas de disco). MAX_TOOL_STEPS aumentado a 12 para plan + leer + escribir + verificar.

Línea de Tiempo del Agente para Transparencia

Los usuarios se quejaban del "caja negra": tres minutos de espera sin insight en los pasos. Agregamos un registro en la barra lateral:

• Llamadas a herramientas con argumentos.
• Resultados.
• Marcas de tiempo.

Flujos de eventos (tool_call_start / tool_call_end) se renderizan en React en tiempo real. Esencial para acceso a archivos: los usuarios ven rutas y operaciones exactas.

Errores Estructurados y Lógica de Reintento

Antes, los errores volcaban trazas de pila de Node.js, llevando a reintentos infinitos o alucinaciones. Ahora están estructurados:

{
  "error": "Archivo no encontrado: /path/to/file.md",
  "canRetry": false,
  "suggestion": "Verifica si la ruta es correcta con list_dir primero"
}

canRetry reduce bucles inútiles. True para timeouts de red, false para archivos inexistentes.

Prompt del Sistema Reestructurado

El prompt del sistema ahora está seccionado:

• Rol y Límites: Capacidades y restricciones.
• Reglas Prioritarias: Seguridad > precisión > velocidad.
• Formato de Respuesta: Estructura para tipos distintos.
• Ejemplo Few-shot: Razonamiento en un caso límite.

Esta estructura redujo alucinaciones en cadenas largas, especialmente en negativas basadas en reglas.

Fase de Planificación: Pensar → Planear → Actuar

Instrucción antes de las herramientas:

Antes de usar herramientas, escribe un plan corto:
PENSAR: [¿qué información necesito?]
PLAN: [paso 1 → paso 2 → paso 3]
ACTUAR: [ejecutar plan]

Reduce a la mitad las llamadas redundantes a herramientas. Obliga a establecer objetivos antes de actuar.

Lecciones Clave

• Mover datos dinámicos (marcas de tiempo) al final del prompt acelera bucles 2–3x vía caché KV.
• Puertas de permiso con diálogos y errores estructurados minimizan riesgos de escritura.
• Verificación automática y validación de rutas eliminan fallos silenciosos en operaciones de archivos.
• Línea de Tiempo del Agente genera confianza mediante transparencia en pasos para acceso a archivos.
• Prompts estructurados con planificación mejoran la fiabilidad en tareas multistep.

— Editorial Team