CubeLabs

1. ¿Qué es Prime Agent?

Prime Agent es un agente de código abierto para coding y research de larga duración, desarrollado por Prime Intellect (los creadores de PRIME-RL, el framework descentralizado de reinforcement learning). Es un repo en tendencia con más de 12.000 estrellas en GitHub y miles de estrellas nuevas al día.

Su diseño se apoya en dos abstracciones centrales:

• Recursive Language Model (RLM): trata el contexto como variables (prompt-as-a-variable) y las herramientas como subagentes recursivos, llamadas como funciones dentro de un REPL persistente.
• Continual Harness: almacena prompts suplementarios, memorias, descripciones de skills y especificaciones de subagentes como estado duradero que Prime Agent puede refinar con pequeñas actualizaciones basadas en evidencia.

Lo que lo distingue de otros agentes:

En las siguientes lecciones lo instalaremos, configuraremos y pondremos a trabajar sobre un proyecto real paso a paso.

2. Instalación en Linux y macOS

La forma más rápida de instalar Prime Agent es con su instalador oficial, que descarga una release versionada, verifica su checksum SHA-256 e instala el comando prime-agent:

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh

Si quieres probar la última beta construida desde main:

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh -s -- beta

Ejecutar desde el código fuente

Necesitas Node.js 22.8.0 o superior:

git clone https://github.com/PrimeIntellect-ai/prime-agent
cd prime-agent
npm ci
./prime-agent.sh

El runner de fuente preserva el directorio desde el que se invoca, así que puedes llamar a /path/to/prime-agent/prime-agent.sh desde otro proyecto.

Instalación paso a paso

Verifica la instalación:

$ prime-agent --version
prime-agent 0.x.x (latest)

Comandos de mantenimiento útiles:

3. Autenticación y proveedores de modelo

Prime Agent soporta dos vías de autenticación: suscripciones (OAuth) y API keys.

Opción 1: login por suscripción

Arranca Prime Agent y ejecuta /login. Los proveedores de suscripción integrados incluyen:

• ChatGPT Plus/Pro (Codex) — recomendado oficialmente por OpenAI para proyectos OSS.
• Claude Pro/Max — el uso desde harnesses de terceros consume extra usage y se factura por token.
• GitHub Copilot — pulsa Enter para github.com o introduce tu dominio de Enterprise Server.

Opción 2: API key

Define la variable de entorno antes de lanzar Prime Agent, o guárdala con /login:

export ANTHROPIC_API_KEY=sk-ant-...
prime-agent

Las claves se guardan en ~/.prime/agent/auth.json (con permisos 0600) y se auto-refrescan. La tabla de proveedores soportados es amplia:

Las credenciales del archivo auth.json tienen prioridad sobre las variables de entorno.

4. Tu primera sesión

Arranca Prime Agent en el directorio del proyecto que quieras trabajar:

cd /path/to/project
prime-agent

Escribe una petición y pulsa Enter:

prime-agent> Resumen de este repositorio y cómo ejecutar sus checks.

Prime Agent da al modelo una única herramienta integrada: ipython. El kernel de larga vida es el entorno de control para leer y editar ficheros, ejecutar comandos del proyecto, inspeccionar datos, retener estado Python e invocar skills instaladas.

Instrucciones de proyecto con AGENTS.md

Prime Agent carga ficheros de contexto al arrancar. Crea un AGENTS.md en la raíz del proyecto:

# Instrucciones del proyecto

- Ejecuta `npm run check` tras cada cambio de código.
- No ejecutes migraciones de producción en local.
- Mantén las respuestas concisas.

Carga automáticamente:

• ~/.prime/agent/AGENTS.md — instrucciones globales.
• AGENTS.md o CLAUDE.md — desde los directorios padre y el actual.

Tras cambiar un fichero de contexto, reinicia Prime Agent o ejecuta /reload.

Cosas comunes que probar

• Referencias a ficheros: escribe @ en el editor para buscar con fuzzy-match, o pásalos por CLI: prime-agent @src/app.ts "Revísalo".
• Comandos shell: !npm run lint ejecuta y envía la salida al modelo; !!npm run lint lo ejecuta sin añadir salida al contexto.
• Cambiar de modelo: /model o Ctrl+L; /effort ajusta el nivel de razonamiento.

5. El modelo de programación RLM

Prime Agent está construido alrededor de un runtime RLM: el modelo trabaja dentro de un entorno de control Python persistente y compone capacidades como código. Las llamadas a proveedor, la persistencia de sesión, los ciclos de vida de los hijos y la política de seguridad viven en el host TypeScript; IPython es la superficie de programación del modelo.

El bucle RLM en una imagen:

Tarea + contexto de trabajo
        │
        ▼
  Modelo padre ──► kernel IPython persistente ──► ficheros · datos · shell
        │                │
        │                ├──► skills Python-backed (llamadas a función)
        │                └──► subagentes rlm(...) ──► respuestas agent_message / ficheros
        ▼
  Respuesta o siguiente turno

Invariantes del modelo

1. La ejecución es programática. Solo hay una herramienta integrada: ipython. Leer/editar ficheros, ejecutar comandos y delegar trabajo empiezan desde el kernel persistente. El estado Python sobrevive entre turns y a la compactación:

from pathlib import Path

config_files = list(Path(".").rglob("*.toml"))
large_files = [p for p in config_files if p.stat().st_size > 10_000]

Ejecuta los comandos del proyecto con su propio entorno desde una celda %%bash (cada celda es un subshell temporal, pero el estado Python y %cd persisten):

%%bash
npm run check

2. Los subagentes son llamadas RLM nativas. El callable rlm está precargado en el kernel (lo veremos a fondo en la lección 6).

3. Las skills añaden capacidad programática. Soporta el formato Agent Skills y lo extiende con skills Python-backed (lección 7).

4. El estado está diseñado para sobrevivir a un turno. Compactación automática, workers daemon, registros de hijos recuperables, heartbeats, objetivos persistentes y modo autónomo acotado.

6. Subagentes recursivos con rlm()

Los subagentes recursivos son una capacidad integrada. El modelo lanza trabajo independiente desde IPython con await rlm("subtarea"). Cada llamada devuelve un handle de admisión al instante y nunca la respuesta; los hijos envían resultados explícitos como respuestas agent_message al padre o los escriben en ficheros.

handle = await rlm("Revisa el flujo de autenticación por problemas de seguridad", name="auth-reviewer")
print(handle.rlm_child_id, handle.name, handle.session_dir, handle.model)

Lanza varios hijos independientes en llamadas separadas y termina el turno en lugar de esperar:

api_review = await rlm("Revisa la API pública", name="api-reviewer")
test_review = await rlm("Revisa la cobertura de tests", name="test-reviewer")
integration_audit = await rlm("Ejecuta la auditoría de integración lenta", name="integration-audit")

Los resultados llegan solo mediante agent_message o ficheros. Desde el hijo:

await agent_message.send(message, receiver_role="parent")

El padre puede retomar un hijo conservado:

await agent_message.send(
    "Comprueba el test de regresión recién añadido.",
    receiver_role="child",
    receiver_name=api_review.name,
)

Registro y ciclo de vida

children = await rlm.list_subagents()
for child in children:
    print(child.session_name, child.status, child.active_session_id)

El registro de hijos con ámbito de padre sobrevive a la compactación, al reinicio del kernel y a la restauración del padre. Los hijos completados y con respaldo daemon siguen direccionables mientras la sesión del padre esté abierta. Elimina un hijo solo cuando su contexto ya no sea necesario:

await rlm.delete_subagent(children[0])

Por defecto la profundidad de recursión permite que un agente raíz cree hijos; subir la profundidad configurada permite que los descendientes recursen más.

7. Skills: capacidades reutilizables

Las skills son paquetes de capacidad autocontenidos que Prime Agent carga bajo demanda. Implementa el estándar Agent Skills (agentskills.io) y lo extiende con skills Python-backed, un superconjunto que instala paquetes Python en el kernel IPython persistente.

Localizaciones de skills

• Globales: ~/.prime/agent/skills/ y ~/.agents/skills/
• De proyecto: .prime/agent/skills/ y .agents/skills/ (en cwd y directorios ancestro hasta la raíz del repo)
• Paquetes: directorios skills/ o entradas pi.skills en package.json
• Settings / CLI: array skills en settings, o --skill <path>

El descubrimiento funciona con divulgación progresiva: solo las descripciones están siempre en contexto; la SKILL.md completa se carga cuando la tarea coincide.

Skills integradas

Skill Python-backed

Usa el mismo SKILL.md pero añade un paquete Python para el kernel:

web-search/
├── SKILL.md
├── pyproject.toml
└── src/
    └── web_search/
        └── __init__.py

Reglas de detección: se requiere SKILL.md; pyproject.toml marca la skill como Python-backed; el nombre de importación es el nombre de la skill con guiones convertidos a guiones bajos. Si el módulo define run(), se envuelve como callable async:

await web_search("prime agent skills")
await web_search.run("prime agent skills")
help(web_search)

Las skills Python se instalan en modo editable en el venv del kernel (por defecto ~/.prime/agent/kernel-venv; cambia con PRIME_AGENT_KERNEL_VENV). Si cambia el pyproject.toml, Prime Agent reconstruye el venv.

Reutilizar skills de otros harnesses

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

8. CLI, modo no interactivo y gestión de sesiones

Prime Agent se puede usar sin TUI para automatización e integraciones.

Modo no interactivo

prime-agent -p "Resume este codebase"
cat README.md | prime-agent -p "Resume este texto"
prime-agent -p @screenshot.png "¿Qué hay en esta imagen?"

Para salida estructurada: --mode json emite eventos JSON; --mode rpc sirve para integración por procesos.

Gestión de sesiones

Las sesiones se guardan automáticamente como JSONL plano en ~/.prime/agent/sessions/:

Comandos slash útiles

• /model — cambiar modelo · /effort — nivel de razonamiento
• /resume · /new · /tree · /fork · /clone — gestión de sesiones
• /compact [prompt] — compactar contexto manualmente
• /refine [instructions] — refinar o revertir el estado del harness
• /btw <pregunta> — pregunta lateral sin ensuciar la sesión
• /export [file] — exportar sesión a HTML · /share — subir gist privado
• /usage — tokens, coste y contexto

9. Agentes long-running y autónomos

Prime Agent está construido para trabajo de larga duración: las sesiones interactivas normales corren en procesos worker respaldados por un supervisor daemon. Cerrar la TUI desconecta el cliente, no detiene el worker.

Ciclo de vida de la sesión daemon

prime-agent list                 # Lista agentes activos
prime-agent attach <agent>        # Re-adjunta
prime-agent rename <agent> <nombre>
prime-agent stop <agent>          # Detiene un agente
prime-agent shutdown [--force]    # Detiene todo

Los workers persisten transcripciones como JSONL y el estado específico bajo el directorio de artefactos de la sesión. Un reinicio del worker o del supervisor puede recuperar estado, schedules y rehidratar hijos RLM completados.

Comunicación agente-a-agente

prime-agent send <agent> "Verifica la última migración"

Desde el kernel IPython, con la skill precargada agent_message:

roster = await agent_message.list_agents()
receipt = await agent_message.send(
    "Recomprueba el endpoint tras la última edición",
    receiver_role="sibling",
    receiver_name="api-reviewer",
    mode="auto",
)
print(receipt["deliveryStatus"])

Modos de entrega: auto (dirige a un objetivo ocupado, entrega inmediata a uno idle), steer (inyecta en trabajo activo) y follow_up (espera a que termine). Un recibo es delivered o queued.

Heartbeats, schedules y objetivos

• Objetivos persistentes: /goal mantiene un objetivo y su progreso activos entre turns hasta completarlo, pausarlo o limpiarlo.
• Modo autónomo acotado: /autonomous continúa dentro de presupuestos de turns, tokens y tiempo, y puede ejecutar quality gates definidos por el usuario.

10. Arquitectura, seguridad y mejores prácticas

Prime Agent separa la presentación en terminal, la coordinación de procesos, la ejecución del agente, el Python que ve el modelo y el estado persistido.

TUI interactivo ──► AgentConnection ──► Supervisor daemon ──► Session worker
CLI/JSON/RPC   ──►                                      │
                                            ┌───────────┴───────────┐
                                            │ AgentSessionRuntime    │
                                            │  ├─ AgentSession raíz  │
                                            │  ├─ Scheduler          │
                                            │  ├─ kernel IPython     │
                                            │  └─ hijos RLM          │
                                            └───────────┬───────────┘
                                                        ▼
                                          proveedores · almacenamiento JSONL

• El cliente posee renderizado, teclado y preferencias UI; no posee la ejecución.
• El supervisor posee descubrimiento, enrutado, adjuntos, salud del worker y entrega de mensajes entre agentes.
• Cada worker posee un runtime raíz, su scheduler, kernels y todos los descendientes.
• AgentSession posee llamadas a proveedor, colas, tools, compactación, objetivos, ciclos de vida de hijos y escritura de transcripciones.

Modelo de confianza

El kernel IPython ejecuta Python generado por el modelo y comandos del proyecto con los permisos del usuario del worker. Es un entorno de control duradero, no una sandbox de seguridad.

Mejores prácticas

1. Trabaja en un clone desechable o worktree limpio — Prime Agent modifica ficheros con tus permisos; usa git para rollback fácil.
2. Configura AGENTS.md por proyecto con convenciones, comandos de verificación y reglas de seguridad.
3. Revisa las skills antes de usarlas, especialmente las de terceros o las que ejecutan código.
4. Usa /refine para persistir lecciones — guarda lecciones enfocadas como prompts suplementarios, memorias o skills, con historial de refinamiento y rollback.
5. Aprovecha la paralelización con subagentes rlm() para revisiones independientes (API, tests, docs).
6. Acota el modo autónomo con presupuestos y quality gates, y verifica los resultados manualmente.
7. Usa prime-agent doctor si los servicios en background fallan antes de reiniciar a ciegas.

Con esto ya tienes el mapa completo: instalar, autenticar, programar con RLM, delegar con subagentes, crear skills y mantener sesiones daemon. Es hora de lanzar prime-agent en tu propio proyecto y experimentar.