Guía de inicio de TheBotCompany: un equipo de IA sin intervención humana

30 minutos para empezar｜colaboración autónoma de tres roles｜cobertura con múltiples proveedores｜automatización extremo a extremo desde la demanda hasta el PR

---

Introducción del proyecto

TheBotCompany es una plataforma de equipo para desarrolladores de IA que te permite «soltar de verdad». Su idea central es muy directa: ya no se trata de que tú, una persona, chatees con una IA para escribir código; en su lugar, montas un equipo formado por varios AI Agent. Uno planifica, otro escribe código y otro verifica. Ellos conversan entre sí, asignan tareas y gestionan el progreso; lo único que debes hacer es intervenir cuando se enfrenten a un problema que requiera un juicio humano real.

En el equipo hay tres roles de gestión fijos: Athena hace la planificación estratégica y define hitos y presupuestos por ciclo; Ares lidera la ejecución, descompone los hitos en tareas concretas para los agents “obreros”; Apollo se encarga de la aceptación, revisando con altos estándares la entrega de Ares; si no cumple, lo devuelve. Este ciclo no exige que estés mirando todo el tiempo: el Dashboard muestra en tiempo real qué está haciendo cada agent, cuánto cuesta y qué problemas han surgido.

---

Perfil de lectores objetivo

Este artículo está dirigido a los siguientes desarrolladores:

• Tienes cierta experiencia en desarrollo y quieres delegar el trabajo repetitivo de codificación a un equipo de AI Agents, para centrarte en decisiones y arquitectura
• Te interesan los conceptos de colaboración Multi-Agent y equipos autoorganizados, y buscas casos prácticos
• Ya usas un solo Agent para ayudarte en el desarrollo, pero quieres ampliarlo a varios Agents en paralelo para cubrir distintas direcciones

Si lo que buscas es una herramienta de «la instalas y te olvidas para siempre», primero debes ajustar expectativas: TheBotCompany puede reducir muchísimo la intervención humana, pero no elimina la necesidad de ti por completo.

---

Dependencias e entorno esenciales

---

Árbol de estructura del proyecto (completo)

Tras la instalación y el arranque, en el directorio ~/.thebotcompany/ se generará la siguiente estructura:

~/.thebotcompany/
├── keys.json              # API Keys almacenadas de forma cifrada
├── db.sqlite              # Base de datos del Issue tracker
├── config.yaml            # Configuración global
└── logs/                  # Registros de ejecución

Tu directorio de proyecto/
├── workers/               # Definiciones de habilidades de los agents obreros
│   ├── leo.md             # Frontmatter: reports_to, role, model
│   └── maya.md
├── workspace/             # Espacios de trabajo de cada agent
│   ├── athena/note.md
│   ├── ares/note.md
│   └── leo/note.md
└── .tbc/                  # Configuración a nivel de proyecto (generada al crear el proyecto)

---

Pasos de instalación guiados

Paso 1: Instalar TheBotCompany

npm install -g thebotcompany

Verificar la instalación:

tbc --version

Paso 2: Iniciar el servicio

tbc start

En la primera ejecución, te pedirá configurar de forma secuencial:

1. Contraseña de acceso al Dashboard — para proteger acciones de escritura (pausar, reanudar, modificar configuración)
2. Número de puerto — por defecto 3100; pulsa Enter para aceptar el valor predeterminado

? Set a password for dashboard write access: ********
? Port to run the dashboard (default 3100):

Cuando el arranque finaliza, el Dashboard se puede acceder en http://localhost:3100. Por defecto está en modo solo lectura; inicia sesión para poder operar.

Paso 3: Configurar la API Key

Abre el Dashboard (http://localhost:3100), haz clic en Settings en la esquina superior derecha y, en el panel de Keys, agrega tu API Key. También puedes detectarla automáticamente en la primera ejecución mediante variables de entorno:

# Añádelo en .bashrc o .zshrc:
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

Paso 4: Crear un proyecto mediante Dashboard

1. Abre http://localhost:3100
2. Haz clic en New Project y completa:
   • Repository URL — la dirección de tu Repo de GitHub (requiere que gh tenga permisos)
   • Provider — elige qué LLM Provider usar
   • Model Tier — qué modelo se usa en cada nivel (high/mid/low)
3. Haz clic en Create y cede el control a Athena para que empiece a trabajar

---

Arquitectura detallada de la colaboración de tres roles

Esta es la parte más esencial del diseño de TheBotCompany. Si la entiendes, sabrás cómo funciona todo el sistema.

Tres roles de gestión fijos

El ciclo completo (Cycle)

Fase PLANNING（Athena）
  → Athena + sus agents obreros en ejecución
  → investigación, evaluación y lluvia de ideas
  → definición de hitos → entrar en IMPLEMENTATION

Fase IMPLEMENTATION（Ares）
  → Ares + sus agents obreros en ejecución (hasta N ciclos)
  → Ares anuncia finalización → entrar en VERIFICATION
  → supera el presupuesto del ciclo → devolver a PLANNING para re-evaluar

Fase VERIFICATION（Apollo）
  → Apollo + sus agents obreros en ejecución
  → Apollo aprueba la aceptación → entrar en el siguiente PLANNING
  → Apollo devuelve → volver a IMPLEMENTATION para corregir

¿Cómo trabajan los agentes obreros?

Los Managers (Ares / Athena / Apollo) “contratan” a los agentes obreros creando archivos .md dentro del directorio {project_dir}/workers/. Cada archivo tiene un frontmatter YAML fijo:

---
reports_to: ares          # A quién informa
role: Frontend Engineer   # Descripción de la responsabilidad
model: mid                # Qué modelo usar
---

# Frontend Engineer

Eres un ingeniero frontend. Te encargarás de implementar componentes de UI y la lógica de interacción.

Cuando el Manager asigna tareas a un agente obrero, solo asigna una tarea por ciclo — no se permite meter cinco tareas a la vez. Cuando el obrero termina, el Manager lee el note.md dentro del espacio de trabajo para entender el contexto y, a partir de ahí, decide el siguiente paso.

Cómo se comunican los agents

Entre agentes, no se chatean directamente: la coordinación se hace mediante un Issue Tracker integrado:

• Ares necesita el criterio de Athena → crea un Issue en el Issue Tracker y lo asigna a Athena
• El Worker se encuentra con un problema → crea un Issue y el Manager lo verá y lo tratará
• Se requiere intervención humana → crea un GitHub Issue con el título que comienza con HUMAN:. Inicia sesión en GitHub para atenderlo

---

Demo del flujo completo de desarrollo

Paso 1: Crear el proyecto mediante Dashboard

Abre el Dashboard y haz clic en New Project:

Repository: https://github.com/your-username/your-repo
Provider: Anthropic
Model: claude-sonnet-4

Después de crear el proyecto, aparecerá una tarjeta en el Dashboard con el estado PLANNING: Athena empieza a trabajar.

Paso 2: Observar el proceso de planificación de Athena

En el panel Agent Reports del Dashboard, puedes ver la salida de Athena. Está haciendo cosas como:

• Lee el README del proyecto y el código existente para entender la situación actual
• Busca soluciones técnicas relacionadas y mejores prácticas
• Evalúa la viabilidad de los requisitos
• Define el primer hito y su presupuesto (cuántos Cycle)

Cuando se completa la definición del hito, el sistema cambia automáticamente a la fase IMPLEMENTATION y Ares entra en escena.

Paso 3: Ares implementa y ejecuta

El estado en el Dashboard cambia a IMPLEMENTATION y Ares empieza a trabajar:

1. Contratar obreros — Ares crea archivos como workers/leo.md y workers/maya.md
2. Asignar tareas — En cada Cycle se asigna solo una tarea concreta a un obrero
3. Revisar PR — Después de que el obrero envía un PR, Ares hace Code Review
4. Control del Cycle — Si un Cycle no se completa, se devuelve para reintentar en el siguiente Cycle

Puedes enviar mensajes directamente a Ares desde el panel Chat del Dashboard para ajustar la dirección o añadir contexto.

Paso 4: Apollo hace la aceptación

Cuando Ares anuncia que el hito está completado, el sistema cambia a VERIFICATION y Apollo entra:

→ Apollo lee los cambios de código
→ Ejecuta pruebas de verificación (a través de GitHub Actions)
→ Comprueba si cumple los requisitos del hito
→ Si pasa → entra al siguiente PLANNING
→ Si no pasa → devuelve a IMPLEMENTATION e indica qué está mal

El estándar de Apollo es un nivel más alto que el de Ares, por eso a menudo ocurre que «Ares piensa que ya está bien, pero Apollo lo devuelve»; eso es un diseño normal, no un bug.

Paso 5: Intervención humana (si hace falta)

Cuando el Agent se enfrenta a algo que realmente requiere juicio humano, crea un GitHub Issue que empieza con HUMAN::

HUMAN: ¿En la página de inicio de sesión usamos OAuth o nombre de usuario y contraseña?
Responde a este Issue en GitHub y el Agent continuará según tu respuesta.

Después de que respondas, Ares continúa ejecutando. Si consideras que no hace falta intervenir, puedes pausar el proyecto directamente en el Dashboard.

---

Detalles de funciones del Dashboard

El Dashboard de TheBotCompany es el centro de control de todo el sistema: todos los estados se ven de un vistazo.

Resumen de proyectos

La página de inicio del Dashboard muestra todas las tarjetas de los proyectos. Cada tarjeta muestra:

• Etapa actual (PLANNING / IMPLEMENTATION / VERIFICATION)
• Conteo actual de Cycle / Epoch
• Barra de progreso de hitos
• Resumen del último Agent Report

Agent Reports

Historial de las salidas de cada agente del proyecto; permite renderizado de Markdown y resúmenes automáticos. Si la salida de algún Cycle es especialmente larga, el Dashboard la comprime automáticamente y muestra solo las conclusiones clave.

Issue Tracker

Aquí es donde se coordina todo entre los agents:

• Filtrar por proyecto
• Filtrar por estado (Open / In Progress / Resolved)
• Filtrar por Agent
• Panel exclusivo Human Issues, donde se listan todas las solicitudes de escalamiento que necesitas gestionar

Chat

Dentro del Dashboard hay un acceso directo al diálogo: puedes elegir cualquier proyecto, enviar mensajes al Manager correspondiente para añadir contexto o ajustar la dirección. Soporta respuestas en streaming y carga de imágenes.

Cost Tracking

Detalle de costos de cada proyecto y de cada agent:

• Coste del Last Cycle
• Promedio de coste de 24 horas
• Coste total acumulado

En conjunto con Budget Controls, puedes configurar un límite móvil de presupuesto para 24 horas; al superarlo, los Agents entran en modo descanso automáticamente.

Controls

Botones de control rápido en el Dashboard:

• Pause / Resume — Pausar y reanudar el proyecto (requiere iniciar sesión)
• Skip Sleep — Saltar el intervalo de descanso predefinido e iniciar el siguiente Cycle de inmediato
• Kill Run / Cycle / Epoch — Terminar forzosamente la ejecución actual
• Bootstrap — Reiniciar desde el hito especificado

---

Gestión de múltiples Providers y Key Pool

Lista de Providers soportados

TheBotCompany incluye soporte para 15+ tipos de LLM Provider:

Cómo funciona el Key Pool

En el panel de Keys dentro de Settings, puedes agregar varias claves para el mismo Provider y configurar el orden de prioridad. Durante la ejecución:

1. El sistema usa primero la key con mayor prioridad
2. Esa key dispara un rate limit (429) o no tiene cuota → se cambia automáticamente a la siguiente key
3. Al terminar el tiempo de enfriamiento, la key vuelve a estar disponible y se reintegra al rotador

Esto es especialmente útil para proyectos con ejecuciones largas: no tienes que preocuparte por que el consumo de una sola key deje parado a todo el equipo de Agents.

Configuración de Model Tier

Cada proyecto puede personalizar qué modelos se usan en cada nivel:

# .tbc/config.yaml a nivel de proyecto
model_tiers:
  high: claude-opus-4       # Arquitecturas complejas, razonamiento profundo
  mid: claude-sonnet-4      # Predeterminado: equilibrio entre capacidad y costo
  low: claude-haiku-3       # Tareas simples y repetitivas, formateo

También puedes modificarlo directamente desde el panel Model Tier Overrides en Settings mediante UI, sin tocar archivos de configuración.

---

Solución de problemas frecuentes

P1: Después de tbc start, no se abre el Dashboard y muestra Connection Refused

Causa: el puerto está ocupado o el servicio no se inició correctamente.

Pasos de verificación:

# 1. Comprueba si tbc está en ejecución
tbc status

# 2. Si no está en ejecución, inicia manualmente y mira la salida de error
tbc dev

# 3. Si el puerto está ocupado, especifica otro puerto
TBC_PORT=3200 tbc start

---

P2: El equipo de Agents se queda siempre en PLANNING y no entra en IMPLEMENTATION

Causa: Athena está haciendo una investigación profunda o esperando los resultados de los agents obreros; aún no ha definido los hitos.

Solución:

En el Dashboard abre → Agent Reports y revisa la salida más reciente de Athena. Si está esperando los resultados de un obrero, puedes usar /tbc logs para comprobar si el servidor está bloqueado. Si efectivamente está trabado, envía un mensaje a Athena desde el panel Chat en el Dashboard: «Define el primer hito con la información actual; no hace falta esperar más investigación.»

---

P3: No se crea el PR de GitHub automáticamente; en el Issue Tracker el Agent reporta un error de permisos

Causa: gh CLI no está autenticado correctamente, o el token no tiene permisos suficientes.

Pasos de verificación:

# 1. Revisa el estado de inicio de sesión de gh
gh auth status

# 2. Si no has iniciado sesión, vuelve a autenticar (requiere permisos de repo)
gh auth login --scopes repo

# 3. Confirma que el remote URL del directorio del proyecto es correcto
cd /path/to/your-project
git remote -v

---

P4: Apollo siempre devuelve la implementación de Ares, provocando un bucle infinito de Cycle

Causa: la dirección de corrección que plantea Ares no coincide con lo que espera Apollo, o la definición del hito no es lo suficientemente clara.

Solución:

En el panel Chat del Dashboard envía a Ares: «La razón por la que Apollo devuelve es [pega el comentario específico del Apollo Report]. Antes de corregir, asegúrate de entender el estándar de Apollo y confirma con Apollo la dirección de la corrección.»

Si el estándar de Apollo es demasiado estricto, en la fase PLANNING puedes pedir a Athena que ajuste los criterios de aceptación del hito.

---

P5: Los costos están muy por encima de lo esperado y quieres pausar todos los Agents de inmediato

Solución:

# Opción 1: Operación desde Dashboard
# Inicia sesión en Dashboard → tarjeta de cada proyecto → Controls → Pause

# Opción 2: Pausar con CLI
tbc stop

# Opción 3: Configurar un límite de presupuesto (se aplica al próximo arranque)
# En Dashboard Settings → Budget Controls, configura un límite de presupuesto de 24h

---

P6: Agregaste varias API Key, pero el Agent siempre usa la misma key y se excede el límite

Causa: el orden de prioridad del Key Pool puede estar mal, o el enfriamiento de la tasa de la key aún no ha terminado.

Solución:

En el panel de Keys de Dashboard Settings, revisa el estado de cada key:

• Active — en uso normal
• Cooldown — activó rate limit y está en enfriamiento
• Exhausted — cuota agotada

Si alguna key está en Cooldown durante mucho tiempo, muévela manualmente al final de la lista de keys para que el sistema cambie a la siguiente.

---

Lecturas adicionales y direcciones avanzadas

1. Personalizar habilidades de agentes obreros

Crea nuevos archivos .md en el directorio workers/ para ampliar las capacidades del equipo:

---
reports_to: ares
role: DevOps Engineer
model: mid
---

# DevOps Engineer

Eres un ingeniero DevOps con dominio de pipelines CI/CD, contenedorización e infraestructura como código.

El Manager detectará automáticamente los nuevos agents obreros y pueden ser programados en el siguiente Cycle.

2. Personalizar integración de Provider

Si necesitas conectar un servicio de LLM interno de la empresa (formato compatible con OpenAI o Anthropic), en Settings → Keys → Add Custom Provider:

{
  "name": "my-internal-llm",
  "baseUrl": "https://llm.internal.company.com/v1",
  "apiKey": "sk-internal-...",
  "model": "gpt-4"
}

3. Integración profunda con GitHub Actions

El diseño de Agents de TheBotCompany anima a ejecutar pruebas y builds que consumen tiempo dentro de GitHub Actions. En los archivos de habilidades de los agents obreros, especifica:

Nunca ejecutes pruebas de más de 5 minutos directamente en la terminal. Todos los suites de pruebas deben dispararse mediante GitHub Actions.

Así, cuando el Agent sea eliminado por timeout en un Cycle, el código ya enviado y los resultados de CI no se perderán.

4. Gestión de múltiples proyectos y visión general

Si estás ejecutando varios proyectos al mismo tiempo (mantenimiento open source, Side Project y proyectos comerciales), el Dashboard unificado de TheBotCompany te permite ver en una sola página el estado, el gasto y la distribución de problemas de todos los proyectos. Usa los Project Filters superiores para cambiar rápido; el panel de Human Issues centraliza todas las solicitudes de escalamiento, para que no se te escape ningún punto que requiera tu decisión.

5. Control fino de presupuesto y costos

El límite móvil predeterminado de 24 horas es global. Si quieres asignar presupuestos distintos a diferentes proyectos, puedes ejecutar múltiples instancias de TheBotCompany (en diferentes directorios TBC_HOME): cada instancia gestiona de forma independiente un conjunto de proyectos y presupuestos, sin interferir entre sí.