Agentes

Un agente es una definición guardada en el workspace: en qué etapas trabaja, con qué modelo y credencial, qué skills y qué servidores MCP recibe en cada etapa, y los prompts que lee al arrancar. Thulu no trae agentes: cada workspace arranca con el catálogo vacío y el equipo escribe los suyos en “Agentes”, los instala desde el Workshop o los importa de otro workspace.

Un agente no corre solo por existir. Una tarea lo asigna a una etapa (a mano o desde el template del proyecto), y cuando la tarea entra en esa columna Thulu arranca la corrida con lo que definiste acá.

Un workspace nuevo: la lista dice “No hay agentes. Hacé clic en + Nuevo agente.”

Antes de empezar

• Rol admin del workspace. Cualquier rol ve la página, pero crear, configurar y escribir prompts lo hace sólo un admin. Con rol developer la página lo avisa arriba y sólo deja cambiar el perfil del modelo; con viewer, todo queda de lectura.
• Una clave para el motor en “Configuración → Motores de IA” (Credenciales y motores). Sin ella el agente se puede crear, pero no tiene con qué llamar al modelo.
• Para que trabaje una columna del tablero, esa columna tiene que tener prendido “Correr un agente” (Tableros y etapas). El tablero que trae un workspace nuevo no lo tiene en ninguna.
• Las skills del workspace (Skills) y los servidores MCP (MCPs) que quieras darle. Se pueden sumar después.

Crear un agente listo para trabajar

Este es el camino completo para que un agente pueda trabajar una columna del tablero, contestar menciones y abrir chats. Configuración, Skills y MCP comparten la barra de abajo: “Guardar configuración” guarda lo de las tres pestañas juntas, y podés pasar de una a otra sin guardar. Arriba de las pestañas, el recuadro “Qué le falta para correr” marca etapas, prompt, credencial y asignación, cada uno con un link a lo que falta.

1. En “Agentes”, tocá “Nuevo agente” (o apretá N).

2. Escribí el “Nombre” y la “Descripción”, tildá las “Etapas” donde va a correr y, si querés, las “Skills por defecto” (se aplican a cada etapa tildada). Tocá “Crear”. El nombre va en minúsculas, con números, guion o guion bajo y hasta 64 caracteres (backend, revisor-pr): es como lo vas a @mencionar y como aparece en las tareas. No puede ser user, system, auditor ni automation, y no se puede cambiar después. El modal marca un nombre inválido o repetido mientras escribís y, si tiene mayúsculas, ofrece la versión en minúsculas.

   

   El modal. Dejá “Clonar un agente existente” apagado para empezar de cero.

   Al crearlo, si el tablero default tiene proyectos y una columna que corre agente, el aviso ofrece “Usar en” esa columna: suma la etapa al agente y lo pone como agente por defecto de esa columna en la plantilla de esos proyectos (lo mismo que el paso 8).

3. En la pestaña “Configuración”, revisá “Etapas válidas”. En “Columnas del tablero” podés fijar al lado de cada una el tope de turnos (vacío = 20). En “Modos”, tildá “Mención” si querés que conteste cuando lo arroban en un comentario, y “Chat” si querés abrir conversaciones con él (en “Chat”, 30 turnos por mensaje).

4. Revisá “Modelo y credenciales” (lo explica la sección siguiente) y tocá “Guardar configuración”. Abajo a la derecha aparece “Configuración guardada”.

   

   El agente backend, que corre en En curso (40 turnos), Mención y Chat. La caja gris dice con qué modelo y clave corre lo guardado.

5. Pasá a “Skills” y, dentro del bloque de cada etapa, tildá las skills del workspace que tiene que leer. “Copiar a las otras etapas” repite lo de un bloque en las demás etapas del agente (pisa lo que tenían). Guardá.

6. Pasá a “MCP” y, en cada etapa, tildá los servidores que el agente puede usar. Guardá. La sección Servidores MCP explica qué concede el tilde y cómo limitarlo a algunas tools.

7. Pasá a “Prompts” y, en la fila “Prompt general”, tocá “Crear main.md”. Escribí la identidad y las reglas del agente en markdown y tocá “Guardar” (o ⌘ S). Ese archivo es el prompt de todas las etapas que no tengan uno propio. Si tenías cambios sin guardar en Configuración, Skills o MCP, al entrar a Prompts te pregunta si los descartás.

8. Asigná el agente fuera de esta página. Para todas las tareas nuevas de un proyecto: en la configuración del proyecto, tabla “Plantilla de etapas”, elegilo como “Agente por defecto” de la etapa (Proyectos); la tabla sólo lista columnas con “Correr un agente”. Para una tarea que ya existe: en su panel, tocá la fila “Agente” y elegilo para la etapa (Tareas). Menciones y chat no necesitan asignación.

Si la tarea entra a una columna que corre agente y no tiene agente asignado ahí, Thulu deja un comentario de sistema y no lanza nada. Si el agente no tiene prompt para esa etapa ni main.md, la corrida falla con “el agente no tiene prompt para esta etapa”.

Modelo y credenciales

La caja “Modelo y credenciales” de “Configuración” tiene dos modos. Los cambios valen desde la próxima corrida.

Modo	Qué elegís	Qué pasa cuando cambia algo en Configuración
“Perfil” con “Predeterminado de Claude Code”	Nada más	El agente sigue al perfil por defecto del motor: si alguien cambia ese perfil, el agente cambia con él
“Perfil” con un perfil con nombre	Un perfil de la lista “Perfiles”	Motor, modelo y clave salen de ese perfil; editarlo cambia a todos los agentes que lo usan
“Personalizado”	“Motor”, “Modelo” (texto libre con sugerencias: sonnet, opus, haiku) y “Esfuerzo” (bajo, medio, alto)	La clave sigue saliendo del perfil por defecto del motor; los campos vacíos usan los valores de ese perfil

Las claves nunca se guardan en el agente. Los perfiles y sus claves se crean en “Configuración → Motores de IA” (Credenciales y motores); si todavía no hay ninguno con nombre, la caja lo dice con un link.

Debajo, la caja gris “La configuración guardada corre con…” muestra el resultado final: motor, modelo, esfuerzo y de dónde sale la clave. Si dice que no tiene clave, las corridas no arrancan. En una instalación propia sin perfiles puede decir “del host del daemon”, si el operador habilitó esa credencial.

Nota

La lista de motores incluye “OpenAI Codex” y “OpenCode”. Los dos corren agentes y auditores. Los mensajes a un agente mientras trabaja necesitan Claude Code, y a Codex las skills le llegan pegadas en el prompt.

Otras opciones de Configuración

Opción	Qué hace
“Descripción”	Texto que se ve en la lista de agentes y en las tarjetas
“Entrega de skills”	“Auto — sigue al motor” (recomendado), “Nativo” (las skills llegan como archivos y el modelo abre las que necesita) o “En línea” (se pegan todas en el prompt, unos 12k tokens más por corrida)
“Funciona sin un repo vinculado”	Para agentes de investigación o textos. Apagado, una tarea sin repo vinculado queda bloqueada al entrar a una etapa de este agente
“Etapas válidas”	“Columnas del tablero”, con el tope de turnos de cada una, y “Modos”: “Mención” y “Chat”
“Auditor por etapa”	Tildá una etapa para que, al terminar la corrida, otro contenedor revise el trabajo. “Motor”, “Turnos” (vacío = 5), “Modelo” y “Skills” (nombres separados por coma) son opcionales. Por defecto el auditor corre con el motor del agente y con su key. Si elegís otro motor, usa la key predeterminada de ese motor y sus modelos; ni Codex ni OpenCode tienen límite de turnos. Si el auditor no puede arrancar, por ejemplo porque ese motor no tiene key, o termina sin veredicto, la tarea queda bloqueada en vez de avanzar. Usa los “Prompts del auditor”
“Lecturas grandes”	Modo “Apagado” (el de fábrica), “Sugerir” u “Obligar”, y el motor y modelo que leen los archivos grandes por el agente. Usa la credencial predeterminada del workspace para ese motor. “Obligar” sólo funciona en agentes de Claude Code. No prometemos que baje el costo: medido con Opus, no ahorró

Si borrás una columna del tablero que el agente tenía tildada, aparece “⚠ configuración por etapa huérfana de etapas eliminadas” con un botón “Limpiar”, que borra esa configuración y los prompts de esa etapa.

Skills por etapa

La pestaña “Skills” tiene un bloque por etapa válida. Arriba, las skills del workspace (las que se crean en Skills); abajo, “Skills del sistema”.

Etapa En curso: convenciones-go concedida. Las skills del sistema dependen de los MCP de la etapa: con octopus-api tildado entran cuatro.

Las skills del sistema vienen con Thulu y le enseñan al agente a trabajar en Thulu. No se conceden: llegan solas cuando la etapa tiene el servidor MCP del que dependen. Cada una dice por qué está:

Skill	Llega cuando
octopus-run	“Toda corrida”
octopus-task-workflow, octopus-refinement, octopus-test-cases, octopus-observability	La etapa tiene octopus-api
octopus-browser-evidence, octopus-evidence-library	La etapa tiene argus-browser
octopus-sandbox	La etapa tiene argus-sandbox
octopus-token-optimizer	El agente tiene prendidas las “Lecturas grandes”

Las que dicen “Necesita … en esta etapa” no aplican: se ven destildadas y no se pueden tocar. Para apagar una que sí aplica, destildala y guardá: queda afuera de las corridas de ese agente en esa etapa (incluidas menciones, chat y corridas retomadas; el auditor conserva las suyas).

Precaución

Si apagás octopus-run, las corridas de esa etapa no saben dónde están los repos, quién commitea y abre el PR, ni qué dejar al terminar. La página lo advierte en rojo. Apagala sólo si el prompt del agente ya cubre todo eso.

Servidores MCP por etapa

La pestaña “MCP” repite, por cada etapa válida, la lista de servidores MCP del workspace. Cada fila tiene un casillero para el servidor entero y un botón “Tools” con cuántas tools están concedidas. Debajo, una línea dice qué concede la etapa (“En esta etapa concede lectura y escritura”, más las que se nombran a mano).

Tildar el servidor concede lo que cubre su scope por defecto: lectura en octopus-api y argus-cloud, lectura y escritura en argus-github. Las tools que mueven cosas fuera de la tarea no entran en ningún scope y se conceden sólo por nombre: pr_merge, run_dispatch y deployment_approve en argus-github (“Deploy”), y las que leen o cambian tareas de otros tableros en octopus-api (“Otros tableros”). Por eso, por default, ningún agente mergea: un admin decide si le concede pr_merge en una etapa.

Tildar el servidor concede su scope por defecto; las tools que se conceden por nombre quedan afuera.

Para elegir tools:

1. Tocá “Tools” en la fila del servidor, dentro de la etapa que querés limitar.

2. En el panel lateral, las tools aparecen agrupadas en “Lectura”, “Escritura” y los grupos que se conceden por nombre. Destildá “Todas, menos las que se conceden por nombre” y tildá una por una las que hacen falta. El contador muestra “n/61 elegidas”.

   

   El panel de octopus-api en la etapa En curso.

3. Tocá “Listo” (o Esc) y después “Guardar configuración”. Si destildás todas, el servidor sale de esa etapa.

4. Para repetirlo en las demás etapas del agente, usá “Copiar a las otras etapas”.

Para una etapa que despliega con GitHub Actions, “Plantilla Deploy” concede argus-github@read más run_dispatch, run_watch y run_logs. run_dispatch necesita el permiso Actions: write en la GitHub App.

Si un servidor muestra “scope por defecto (desconocido)” y “?/N”, la etapa lo tiene concedido por nombre y Thulu no sabe qué tools da eso; el servidor aplica su propio default. Elegí tools, o destildá y volvé a tildar el servidor. Si en lugar de “Tools” dice “todas las tools”, el daemon no pudo leer la lista del servidor (puede estar caído) y se concede entero. Ver MCPs.

Prompts

La pestaña “Prompts” lista los archivos que lee el agente, agrupados en “Prompts del agente” y “Prompts del auditor”.

main.md vale para En curso y Mención; Chat tiene su propio archivo.

Fila	Para qué
“Prompt general” (main.md)	El prompt de toda etapa que no tenga uno propio. Sin él, las etapas sin prompt propio no tienen prompt
Una etapa en “Prompts por etapa”	Un prompt sólo para esa etapa. “Escribir uno propio” lo arranca con una copia de main.md; mientras no exista, la fila dice “Usa el prompt general”
“Mención” y “Chat”	Lo que lee el agente cuando lo arroban o en el chat. Sin archivo propio usan main.md; si tampoco hay main.md, la mención y el chat responden que falta el prompt y nombran el archivo
“default.md” del auditor	Las instrucciones de revisión del auditor, con overrides por etapa igual que el agente
“Archivos huérfanos”	Prompts de etapas donde el agente ya no corre. Nadie los carga: borralos o pasá el texto a otra etapa

Un prompt guardado vale desde la próxima corrida; una corrida en curso sigue con el que bajó al arrancar. No pegues secretos en un prompt: viaja a cada corrida y al modelo. Si el texto tiene algo con forma de clave (una clave de Anthropic sk-ant-…, un token de GitHub ghp_…, una clave de AWS AKIA…, una clave privada o un token de Slack), Thulu no lo guarda y el editor dice “No se pudo guardar: el texto parece incluir una credencial…”.

Para escribir el prompt de una etapa:

1. En “Prompts”, tocá “Escribir uno propio” en la fila de la etapa.

2. Editá el texto (arranca con la copia de main.md).

3. Tocá “Guardar” o ⌘ S. Aparece “Se guardó” con la ruta del archivo (prompts/in_progress.md, por ejemplo) y la fila pasa a mostrar el archivo en verde.

4. Tocá “← Volver a la lista”.

Para volver a usar main.md en esa etapa, borrá su archivo con “Eliminar”.

Volver a una versión anterior de un prompt

Cada guardado de un prompt queda como versión: quién lo hizo y cuándo. Se guardan las últimas 50 por archivo.

1. En “Prompts”, tocá “Editar” en la fila del archivo.

2. Tocá “Historial”.

3. Elegí una versión de la lista (“Creado”, “Editado”, “Borrado”, “Restaurado”) para leer su texto completo a la derecha.

   

   El historial de main.md. Se lee el texto de cada versión; no hay comparación lado a lado.

4. Tocá “Restaurar esta versión” y confirmá. El archivo vuelve a ese texto y el que tenía queda como una versión más, así que podés volver.

La configuración tiene su propio historial. El botón “Historial” del encabezado del agente lista las configuraciones que tuvo: cada vez que guardás los ajustes, instalás encima desde el Workshop o restaurás, la que se reemplaza queda ahí, con qué cambió después (etapas, motor, modelo, esfuerzo, skills y MCP por etapa, auditor). “Restaurar esta configuración” vuelve a esa versión sin tocar los prompts, y la actual queda en el historial.

Clonar, buscar y eliminar

Para clonar, en “Nuevo agente” escribí el nombre nuevo, prendé “Clonar un agente existente” y elegí el original. El clon copia etapas, modelo, skills, MCP y prompts. Si además tildás “Skills por defecto”, se suman a las que ya tiene el original en cada una de sus etapas.

La búsqueda de la lista (/) filtra por nombre, descripción y etapas; ↑ ↓ recorren los agentes.

“Eliminar agente” saca al agente de la lista y de los selectores después de confirmar; sus prompts quedan en el historial. El diálogo dice cuántas tareas o plantillas de proyecto lo nombran. Esas tareas siguen nombrándolo: si después creás otro agente con el mismo nombre, corren con el nuevo.

Importar y exportar con la CLI

Para mover un agente o una skill desde la UI, usá “Exportar” e “Importar archivo” del Workshop. En una instalación propia, para mover varios agentes juntos o versionarlos en un repo, está la CLI. Habla directo con la base de datos, así que se corre donde corre el daemon:

thulu agents export -workspace <id> > mis-agentes.json
thulu agents import -workspace <id> ./mis-agentes.json

import también acepta un directorio. El export completo de un workspace lleva los agentes. Ver CLI.

Problemas comunes

Síntoma	Causa y salida
“Sólo minúsculas, números, guion y guion bajo…” debajo del nombre	El nombre tiene mayúsculas, espacios u otros caracteres. Tocá “Usar «…»” para tomar la versión en minúsculas
“Ese nombre lo usa Thulu. Elegí otro.”	Elegiste user, system, auditor o automation. Usá otro
“No se pudo guardar: el texto parece incluir una credencial…” al guardar un prompt	El texto tiene algo con forma de clave. Sacala del texto; las credenciales van en Configuración
Las “Skills por defecto” no se pueden tildar	No marcaste ninguna etapa en el modal
El agente no aparece para elegir en una columna	No tiene esa etapa en “Etapas válidas”, o no guardaste
La tarea entra a la columna y no arranca nada	La tarea no tiene agente asignado en esa etapa, o la columna no tiene “Correr un agente”. Ver Tableros y etapas
El chat o la mención contestan que falta el prompt	Creá main.md o el prompt propio de “Chat” / “Mención”
La caja del modelo dice que no hay clave	No hay perfil predeterminado para ese motor. Creá uno en Configuración → Motores de IA
El agente no puede comentar ni adjuntar en su tarea	La etapa tiene octopus-api sin escritura. Revisá sus tools en “MCP”

Relacionado

SkillsCrear las skills del workspace que se conceden por etapa.

MCPsQué servidores hay y qué hace cada tool.

Credenciales y motoresPerfiles, claves y proveedores del modelo.

Tableros y etapasLas columnas que un agente puede trabajar.

Corridas de agentesQué pasa cuando el agente arranca y cómo seguirlo.

ChatConversar con un agente que tiene la etapa Chat.