Construyamos el entorno de ejecución de Claude Code (paso a paso)

Cubriremos todo lo que implica construir un arnés de codificación: el bucle del agente, la planificación, los subagentes, el sandboxing, la memoria y los puntos de control, todo construido paso a paso.

Si alguna vez has intentado construir tu propio agente de codificación, sabes cómo funciona esto. Conectas un modelo a herramientas de archivos y una terminal, lo apuntas a un código real y se rompe en menos de una docena de llamadas a herramientas.

Lee los archivos incorrectos, pierde el objetivo a mitad de camino y llena su contexto con resultados que ya no necesita.

Luego, la misma tarea pasa por Claude Code y se completa limpiamente. La conclusión fácil es que Anthropic simplemente tiene un mejor modelo, y esa conclusión ignora dónde ocurre realmente el trabajo.

La diferencia es el arnés. Un arnés es el código común que envuelve al modelo, y maneja la planificación, la ejecución de herramientas, la memoria y la seguridad, mientras que el modelo solo decide el siguiente paso.

Así es como se ve un agente completamente equipado cuando lo dibujas:

GIF

La imagen parece compleja, pero se divide en cuatro grupos:

• Memoria alimenta al modelo con su contexto de trabajo más los hechos que ha aprendido entre sesiones.
• Habilidades codifican cómo debe operar el agente, es decir, los procedimientos, restricciones y heurísticas que sigue.
• Protocolos conectan al agente con usuarios, herramientas y otros agentes.
• El núcleo del arnés lo une todo con orquestación de subagentes, un sandbox, un evaluador, un bucle de aprobación, observabilidad y compresión de contexto.

Anthropic describe esta división como el cerebro y las manos. El modelo es el cerebro que elige cada acción, y el arnés son las manos que la ejecutan y mantienen el proceso en marcha.

Así que la brecha entre tu agente y Claude Code no es el modelo, es la maquinaria que rodea al modelo.

Claude Code es uno de los arneses más capaces en producción hoy en día, y está construido a partir de un conjunto sorprendentemente pequeño de las capas de esa ilustración. Para ver cuánta de esa maquinaria tendrías que construir tú mismo, lo reconstruí en CrewAI, un framework de código abierto para orquestar agentes.

Más de lo que esperaba se asigna a funciones integradas, y la parte que no lo hace es donde reside la verdadera ingeniería.

Construyámoslo capa por capa, comenzando con el bucle central y añadiendo planificación, subagentes, sandboxing y memoria. En cada paso marcaremos dónde termina el framework y dónde comienza tu trabajo.

Cómo funciona el arnés de Claude Code

En el centro de Claude Code hay un bucle de agente simple. Le envías un mensaje, el modelo decide qué hacer a continuación, y responde directamente o solicita una herramienta. Si solicita una, la herramienta se ejecuta, el resultado vuelve a la conversación y el modelo decide de nuevo.

Esto se repite hasta que el modelo devuelve una respuesta final sin más llamadas a herramientas.

Dentro de ese bucle, el modelo lee archivos, edita código, ejecuta comandos de terminal y ejecuta pruebas. No son modos separados. Son solo diferentes llamadas a herramientas dentro del mismo bucle.

Sin embargo, el bucle por sí solo no es suficiente para un agente de codificación confiable. Claude Code añade planificación, herramientas de archivos, subagentes, memoria y un sistema de permisos y sandbox a su alrededor. Estas capas no reemplazan el bucle, lo hacen seguro y confiable para el trabajo real.

Esa es la arquitectura que reconstruiremos: primero el bucle central, luego cada capa encima, asignando cada capa a la función de CrewAI que la maneja.

El bucle central del agente

El bucle ejecuta la misma secuencia hasta que la tarea está completada:

1. Pide al modelo que realice la tarea.
2. El modelo responde directamente o solicita una o más herramientas.
3. Si se solicitan herramientas, ejecútalas y devuelve los resultados al modelo.
4. Repite con la conversación actualizada.
5. Cuando el modelo responde sin solicitar ninguna herramienta, la tarea está completa.

1while True:
2    reply = model(messages, tools)
3    calls = [b for b in reply if b.type == "tool_use"]
4    if not calls:            # texto plano, sin llamada a herramienta: el trabajo está hecho
5        return reply.text
6    messages += [reply, run_all(calls)]

Cada llamada a herramienta completa un paso, proporciona nueva información al modelo y alimenta la siguiente decisión. Una pregunta simple podría terminar en una iteración, mientras que corregir un error complejo o refactorizar un código grande puede requerir docenas de iteraciones antes de que el modelo tenga suficiente para producir una respuesta final.

CrewAI proporciona este bucle de ejecución automáticamente en cuanto creas un agente. No implementas el bucle while tú mismo, defines el agente y le asignas una tarea.

Construyendo el primer agente

Creemos un agente simple de Corrección de Errores.

1from crewai import LLM, Agent, Crew, Task
2
3bug_fixer = Agent(
4    role="Corrector de Errores",
5    goal="Encontrar y describir la solución para el error reportado en el código.",
6    backstory="Lees directorios y archivos para construir una imagen precisa del código.",
7    llm="claude-sonnet-4-6",
8)
9
10task = Task(
11    description="Encuentra la solución para {objective}.",
12    expected_output="Una breve descripción de la solución y en qué archivo se encuentra.",
13)
14
15result = Crew(agents=[bug_fixer], tasks=[task]).kickoff(
16    inputs={"objective": "el error de sobregiro en account.py"}
17)

Tres conceptos que entender aquí:

• Un Agente define quién hace el trabajo, a través de su rol, objetivo, LLM y herramientas.
• Una Tarea describe la asignación.
• Un Equipo reúne agentes y tareas. Llamar a kickoff() ejecuta el mismo bucle de ejecución descrito anteriormente, independientemente de si el modelo subyacente es de Anthropic, OpenAI, Google u otro.

Dándole herramientas al agente

Las herramientas son lo que permite que un modelo que solo genera texto realmente trabaje en un código. Leen archivos, los escriben, ejecutan comandos de terminal y llaman a APIs externas.

CrewAI incluye herramientas del sistema de archivos listas para usar:

• FileReadTool lee archivos.
• DirectoryReadTool lista directorios.
• FileWriterTool escribe archivos.

1from crewai_tools import DirectoryReadTool, FileReadTool, FileWriterTool
2
3read_file = FileReadTool()
4write_file = FileWriterTool()
5list_dir = DirectoryReadTool()
6
7filesystem_tools = [read_file, write_file, list_dir]

Estas también funcionan como memoria externa. En lugar de mantener un resultado de búsqueda grande en la ventana de contexto del modelo, el agente puede escribirlo en un archivo, conservar solo el nombre del archivo y leerlo cuando sea necesario.

Esto mantiene la ventana de contexto más pequeña y al modelo más enfocado, lo que Anthropic llama ingeniería de contexto.

Las herramientas integradas cubren solo flujos de trabajo comunes. Para algo más específico, expones una función de Python como herramienta con el decorador @tool.

El docstring actúa como manual de instrucciones, indicando al modelo qué hace la herramienta, cuándo usarla y qué espera como entrada.

1from crewai.tools import tool
2import subprocess
3
4@tool("run_tests")
5def run_tests(path: str = "tests/") -> str:
6    """Ejecuta la suite de pruebas pytest en la ruta dada y devuelve el resultado."""
7    result = subprocess.run(
8        ["pytest", path, "-q"], capture_output=True, text=True, timeout=120
9    )
10    output = result.stdout + result.stderr
11    return output[-4000:] if len(output) > 4000 else output

Planificación de tareas de larga duración

A medida que las tareas se vuelven más complejas, un bucle de ejecución simple comienza a perder de vista el objetivo original. Después de suficientes llamadas a herramientas, lecturas de archivos y resultados intermedios, el contexto se llena y el objetivo se ve desplazado por todo lo que vino después.

Esta degradación lenta es lo que la gente llama deterioro del contexto.

La planificación lo aborda directamente. El agente construye un plan paso a paso antes de hacer cualquier trabajo y mantiene ese plan en contexto durante toda la ejecución.

El plan no hace el trabajo. Es una hoja de ruta que mantiene al modelo conectado con el objetivo original, que es la misma función que hace la lista de tareas de Claude Code.

CrewAI añade esto a nivel de equipo con planning=True. Genera un plan antes de la ejecución y lo mantiene disponible a medida que avanza la tarea.

1from crewai import Crew, LLM
2
3crew = Crew(
4    agents=self.agents,
5    tasks=self.tasks,
6    planning=True,
7    planning_llm=LLM(model="gpt-4o-mini"),
8)

Nota: Por defecto, CrewAI usa gpt-4o-mini para la planificación, y puedes cambiar cualquier LLM que prefieras para ese paso.

Los agentes individuales también pueden razonar sobre su propio trabajo con reasoning=True:

1from crewai import Agent
2
3bug_fixer = Agent(
4    role="Corrector de Errores",
5    goal="Encontrar y describir la solución para el error reportado en el código.",
6    backstory="Lees directorios y archivos para construir una imagen precisa del código.",
7    tools=[FileReadTool()],
8    reasoning=True,
9    max_reasoning_attempts=3  # Opcional: Establece un número máximo de intentos de razonamiento
10)

La planificación y el razonamiento resuelven problemas diferentes. La planificación construye una hoja de ruta de alto nivel para la tarea general, mientras que el razonamiento le da tiempo a un agente para pensar su propio enfoque antes de actuar.

Cuando el razonamiento está habilitado, el agente:

1. Reflexiona sobre la tarea y redacta un plan de ejecución.
2. Evalúa si el plan está listo.
3. Refina el plan si es necesario, hasta que esté satisfecho o alcance max_reasoning_attempts.
4. Inyecta el plan de razonamiento finalizado en la tarea antes de la ejecución.

Juntos, mantienen al agente anclado en tareas de larga duración y reducen la desviación del objetivo original.

Delegación con subagentes

La planificación mantiene al agente enfocado, pero no reduce la cantidad de información que el modelo tiene que retener. En un código grande, incluso una tarea bien planificada puede exceder una sola ventana de contexto.

Encontrar un error puede requerir leer docenas de archivos, y el agente principal no necesita mantenerlos todos en memoria.

Los subagentes resuelven esto mediante la delegación. El agente principal asigna una tarea específica a un agente ayudante, que trabaja en su propio contexto y devuelve un resumen breve. El agente principal ve la conclusión, no los pasos intermedios.

CrewAI admite esto a través de flujos de trabajo jerárquicos, donde un agente gerente delega a agentes especialistas y combina sus resultados.

En nuestra configuración anterior, un solo agente de Corrección de Errores hacía todo el trabajo pesado. Dividamos el trabajo entre un gerente y tres especialistas:

• Explorador de Código explora el código y mapea el repositorio.
• Ingeniero de Software implementa el cambio solicitado.
• Ejecutor de Pruebas ejecuta las pruebas en el sandbox e informa si pasan o fallan.
• Líder de Ingeniería supervisa a los tres especialistas.

1from crewai import Crew, Agent, Task, Process
2
3explorer = Agent(
4    role="Explorador de Código",
5    goal="Mapear el repositorio y sacar a la luz los archivos relevantes para la tarea.",
6    backstory="Lees directorios y archivos para construir una imagen del código.",
7    tools=[read_file, list_dir],
8    llm=llm,
9)  # Lo mismo para los otros dos agentes especialistas
10
11manager = Agent(
12    role="Líder de Ingeniería",
13    goal="Dividir la solicitud en pasos y delegar cada uno al especialista adecuado.",
14    backstory="Decides quién hace qué, revisas las pruebas, terminas cuando el cambio está hecho.",
15    llm=llm,
16    allow_delegation=True,
17)
18
19crew = Crew(
20    agents=[explorer, coder, tester],
21    tasks=[task],
22    manager_agent=manager,
23    process=Process.hierarchical,
24)

Una cosa a tener en cuenta es que allow_delegation está deshabilitado por defecto, por lo que debe habilitarse explícitamente en el gerente.

Sandboxing: Asegurando la ejecución del agente

Un agente con acceso a la terminal puede ejecutar un comando destructivo, y decirle al modelo que no haga algo no es una salvaguarda.

La protección real proviene de dos capas:

1. Un sistema de permisos que requiere aprobación para acciones sensibles.
2. Un sandbox que aísla la ejecución, de modo que incluso los comandos aprobados no puedan tocar la máquina anfitriona.

Anthropic utiliza el mismo enfoque. Mover la ejecución de código a un sandbox reduce la frecuencia con la que un usuario necesita aprobar acciones, mientras sigue protegiendo el sistema anfitrión.

Sandboxing en CrewAI

Ejecutar código dentro de un sandbox en lugar de en la máquina anfitriona aplica esa segunda capa. En esta configuración, el código se ejecuta dentro de E2B, que inicia una VM nueva por sesión y la destruye después.

Los comandos de terminal y Python se ejecutan completamente dentro de ese entorno aislado.

1from crewai_tools import E2BExecTool, E2BPythonTool
2sandbox_tools = [E2BExecTool(), E2BPythonTool()]  # ejecutar pruebas / ejecutar código

Aprobación humana en el bucle

Establecer human_input=True en una Tarea pausa el equipo después de que genera una respuesta. Revisas la salida, luego la apruebas o la envías de vuelta para otra iteración.

Cuando la ejecución alcanza esa tarea, CrewAI espera tu retroalimentación a través de la entrada estándar.

1from crewai import Task
2
3task = Task(
4    description=(
5        "En el directorio de trabajo ./workspace, {objective}. "
6        "Explora el código primero, haz el cambio, luego ejecuta las pruebas e informa."
7    ),
8    expected_output="Un resumen de los archivos modificados y el resultado final de las pruebas.",
9    human_input=True,
10)

Si tu equipo se ejecuta detrás de una aplicación web o interfaz de chat en lugar de una terminal, el sistema de bucle humano basado en webhooks de CrewAI maneja el mismo paso de revisión.

Memoria y puntos de control

Por defecto, un agente olvida todo una vez que termina una ejecución. Vuelve mañana para corregir otro error en el mismo proyecto y comienza desde cero.

Dos mecanismos permiten que un agente lleve información entre ejecuciones, y cada uno sirve a un propósito diferente:

• Puntos de control guardan el estado del agente durante una ejecución, para que pueda reanudarse después de una interrupción o continuar desde el mismo punto por un camino diferente.
• Memoria persistente almacena hechos a través de conversaciones separadas, incluyendo preferencias del proyecto como "siempre formatea el código final antes de terminar".

Memoria en CrewAI

CrewAI proporciona una interfaz de Memoria unificada en lugar de tipos separados de memoria a corto plazo, a largo plazo, de entidades y externa. Al guardar, usa un LLM para identificar detalles importantes, organizarlos y hacerlos recuperables más tarde.

Establecer memory=True en el equipo le da memoria entre ejecuciones. Después de cada tarea, CrewAI extrae hechos útiles de la salida y los almacena, y en ejecuciones futuras recupera recuerdos relevantes y los añade al prompt de la tarea.

1from crewai import Crew
2
3crew = Crew(
4    agents=[explorer, coder, tester],
5    tasks=[task],
6    memory=True,
7)

Todos los agentes en un equipo comparten su memoria a menos que a un agente se le dé la suya propia.

Puntos de control en CrewAI

Un punto de control es una instantánea del progreso de un agente, incluyendo su configuración, estado de la tarea, memoria, resultados intermedios, entradas e historial de ejecución.

Por defecto, CrewAI crea un punto de control cada vez que una tarea termina, permitiendo que el flujo de trabajo se reanude desde ese punto si se interrumpe.

Los puntos de control pueden residir en uno de dos almacenes integrados:

• JsonProvider guarda cada punto de control como un archivo JSON separado, que es fácil de leer e inspeccionar manualmente.
• SqliteProvider almacena todos los puntos de control en una sola base de datos SQLite, que se comporta mejor bajo puntos de control frecuentes y cargas de trabajo más grandes.

1from crewai import Crew
2
3crew = Crew(
4    agents=[explorer, coder, tester],
5    tasks=[task],
6    checkpoint=True,
7)

Crew, Flow y Agent aceptan un argumento checkpoint, y los hijos heredan de su padre a menos que establezcan su propio valor.

Poniéndolo todo junto

Aquí está el arnés completo en una sola tarea, con el bucle de ejecución, herramientas, planificación, subagentes, sandboxing y memoria trabajando juntos:

1from crewai import Agent, Crew, LLM, Process, Task
2from crewai.tools import tool
3from crewai_tools import (DirectoryReadTool, FileReadTool, FileWriterTool,
4E2BExecTool, E2BPythonTool)
5
6llm = LLM(model="anthropic/claude-sonnet-4.6")
7
8list_dir = DirectoryReadTool(directory="./workspace")
9filesystem_tools = [FileReadTool(), FileWriterTool(), list_dir]
10sandbox_tools = [exec_tool, E2BPythonTool()]
11
12@tool("run_tests")
13def run_tests(path: str = "tests/") -> str:
14    """Sincroniza ./workspace en el sandbox, luego ejecuta pytest allí."""
15    return E2BExecTool().run(command=sync_and_test_command(path))
16
17explorer = Agent(role="Explorador de Código", goal="Mapear el repo, sacar archivos relevantes.",
18    tools=[read_file, list_dir], llm=llm)
19coder = Agent(role="Ingeniero de Software", goal="Implementar el cambio solicitado.",
20    tools=filesystem_tools, reasoning=True, llm=llm)
21tester = Agent(role="Ejecutor de Pruebas", goal="Ejecutar pruebas en el sandbox, informar éxito/fallo.",
22    tools=sandbox_tools + [read_file] + [run_tests], llm=llm)
23manager = Agent(role="Líder de Ingeniería", goal="Delegar pasos, terminar una vez que las pruebas pasen.",
24    allow_delegation=True, llm=llm)
25
26task = Task(
27    description="En ./workspace, {objective}. Explora, edita, prueba, informa.",
28    expected_output="Resumen de cambios y resultado de pruebas.", human_input=True,
29)
30crew = Crew(
31    agents=[explorer, coder, tester], tasks=[task],
32    manager_agent=manager, process=Process.hierarchical,
33    planning=True, memory=True, checkpoint=True,
34)
35result = crew.kickoff(inputs={"objective": "corregir pruebas fallidas en account.py"})

Los arneses de agente son más fáciles de evaluar cuando el éxito se puede verificar automáticamente. Un conjunto de pruebas le da al agente un objetivo concreto, para que pueda planificar, editar, probar y repetir hasta que todo pase.

Así que esto se probó contra un código pequeño, una clase BankAccount con dos errores reales y cinco pruebas, tres de las cuales fallaban. La regla era corregir solo la implementación, no las pruebas.

Esto refleja cómo Anthropic evalúa internamente a los agentes de codificación. Un ejemplo publicado tiene a Claude reconstruyendo un clon de la interfaz de claude.ai contra un gran conjunto de pruebas fallidas.

Aquí, el arnés llevó el proyecto de 3 fallas y 2 aciertos a todos 5 aciertos, con la regla de solo implementación cerrando el atajo de editar o eliminar las pruebas fallidas.

Lo que sigue siendo tu trabajo

Algunas partes del sistema no son cosas que el framework construya por ti:

• Los prompts. El comportamiento de cada agente proviene de su rol, objetivo e historia de fondo. Lograrlos bien requiere pruebas e iteración, y ninguna bandera de configuración lo sustituye.
• El entorno de ejecución. El sandbox, ya sea E2B o una VM autogestionada, debe configurarse y conectarse.
• Selección de herramientas. Qué herramientas recibe cada agente, y qué agente debe tener acceso a qué, es una decisión de diseño que el framework no toma.

También hay un costo en el propio arnés. La planificación, los subagentes y el bucle añaden llamadas a la API, por lo que una configuración compleja de agente puede terminar siendo más costosa que una tarea que una sola llamada al modelo habría resuelto directamente.

Y hay una limitación a largo plazo que vale la pena tener en cuenta. A medida que los modelos mejoran, parte del andamiaje deja de ser necesario, porque parte de lo que se construye en un arnés hoy es un parche para los límites actuales del modelo, no un requisito permanente.

Anthropic usaba originalmente reinicios de contexto para evitar que Claude Sonnet 4.5 terminara las tareas demasiado pronto, y ya no eran necesarios con el más capaz Claude Opus 4.5.

Conclusión

Ese es el hallazgo completo. La capacidad de un agente de codificación reside principalmente en el arnés, y un framework de orquestación te da más de ese arnés de lo que imaginas.

El bucle, la planificación, la delegación, el sandboxing y la memoria llegan como configuración, mientras que los prompts, el entorno de ejecución y la elección de herramientas siguen siendo tuyos.

Si quieres ejecutar esto contra tu propio código, los documentos de CrewAI cubren todas las funciones utilizadas aquí, y el framework es completamente de código abierto.

Consulta la documentación de CrewAI →

Encuentra todo el código aquí →

¡Gracias por leer!

¡Saludos! :)