Super-agent

El super-agent es un modo, no el nombre de una persona. Cuando ejecutás apx exec sin apuntar a un agente de proyecto específico, APX activa este modo: el loop a nivel del daemon, que usa herramientas y puede alcanzar cada herramienta registrada — operaciones de archivos, llamadas MCP, Telegram, shell, tasks, sesiones y más.

El nombre que usa el asistente cuando habla con vos viene de ~/.apx/identity.json (por defecto “APX”). Las referencias a “super-agent” son un término técnico interno para el modo. Lo configurás con las claves super_agent.* en ~/.apx/config.json, y los tipos de routine todavía pueden decir super_agent — pero los usuarios nunca ven esa etiqueta.

Nota

Este diseño está registrado en spec/decisions/002-super-agent-is-mode-not-name.md. Mirá Configuration para la referencia completa de las claves super_agent.*.

Habilitarlo

El modo está deshabilitado por defecto. Configurá ambas claves antes de llamarlo por primera vez:

apx config set super_agent.enabled true
apx config set super_agent.model "anthropic:claude-sonnet-4-5"

Una vez habilitado, cada llamada a apx exec sin -a <agent> pasa por este modo.

apx exec — el punto de entrada de una sola vez

apx exec "<prompt>"                         # modo super-agent (por defecto)
apx exec -- "<prompt>"                      # igual; -- evita problemas de parseo de flags
apx exec -a reviewer "<prompt>"            # un agente de proyecto nombrado en su lugar
apx exec "<prompt>" --model gpt-5          # sobrescribe el modelo configurado para esta llamada
apx exec "<prompt>" --max-tokens 2000      # limita los tokens de salida
apx exec "<prompt>" --project my-app       # fija un contexto de proyecto específico

apx

$ apx exec 'list my open tasks across all projects'
Roby (super-agent) · anthropic:claude-sonnet-4-5

→ tool  tasks.list { project: "First Project", state: "open" }
→ tool  tasks.list { project: "Acme Store", state: "open" }
→ tool  tasks.list { project: "Data Pipeline", state: "open" }

Tenés 4 tasks abiertas:
• First Project  — Wire Stripe webhooks before merge (vence 06-16)
• Acme Store     — Retry-guard the flaky cart-total test (vence 06-18)
• Acme Store     — Document the pairing flow for the web panel
• Data Pipeline  — Backfill ingestion CLI flag (vence 06-20)

# 612 tok in / 198 out · 2.4s

apx exec en acción — modo super-agent con las llamadas a herramientas visibles

Cuando el modo super-agent está activo, el daemon resuelve el nombre del asistente desde ~/.apx/identity.json y lo muestra en las líneas de estado, los headers de la TUI y las respuestas de Telegram — nunca la cadena “super-agent”.

El tool loop

Por debajo, runSuperAgent() arma un system prompt (bloque de identidad + inventario de proyectos + bloque de memoria + bloque de threads activos), selecciona un subconjunto del schema de herramientas apropiado para el canal, y después llama al engine vía el loop estándar runAgent(). El loop continúa hasta que el modelo deja de llamar herramientas o una señal lo aborta.

Registro de herramientas

El registro completo tiene alrededor de 30 herramientas nativas más herramientas puenteadas desde registries (browser, fetch, search, glob, grep). El daemon elige un subconjunto según el canal para mantenerse dentro de los presupuestos de TPM de los tiers baratos:

Canal	Conjunto de herramientas	Justificación
api / apx exec	Completo	Deliberado, modelo elegido por el usuario
routine	Completo	Programado, autónomo, modelo elegido por el usuario
web / code	Completo	Workspace de formato largo
telegram	Core (~700 tokens)	Tiers baratos, respuestas ágiles
desktop / deck	Core	Igual

El modelo siempre puede expandir su superficie llamando a load_skill.

Herramientas nativas seleccionadas

Herramienta	Qué hace
create_task / list_tasks	Agregar y leer items de TODO por proyecto
call_agent	Delegar a un agente de proyecto nombrado sin lanzar un proceso nuevo
call_mcp	Llamar cualquier herramienta de un servidor MCP registrado
call_runtime	Delegar a un runtime externo (Claude Code / Codex …), de forma síncrona o en segundo plano
run_subagent	Lanzar un sub-agente aislado (contexto fresco, mismas tools menos las de interacción con el usuario) que trabaja una tarea auto-contenida hasta completarla y devuelve el resultado — máximo un nivel de anidamiento
run_shell	Ejecutar un comando de shell (limitado por el modo de permisos)
send_telegram	Enviar un mensaje vía el plugin de Telegram
remember	Escribir un hecho durable en ~/.apx/memory.md
search_sessions	Recuperar transcripciones de sesiones pasadas
set_identity	Actualizar campos de ~/.apx/identity.json

Brokering entre canales

El modo super-agent es el handler común detrás de cada superficie: mensajes de Telegram, prompts de la ventana de Desktop, llamadas a apx exec, chat web y corridas de routines convergen todos en runSuperAgent(). Cada superficie pasa un identificador de channel (telegram, desktop, web, routine, api, …) que determina:

• Qué subconjunto de herramientas es visible para el modelo.
• Si se inyecta un bloque de “active threads” (turnos recientes en otros canales).
• Qué identidad de remitente de Telegram y qué reglas de role-gating aplican.

El broker de memoria corre antes de cada llamada que no sea tool-free e inyecta un bloque [MEMORIA RELEVANTE] en el system prompt. Mirá Memory system para los detalles.

Identidad — apx identity

El nombre visible del asistente se guarda en ~/.apx/identity.json:

{
  "agent_name": "APX",
  "owner_name": ""
}

Tres comandos lo gestionan:

apx identity show                 # imprime los campos de identidad actuales
apx identity set agent_name Ada   # cambia el nombre visible a "Ada"
apx identity set owner_name Sam   # configura el nombre del owner/usuario
apx identity wizard               # prompt de configuración interactivo

apx

$ apx identity show
  Agent name  : Roby
Personality : pragmatic, concise, a little playful
Owner       : Alex
Context     : prefers es-AR, ships fast, hates ceremony
Language    : en  (apx config set user.language <code>)
Last wakeup : 2026-06-14 09:31
File        : ~/.apx/identity.json

apx identity show — nombre actual del agente y del owner

Consejo

Cambiar agent_name se propaga de inmediato a las respuestas de Telegram, la burbuja de Desktop, el sidebar de la TUI y el chat web. No hace falta reiniciar.

Modo de permisos

permission_mode en super_agent controla qué puede hacer el tool loop sin preguntar:

Modo	Comportamiento
total	Todas las herramientas corren sin confirmación
automatico	APX decide automáticamente (recomendado)
permiso	Solo las herramientas en allowed_tools; todo lo demás pregunta

apx permission set automatico

Análisis de riesgo inline

Una capa opt-in encima del modo de permisos (inspirada en el LLMSecurityAnalyzer de OpenHands). Cuando está habilitada, cada schema de herramienta gana un campo obligatorio security_risk (LOW / MEDIUM / HIGH) que el modelo completa como parte del mismo call — sin ninguna llamada extra al LLM. Los calls calificados en confirm_at o más alto pausan y piden tu confirmación en la superficie activa (diálogo web, Telegram); un call rechazado vuelve al modelo como una observación de error para que re-planifique.

"super_agent": {
  "security_risk": {
    "enabled": true,
    "confirm_at": "HIGH",
    "confirm_unknown": true
  }
}

• confirm_at — calificación mínima que pausa (LOW confirma todo, HIGH solo acciones destructivas o hacia afuera).
• confirm_unknown — también pausa cuando el modelo no calificó el call (los modelos débiles a veces omiten el campo).

No es un duplicado del modo de permisos — filtra por otro eje. El modo de permisos decide por identidad de la tool (¿es peligrosa / está en la allowlist?); el analizador de riesgo decide por el juicio del modelo sobre la gravedad de esta acción concreta. Por eso agrega una barrera que el modo de permisos no puede dar:

• En automatico la calificación de riesgo reemplaza la confirmación estática por herramienta peligrosa.
• En permiso la allowlist sigue aplicando y el gate de riesgo se compone encima.
• En total se vuelve un piso de seguridad: todo corre libre excepto una acción calificada HIGH, que igual se detiene para confirmación aun con confianza total. Ese es el punto — una acción catastrófica se atrapa por más que confíes en el agente.

Judge de completitud

Loop de verificación opt-in (patrón critic de OpenHands) para turnos con completion contract (superficies de código): cuando el agente declara que terminó, un LLM juez puntúa la probabilidad de que el pedido original esté completamente satisfecho. Por debajo de success_threshold, el agente recibe una nota interna de verificación (qué parece faltar, según el juez) y sigue trabajando — hasta max_iterations rondas. Un juez inutilizable (engine caído, respuesta no parseable) acepta el resultado en vez de bloquearlo.

"super_agent": {
  "judge": { "enabled": true, "success_threshold": 0.6, "max_iterations": 2, "model": "" }
}

model vacío → el juez corre sobre super_agent.model; poné un modelo barato para mantener bajo el overhead de verificación. Los veredictos salen como eventos judge_verdict y en el resultado como result.judge.

Detección de loops (stuck detection)

El tool loop vigila dos formas de quedarse trabado: el mismo call devolviendo el mismo resultado action_repeat veces, y el mismo call fallando error_repeat veces seguidas. En la primera detección el modelo recibe una nota in-band (“parecés trabado — cambiá de enfoque o explicá el bloqueo”); si sigue loopeando, el turno se cierra antes con un wrap-up escrito por el modelo en vez de quemar el resto del presupuesto de iteraciones. Activado por defecto:

"super_agent": {
  "stuck_detection": { "enabled": true, "action_repeat": 4, "error_repeat": 3 }
}

Fallback de modelo

Si el modelo primario no está disponible, APX recorre una lista ordenada y configurable de proveedores de fallback. Configurá el orden y habilitá el router:

apx model enable
apx model order ollama openrouter groq
apx model status          # prueba todos los proveedores; muestra cuál se usaría ahora

Mirá Configuration para el schema completo de super_agent.model_fallback.

Routing por contenido

Encima de la cadena estática de fallback, reglas opt-in de routing por turno (inspiradas en el RouterLLM de OpenHands) inspeccionan el mensaje real — imágenes, tamaño del prompt/contexto, canal, keywords — y prefieren otro modelo para ese turno. Las reglas se evalúan en orden; gana la primera que matchea completa. El modelo preferido igual pasa por el health-check y cae por la cadena normal si no está disponible, y un override explícito por request siempre le gana a las reglas.

"super_agent": {
  "routing": {
    "enabled": true,
    "rules": [
      { "model": "anthropic:claude-sonnet-5", "when": { "has_image": true } },
      { "model": "groq:llama-3.3-70b-versatile", "when": { "max_prompt_chars": 200, "channels": ["telegram"] } },
      { "model": "anthropic:claude-opus-4-8", "when": { "keywords": ["refactor", "arquitectura"] } }
    ]
  }
}

Condiciones de when (todas deben cumplirse): has_image, min_prompt_chars / max_prompt_chars, min_context_chars, channels (lista), keywords (lista, substring case-insensitive). Un when vacío matchea todos los turnos — útil como catch-all final.

Siguiente

• Memory system — cómo el agente recupera contexto relevante entre canales.
• Routines — programá el super-agent o un exec_agent simple en un cron.
• Configuration — referencia completa de super_agent.* e identity.json.