Un Agent Harness es la infraestructura de software que rodea a un modelo de lenguaje y le permite realizar acciones.

El harness es responsable de:

• Construir el contexto del modelo.
• Comunicarse con el LLM.
• Proporcionar herramientas al LLM.
• Ejecutar las llamadas a herramientas solicitadas.
• Devolver los resultados de las herramientas al modelo.
• Gestionar conversaciones y sesiones.
• Controlar el ciclo de vida de la ejecución.

El LLM proporciona capacidades de razonamiento.

El harness proporciona el entorno en el que ese razonamiento puede traducirse en acciones.

Un chatbot tradicional generalmente sigue este patrón:

flowchart LR
    A["Usuario"] --> B["Prompt"]
    B --> C["LLM"]
    C --> D["Respuesta"]

Un agente de programación con IA añade un entorno de ejecución:

flowchart TD
    A["Usuario"] --> B["Agente Pi"]
    B --> C["LLM"]
    C --> D{"¿Se necesita herramienta?"}
    D -->|Sí| E["Ejecutar Herramienta"]
    E --> F["Devolver Resultado"]
    F --> C
    D -->|No| G["Respuesta Final"]

Ejemplo:

Chatbot: "Aquí tienes código Python que calcula gastos."

Pi: "Creé los archivos de Python, ejecuté el programa, realicé pruebas y corregí un error."

La diferencia importante es la capacidad de interactuar con un entorno real.

Minimalismo:

• Mantener el núcleo relativamente pequeño.
• Evitar abstracciones innecesarias.
• Construir sobre herramientas existentes del sistema operativo.

Extensibilidad:

• Crear herramientas personalizadas.
• Construir extensiones.
• Usar habilidades reutilizables.
• Conectar servicios externos.

Independencia del Modelo:

• Usar diferentes proveedores de LLM.
• Cambiar de modelo dentro del mismo entorno.
• Comparar el comportamiento de los modelos.

Transparencia:

• Observar las respuestas del modelo.
• Inspeccionar las ejecuciones de herramientas.
• Revisar las modificaciones.
• Examinar el historial de sesiones.

Una configuración básica de Pi no requiere:

• Una base de datos vectorial.
• Un servidor de orquestación separado.
• Kubernetes.
• Docker.
• Un marco de trabajo multi-agente complejo.
• Una aplicación backend personalizada.

Para una demostración básica, una terminal, un LLM compatible y un directorio local son suficientes.

flowchart TB
    USER["Desarrollador"]

    subgraph PI["Agente de Programación Pi"]
        UI["Interfaz de Terminal"]
        CORE["Runtime del Agente"]
        CONTEXT["Gestor de Contexto"]
        SESSION["Gestor de Sesiones"]
        TOOLS["Ejecución de Herramientas"]
        EXT["Extensiones / Habilidades"]
        API["Abstracción de API de LLM"]
    end

    subgraph MODELS["Proveedores de LLM"]
        OPENAI["OpenAI"]
        ANTHROPIC["Anthropic"]
        GOOGLE["Google"]
        LOCAL["Modelos Locales"]
    end

    subgraph SYSTEM["Entorno de Desarrollo"]
        FILES["Sistema de Archivos"]
        BASH["Shell"]
        GIT["Git"]
        TESTS["Pruebas"]
    end

    USER <--> UI
    UI <--> CORE

    CORE <--> CONTEXT
    CORE <--> SESSION
    CORE <--> TOOLS
    CORE <--> API

    EXT --> CORE

    API <--> OPENAI
    API <--> ANTHROPIC
    API <--> GOOGLE
    API <--> LOCAL

    TOOLS <--> FILES
    TOOLS <--> BASH
    TOOLS <--> GIT
    TOOLS <--> TESTS

Esta es una arquitectura conceptual, que muestra las principales responsabilidades en lugar de cada dependencia interna.

Pi se desarrolla como una colección de paquetes de TypeScript.

flowchart TD
    USER["Desarrollador"]
    TUI["pi-tui"]
    CODING["pi-coding-agent"]
    CORE["pi-agent-core"]
    AI["pi-ai"]
    LLM["Proveedores de LLM"]

    USER <--> TUI
    TUI <--> CODING
    CODING <--> CORE
    CORE <--> AI
    AI <--> LLM

    CODING --> FS["Herramientas"]
    CODING --> SESSION["Sesiones"]
    CODING --> EXT["Extensiones"]

La misma infraestructura de agente también se puede utilizar a través de interfaces no interactivas.

Ejemplo:

"Crea una aplicación de Python que rastree gastos."

Pi recibe esta solicitud a través de su interfaz de terminal.

Antes de contactar al LLM, Pi prepara el contexto.

Esto puede incluir:

• Instrucciones del sistema.
• Solicitud del usuario.
• Historial de conversación activo.
• Herramientas disponibles.
• Instrucciones del proyecto desde AGENTS.md.
• Descripciones de habilidades.
• Contenido de archivos relevantes.
• Configuración del modelo.

La rama de sesión activa determina qué mensajes históricos se incluyen.

Pi envía la solicitud preparada al proveedor de LLM seleccionado.

El LLM puede producir:

• Texto en lenguaje natural.
• Llamadas a herramientas estructuradas.
• Una combinación de ambos.

Ejemplo de solicitud de herramienta:

Herramienta: write Archivo: expenses.py Contenido: Código fuente de Python

El LLM no escribe el archivo directamente.

Solicita que Pi ejecute la operación.

Pi recibe la llamada a la herramienta solicitada.

El ejecutor de herramientas realiza la acción.

Ejemplos:

• Leer un archivo.
• Escribir un archivo.
• Modificar código.
• Ejecutar un comando de shell.

Pi luego captura el resultado.

La salida se devuelve al runtime del agente.

Ejemplo:

Herramienta: bash Comando: python expenses.py

Resultado: Traceback: NameError …

El resultado se convierte en parte del contexto disponible para el LLM.

El LLM puede decidir:

• Llamar a otra herramienta.
• Modificar el código.
• Ejecutar pruebas adicionales.
• Proporcionar una respuesta final.

Pi repite el proceso mientras se requiera más ejecución.

Esta interacción es la base del comportamiento agéntico.

Se separan tres responsabilidades:

1. LLM: Genera razonamiento y propone acciones.
2. Agent Harness: Coordina la ejecución y gestiona el contexto.
3. Herramientas: Realizan operaciones en el entorno.

Esta arquitectura también es fundamental para muchas otras implementaciones de agentes de IA.

Leer el contenido de archivos.

Ejemplo de prompt:

"Lee app.py y explica su estructura."

Crear o sobrescribir archivos.

Ejemplo de prompt:

"Crea un programa en Python que imprima Hello TechHive."

Modificar archivos existentes.

Ejemplo de prompt:

"Modifica el programa para aceptar un nombre de usuario."

Ejecutar comandos de shell.

Ejemplo de prompt:

"Ejecuta el programa y muestra el resultado."

flowchart TD
    A["Usuario: Corrige el error"]
    B["El LLM analiza la solicitud"]
    C["read: Inspeccionar código"]
    D["edit: Corregir código"]
    E["bash: Ejecutar pruebas"]
    F{"¿Pasan las pruebas?"}
    G["Respuesta final"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F -->|No| B
    F -->|Sí| G

Pueden estar disponibles herramientas y extensiones integradas adicionales según la versión y la configuración.

El contexto es la información suministrada al LLM para una solicitud de modelo.

Puede incluir:

• Solicitud actual del usuario.
• Historial de conversación.
• Resultados de herramientas.
• Instrucciones del sistema.
• Instrucciones del proyecto.
• Descripciones de habilidades.
• Contenido de archivos referenciados.

Pi no carga automáticamente cada archivo en un repositorio en el contexto del LLM.

Selecciona y ensambla el contexto según la sesión y los recursos configurados.

AGENTS.md es un archivo de instrucciones del proyecto.

Ejemplo:

# Instrucciones del Proyecto

Este proyecto es para un taller de agentes de programación.

Directrices:
- Usa Python.
- Prefiere la biblioteca estándar.
- Mantén el código simple.
- Escribe funciones legibles.
- Añade pruebas para nuevas funciones.
- Explica los cambios importantes.

Estas instrucciones ayudan a guiar el comportamiento del agente dentro del proyecto.

Pi mantiene sesiones de conversación.

Las sesiones pueden incluir:

• Mensajes del usuario.
• Mensajes del asistente.
• Llamadas a herramientas.
• Resultados de herramientas.
• Cambios de modelo.
• Eventos de compactación de contexto.

Las sesiones persistentes utilizan archivos JSONL.

Pi admite una estructura de conversación basada en árbol.

flowchart TD
    A["Iniciar Sesión"]
    B["Crear Aplicación"]
    C["Añadir Almacenamiento de Datos"]

    D["Enfoque CSV"]
    E["Enfoque SQLite"]

    F["Probar CSV"]
    G["Probar SQLite"]

    A --> B
    B --> C
    C --> D
    C --> E
    D --> F
    E --> G

Las ramas permiten la exploración de enfoques alternativos desde estados de conversación anteriores.

Las conversaciones largas pueden exceder la ventana de contexto de un modelo.

Pi puede resumir el contexto antiguo para reducir la cantidad de información enviada en futuras solicitudes al modelo.

Comando:

/compact

La compactación ayuda a gestionar el tamaño del contexto, pero puede perder algunos detalles de mensajes antiguos.

Las entradas de sesión originales pueden permanecer en el historial de sesiones almacenado.

flowchart TD
    USER["Desarrollador"]
    PI["Agente Pi"]
    API["Interfaz de Modelo Unificada"]

    USER --> PI
    PI --> API

    API --> A["OpenAI"]
    API --> B["Anthropic"]
    API --> C["Google"]
    API --> D["Modelo Local"]

Ventajas:

• Flexibilidad.
• Comparación de modelos.
• Elección del proveedor.
• Optimización de costos.
• Experimentación.

Las capacidades y la compatibilidad de los modelos pueden variar.

Instrucciones específicas del proyecto.

Prompts reutilizables para actividades recurrentes.

Ejemplos:

• Revisión de código.
• Documentación.
• Generación de pruebas.
• Refactorización.

Instrucciones reutilizables y recursos de apoyo para flujos de trabajo especializados.

Ejemplos:

• Flujo de trabajo de pruebas en Python.
• Flujo de trabajo de despliegue.
• Generación de documentación.
• Desarrollo de API.

Personalización basada en TypeScript.

Las extensiones pueden:

• Definir herramientas personalizadas.
• Registrar comandos.
• Reaccionar a eventos del ciclo de vida.
• Integrar servicios externos.
• Personalizar el comportamiento interactivo.

MCP significa Model Context Protocol (Protocolo de Contexto de Modelo).

Proporciona una forma estandarizada para que las aplicaciones accedan a herramientas y recursos externos.

Las versiones modernas de Pi proporcionan soporte MCP integrado.

Ejemplos de integraciones:

• GitHub.
• Bases de datos.
• Aplicaciones internas.
• Servicios remotos.

Lanzar la interfaz de terminal.

pi

Ejecutar un prompt e imprimir su respuesta.

pi -p "Explica los decoradores de Python"

Transmitir eventos de agente estructurados.

pi --mode json -p "Explica este proyecto"

Controlar Pi usando mensajes JSONL a través de entrada y salida estándar.

Integrar las capacidades del agente Pi en aplicaciones TypeScript.

flowchart TD
    CORE["Runtime del Agente Pi"]

    CORE --> A["TUI Interactiva"]
    CORE --> B["Imprimir / JSON"]
    CORE --> C["RPC"]
    CORE --> D["SDK de TypeScript"]

    A --> E["Desarrollador"]
    B --> F["Scripts de Automatización"]
    C --> G["Aplicación Externa"]
    D --> H["Aplicación de Agente Personalizada"]

macOS / Linux:

curl -fsSL https://pi.dev/install.sh | sh

Windows PowerShell:

irm https://pi.dev/install.ps1 | iex

Alternativa usando npm:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

La instalación de npm requiere Node.js 22.19 o superior.

Dentro de Pi:

/login

Selecciona un proveedor compatible y autentícate.

Luego:

/model

Selecciona el modelo que deseas usar.

Prompt:

Inspecciona el directorio actual.

Explica qué archivos están presentes.

No modifiques nada.

Concepto: Exploración del sistema de archivos y operaciones de lectura.

Prompt:

Crea un rastreador de gastos simple en Python.

Requisitos:
- Añadir un gasto.
- Listar gastos.
- Calcular el total de gastos.
- Almacenar gastos en un archivo CSV.
- Usa solo la biblioteca estándar de Python.

Mantén la implementación simple.

Concepto: Generación de código y creación de archivos.

Prompt:

Ejecuta la aplicación.

Crea tres ejemplos de gastos.

Verifica que el total se calcule correctamente.

Concepto: Ejecución de shell y observación de resultados.

Prompt:

Crea pruebas unitarias usando unittest de Python.

Prueba la creación de gastos y el cálculo del total.

Ejecuta las pruebas y corrige cualquier error.

Concepto: Pruebas autónomas y corrección iterativa.

Prompt:

Añade una función para agrupar gastos por categoría.

Muestra el total para cada categoría.

Actualiza las pruebas y ejecútalas.

Concepto: Modificación de código y retención de contexto.

Comandos:

/session /tree /model

Concepto: Historial de sesiones, ramificación y cambio de modelo.

Entorno de agente de programación minimalista y extensible.

Fortalezas:

• Personalización.
• Múltiples proveedores de LLM.
• Ejecución de herramientas.
• Gestión de sesiones.
• Extensibilidad.

Agente de programación con un conjunto integrado de herramientas y flujos de trabajo de desarrollo.

Agente de programación diseñado para trabajar con bases de código, comandos de terminal y flujos de trabajo de desarrollo.

Marcos de trabajo para desarrollar aplicaciones de LLM personalizadas y flujos de trabajo agénticos.

Pi es principalmente un entorno de agente listo para usar y extensible, en lugar de un marco de trabajo de grafos de flujo de trabajo de propósito general.