Esencia del patron
Code-Execution Agent es un patron en el que el agente no solo razona en texto, sino que ejecuta codigo generado en un entorno controlado, obtiene un resultado factual y continua con ese resultado.
Cuando usarlo: cuando la respuesta debe calcularse o verificarse ejecutando codigo, y no solo generarse en texto.
El agente:
Generate: genera codigo corto para la tareaRun: lo ejecuta en sandboxObserve: obtiene resultado realExplain: devuelve resultado con explicacion
Problema
Imagina que pides:
"Calcula la conversion promedio de este CSV."
El agente escribe un script y dice: "La conversion promedio es 3.84%".
Pero sin un entorno controlado no ves:
- que se ejecuto exactamente
- que archivos se leyeron
- si hubo intentos de llamadas de red
- cuantos recursos consumio el codigo
En ejecucion de codigo importa no solo la logica, sino tambien los limites del entorno donde corre.
Ese es el problema: el resultado depende al mismo tiempo del codigo y del entorno de ejecucion, por eso "solo ejecutar" es inseguro y opaco.
Solucion
Code-Execution Agent ejecuta codigo solo a traves de una capa de ejecucion controlada.
Analogia: es como un laboratorio con reglas de seguridad. El experimento solo se permite en una sala aislada y bajo politicas. Esto reduce el riesgo de dañar el entorno o extraer datos de mas.
Principio clave: el modelo puede escribir codigo, pero la ejecucion se permite solo en sandbox y despues de revisar policy.
Restricciones base:
- sandbox runtime
- acceso restringido a archivos
- sin red
- limites de CPU/RAM/tiempo
Ciclo controlado:
- Planificacion: definir el script minimo para la tarea
- Generacion: producir codigo
- Policy check: validar seguridad y operaciones permitidas
- Ejecucion aislada: correr codigo en sandbox
- Validacion de resultado: verificar correccion y riesgo del output
Si falla el policy check o la validacion, la ejecucion se detiene o se escala.
Esto protege contra casos donde el agente podria:
- leer archivos sensibles
- enviar datos afuera
- quedar colgado en bucles largos
- ejecutar operaciones peligrosas
La ejecucion confiable no es "solo correr", es correr de una forma que runtime-policy no pueda saltarse tecnicamente.
Como funciona
Elemento clave: la sandbox.
Suele limitar:
sistema de archivos: acceso solo al directorio de trabajored: normalmente desactivada por completorecursos:CPU/RAM/time quotasentorno runtime: bibliotecas y syscalls permitidos
Descripcion completa del flujo: Plan → Generate Code → Policy Check → Execution Layer → Sandbox Run → Validate → Return
Planificacion
El agente define que debe calcularse exactamente y que formato de salida se espera.
Generacion de codigo
El modelo genera codigo minimo para el paso especifico, sin volumen innecesario.
Policy check
El codigo generado pasa por policy-engine: bibliotecas permitidas, tipo de computo y nivel de consumo aceptable.
Capa de ejecucion
El sistema prepara ejecucion controlada: entorno, limites y reglas de acceso.
Sandbox run
El codigo se ejecuta aislado con limites estrictos.
Validacion
El sistema revisa formato de salida, errores, policies de seguridad y conformidad con esquema esperado.
Retorno
El usuario recibe respuesta valida o stop/escalado controlado.
En codigo se ve asi
code = agent.generate_code(goal, constraints={
"language": "python",
"no_network": True,
"max_seconds": 5,
})
exec_result = execution_layer.run_code(
code=code,
policy="sandboxed_python",
)
if not exec_result.success:
return fallback_or_stop(exec_result.error)
validated = validate_output(exec_result.stdout, schema=expected_schema)
if not validated.ok:
return stop_with_reason(validated.reason)
return format_answer(validated.data)
Regla principal: nunca ejecutar codigo generado fuera de control sandbox y policy.
Como se ve durante la ejecucion
Goal: calcular conversion sobre reporte CSV
Generate Code:
- leer sales.csv
- calcular conversion_rate = paid / leads
- mostrar tabla por dia
Sandbox Run:
- timeout: 5s
- memory: 256MB
- network: disabled
Output:
- tabla con 7 filas
- conversion promedio: 3.84%
Ejemplo completo de agente Code-Execution
Cuando encaja - y cuando no
Encaja
| Situacion | Por que Code-Execution encaja | |
|---|---|---|
| ✅ | Se necesitan calculos reales, no suposiciones de texto | La ejecucion de codigo da resultados factuales en vez de estimaciones del modelo. |
| ✅ | Trabajo con tablas, archivos, formulas | Aqui hace falta ejecutar pasos de verdad, no solo describirlos. |
| ✅ | Importa la reproducibilidad del resultado | Correr en entorno controlado hace mas facil verificar resultados. |
| ✅ | Hay sandbox + policies aplicadas de forma obligatoria | La infraestructura segura permite ejecutar codigo sin riesgos criticos. |
No encaja
| Situacion | Por que Code-Execution no encaja | |
|---|---|---|
| ❌ | Tarea puramente textual | Ejecutar codigo agrega complejidad sin beneficio. |
| ❌ | No hay entorno de ejecucion aislado | Sin sandbox no se puede ejecutar codigo generado de forma segura. |
| ❌ | El riesgo es mayor que el beneficio | El daño potencial no justifica este enfoque en este caso. |
Porque ejecutar codigo agrega requisitos operativos: sandbox, limites de recursos, monitoreo y auditoria de ejecuciones.
Diferencia frente a Guarded-Policy
| Guarded-Policy | Code-Execution | |
|---|---|---|
| Foco principal | Que se permite ejecutar | Como ejecutar codigo generado de forma segura |
| Mecanismo clave | Policy gate | Sandbox runtime + validacion de output |
| Cuando se activa | Antes de la accion | Durante y despues de ejecutar codigo |
| Riesgo sin patron | Una accion peligrosa llega a ejecucion | Resultados de ejecucion inseguros o no confiables |
Guarded-Policy decide si se puede actuar. Code-Execution decide como ejecutar la accion de codigo de forma segura y reproducible.
Cuando usar Code-Execution (vs otros patrones)
Usa Code-Execution cuando el agente debe ejecutar codigo, validar resultados e iterar de forma segura.
Test rapido:
- si necesitas "ejecutar codigo y trabajar con output factual" -> Code-Execution
- si necesitas "primero solo dividir una tarea grande en subtareas" -> Task Decomposition Agent
Comparacion con otros patrones y ejemplos
Guia rapida:
| Si la tarea se ve asi... | Usa |
|---|---|
| Despues de cada paso debes decidir que hacer despues | ReAct Agent |
| Primero debes dividir un objetivo grande en tareas ejecutables pequeñas | Task Decomposition Agent |
| Necesitas ejecutar codigo, validar resultados e iterar con seguridad | Code Execution Agent |
| Necesitas analizar datos y devolver conclusiones | Data Analysis Agent |
| Necesitas investigacion multi-fuente con evidencia estructurada | Research Agent |
Ejemplos:
ReAct: "Encuentra causa de caida de API: revisa logs -> mira errores -> ejecuta la siguiente verificacion segun el resultado."
Task Decomposition: "Prepara lanzamiento de nuevo plan: divide en subtareas de contenido, tecnica, QA y soporte."
Code Execution: "Calcula retencion de 12 meses en Python y valida formulas con datos reales."
Data Analysis: "Analiza un CSV de ventas: encuentra tendencias, anomalias y da conclusiones breves."
Research: "Reune datos de 5 competidores desde varias fuentes y arma un resumen comparativo."
Como combinar con otros patrones
- Code-Execution + Guarded-Policy: antes de correr, el agente revisa codigo con reglas de seguridad y bloquea acciones peligrosas.
- Code-Execution + Fallback-Recovery: si la ejecucion se cuelga o falla, el agente pasa a un escenario fallback seguro.
- Code-Execution + Supervisor: ejecuciones riesgosas no se ejecutan automatico; se mandan a aprobacion humana.
Resumen
Code-Execution Agent:
- Genera codigo para una tarea concreta
- Lo ejecuta en sandbox aislada
- Valida output antes de responder
- Mejora precision en tareas de calculo
Ventajas y Desventajas
Ventajas
da resultados mas precisos en calculos
resultado facil de verificar y repetir
se ve que codigo se ejecuto realmente
comodidad para trabajar con archivos y datos
Desventajas
requiere entorno de ejecucion aislado
la respuesta puede ser mas lenta por ejecutar codigo
pueden ocurrir errores en tiempo de ejecucion
FAQ
Q: Se puede ejecutar codigo directo en servidor sin aislamiento?
A: Para produccion: no. Se necesita aislamiento, limites de recursos y control de operaciones permitidas.
Q: Ejecutar codigo garantiza que el resultado sea correcto?
A: No del todo. Hace falta validacion de salida, pruebas de invariantes y checks de policy.
Q: Que hacer si el codigo falla durante ejecucion?
A: Aplicar recuperacion acotada: retry, entorno de ejecucion de respaldo o stop controlado con stop reason.
Que sigue
El enfoque Code-Execution permite al agente ejecutar calculos de forma confiable.
Pero como aplicarlo a analitica completa: limpieza de datos, agregados, graficos y conclusiones?