Shell + Habilidades + Compactación: consejos para agentes de larga duración que hacen trabajo real

Estamos pasando de asistentes de un solo turno a agentes de larga duración que realizan trabajo del conocimiento real: leen grandes conjuntos de datos, actualizan archivos y desarrollan aplicaciones.

A partir de los comentarios de los desarrolladores y de nuestra experiencia al crear Codex y agentes internos, estamos lanzando un nuevo conjunto de primitivas para agentes que facilitan el trabajo de larga duración:

• Habilidades (alineadas con el estándar abierto Agent Skills): instrucciones reutilizables y versionadas que puedes montar en contenedores para que los agentes ejecuten tareas de forma más confiable.
• Herramienta de shell mejorada: un contenedor alojado por OpenAI con acceso controlado a Internet, donde un agente puede instalar dependencias, ejecutar scripts y escribir resultados (por ejemplo, informes y artefactos).
• Compactación del lado del servidor: una forma sencilla de compactar automáticamente las ejecuciones largas de agentes para que nunca alcances los límites de contexto.

La documentación y la referencia de la API cubren cada elemento anterior por separado. Esta publicación se centra en los consejos y patrones menos evidentes que mejor nos han funcionado hasta ahora, tanto en nuestro trabajo en OpenAI como en producción en Glean, uno de los primeros clientes en usar habilidades.

Un breve modelo mental

Habilidades: “procedimientos” que el modelo puede cargar cuando los necesita

Una habilidad es un conjunto de archivos junto con un archivo de manifiesto SKILL.md que contiene metadatos iniciales e instrucciones. Piensa en ella como una guía de procedimientos versionada que el modelo puede consultar cuando llega el momento de hacer trabajo real.

Cuando hay habilidades disponibles, la plataforma expone al modelo los campos name, description y path de cada habilidad. El modelo usa esos metadatos para decidir si debe invocar una habilidad. Si lo hace, lee SKILL.md para consultar el flujo de trabajo completo.

Herramienta de shell: “ejecución” para agentes

La herramienta de shell permite a los modelos trabajar en un entorno de terminal real, ya sea en:

• Contenedores alojados y administrados por OpenAI.
• Un entorno de ejecución de shell local que ejecutas tú mismo (con la misma semántica de la herramienta, pero tú controlas la máquina).

La terminal alojada en la nube se ejecuta a través de la API Responses, lo que significa que tus solicitudes incluyen trabajo con estado persistente, llamadas a herramientas, continuidad entre turnos y artefactos.

Compactación: mantener en marcha las ejecuciones largas

A medida que los flujos de trabajo se alargan, alcanzan los límites de la ventana de contexto. La compactación del lado del servidor mantiene en marcha las ejecuciones largas al administrar la ventana de contexto y comprimir automáticamente el historial de la conversación.

La compactación en la API Responses te ofrece dos formas de manejar esto:

• Compactación del lado del servidor (nueva): cuando el contexto supera el umbral, la compactación se ejecuta automáticamente durante la transmisión, por lo que no hay una llamada de compactación por separado.
• Punto de acceso independiente de compactación: usa /responses/compact cuando quieras controlar explícitamente cuándo se realiza la compactación.

Por qué funcionan mejor juntos

• Las habilidades reducen los enredos en los prompts al trasladar los procedimientos y ejemplos estables a un paquete reutilizable.
• El shell proporciona un entorno de ejecución completo que te permite instalar código, ejecutar scripts y escribir resultados.
• La compactación preserva la continuidad en las ejecuciones largas, de modo que el mismo flujo de trabajo puede seguir ejecutándose sin ajustes manuales minuciosos del contexto.
• En conjunto, obtienes flujos de trabajo repetibles con ejecución real, sin convertir tu prompt del sistema en un documento enorme y frágil.

Consejos y trucos

1) Escribe las descripciones de las habilidades como lógica de enrutamiento (no como textos publicitarios)

En la práctica, la descripción de tu habilidad define el criterio de decisión del modelo. Debe responder:

• ¿Cuándo debo usarla?
• ¿Cuándo no debo usarla?
• ¿Cuáles son los resultados y los criterios de éxito?

Un patrón práctico es incluir un bloque breve de “Cuándo usarla y cuándo no” directamente en la descripción, con información concreta (entradas, herramientas involucradas y artefactos esperados).

2) Agrega ejemplos negativos y casos límite para reducir las activaciones incorrectas

Un fallo sorprendente es que poner habilidades a disposición del modelo puede reducir inicialmente las activaciones correctas. Una solución que hemos visto funcionar es incluir ejemplos negativos y cubrir casos límite.

En la práctica, eso significa escribir algunos casos explícitos de “No invoques esta habilidad cuando...” (y qué hacer en su lugar). Esto ayuda al modelo a elegir con más precisión, especialmente cuando tienes varias habilidades que parecen similares a primera vista.

Glean lo observó directamente: el enrutamiento basado en habilidades redujo inicialmente las activaciones en alrededor de un 20 % en evaluaciones específicas; luego, estas se recuperaron tras agregar ejemplos negativos y cubrir casos límite en las descripciones.

3) Incluye las plantillas y los ejemplos dentro de la habilidad (prácticamente no tienen costo cuando no se usan)

Si has estado llenando el prompt del sistema de plantillas, deja de hacerlo.

Las plantillas y los ejemplos desarrollados dentro de las habilidades tienen dos ventajas:

• Están disponibles justo cuando se necesitan (al invocar la habilidad).
• No aumentan el consumo de tokens en consultas no relacionadas.

Esto es especialmente eficaz para los entregables del trabajo del conocimiento, como:

• Informes estructurados.
• Resúmenes de clasificación y priorización de casos escalados.
• Planes de cuentas.
• Informes de análisis de datos.

Glean informó que este patrón produjo algunas de sus mayores mejoras de calidad y latencia en producción, porque esos ejemplos solo se cargan cuando se activa la habilidad.

4) Diseña desde el principio para ejecuciones largas con reutilización de contenedores y compactación

Los agentes que trabajan durante períodos largos rara vez tienen éxito con un único prompt. Planifica la continuidad desde el principio:

• Reutiliza el mismo contenedor entre pasos cuando quieras mantener dependencias estables, archivos en caché y resultados intermedios.
• Pasa previous_response_id para que el modelo pueda continuar el trabajo en el mismo hilo.
• Usa la compactación como una primitiva predeterminada para ejecuciones largas, no como un recurso de emergencia.

Esta combinación reduce los reinicios y mantiene la coherencia de los trabajos de varios pasos a medida que crece el hilo.

5) Cuando necesites determinismo, indica explícitamente al modelo que use la habilidad

De forma predeterminada, el modelo decide cuándo usar una habilidad. A menudo, eso es lo que buscas.

Pero cuando ejecutas un flujo de trabajo en producción con un contrato claro (y prefieres un comportamiento determinista a uno ingenioso), basta con decir:

“Usa la habilidad <skill name>”.

Esta es la medida más sencilla que puedes tomar para mejorar la confiabilidad. Convierte un enrutamiento impreciso en un contrato explícito.

6) Trata las habilidades con acceso a la red como una combinación de alto riesgo (diseña para contenerlo)

Este es el consejo de seguridad que resulta fácil pasar por alto ahora, pero cuyas consecuencias son difíciles de corregir después.

Combinar habilidades con acceso abierto a la red crea una vía de alto riesgo para la exfiltración de datos. Si usas acceso a la red, mantén listas estrictas de destinos permitidos, trata los resultados de las herramientas como datos no confiables y evita combinar Internet abierto con procedimientos potentes en flujos dirigidos a consumidores donde los usuarios esperan controles de confirmación sólidos.

Una configuración predeterminada sólida:

• Habilidades: permitidas
• Shell: permitido
• Red: habilitada solo con una lista mínima de destinos permitidos, por solicitud, para tareas de alcance limitado

7) Usa /mnt/data como punto de entrega de artefactos

En los flujos de trabajo con la terminal alojada en la nube, usa /mnt/data como la ubicación estándar para escribir los resultados que recuperarás, revisarás o pasarás a pasos posteriores. Por ejemplo, informes, conjuntos de datos depurados y hojas de cálculo terminadas.

Una buena forma de entenderlo: las herramientas escriben en el disco, los modelos razonan sobre su contenido y los desarrolladores recuperan los archivos del disco.

8) Entiende las listas de destinos permitidos como un sistema de dos niveles (organización y solicitud)

El acceso a la red se controla en dos lugares:

• Una lista de destinos permitidos de la organización (configurada por un administrador), que define el conjunto máximo de destinos permitidos.
• Una network_policy por solicitud que debe ser un subconjunto de la lista de destinos permitidos de la organización.

Dos implicaciones importantes para la operación:

1. Mantén reducida y estable la lista de destinos permitidos de la organización (el conjunto de “destinos aprobados en los que confías”).
2. Mantén aún más reducidas las listas de destinos permitidos de cada solicitud (el conjunto de “destinos necesarios para esta tarea específica”).

Si una solicitud incluye dominios que no están en la lista de destinos permitidos de la organización, se producirá un error.

9) Usa domain_secrets para las llamadas autenticadas (evita la filtración de credenciales)

Si un dominio permitido necesita encabezados de autenticación, usa domain_secrets para que el modelo nunca vea las credenciales reales.

Durante la ejecución, el modelo ve marcadores de posición (por ejemplo, $API_KEY), y un sidecar inyecta los valores reales solo para los destinos aprobados. Esta es una opción predeterminada sólida siempre que tu agente necesite llamar a una API protegida desde un contenedor.

10) Usa las mismas API en la nube y de forma local

Puedes usar ambas primitivas sin tener que alojarlo todo en la nube:

• Las habilidades funcionan con la terminal alojada en la nube y con el modo de shell local.
• Shell tiene un modo de ejecución local en el que tú ejecutas shell_call y devuelves shell_call_output al modelo.
• Si usas el Agents SDK, también puedes conectar tu propio ejecutor de shell.

Un ciclo de desarrollo práctico sería así:

1. Empieza de forma local (iteración rápida, acceso a herramientas internas y depuración sencilla).
2. Pasa a contenedores alojados en la nube cuando busques repetibilidad, aislamiento y uniformidad en los despliegues.
3. Mantén las mismas habilidades en ambos modos (el flujo de trabajo se mantiene estable aunque cambie el lugar de ejecución).

Tres patrones de desarrollo

Puedes experimentar libremente con estas nuevas primitivas para agentes. Aquí tienes tres ejemplos de cómo combinarlas para crear aplicaciones útiles.

Patrón A: instalar -> obtener datos -> escribir un artefacto

Esta es la forma más sencilla de aprovechar la terminal alojada en la nube: un agente instala dependencias, obtiene datos externos y produce un entregable concreto.

Por ejemplo:

• Instala un par de bibliotecas.
• Extrae datos mediante scraping o llama a una API.
• Escribe un informe en /mnt/data/report.md.

Este patrón es la base de los agentes que realizan trabajo real porque establece un punto claro de revisión: tu aplicación puede mostrar el artefacto al usuario, registrarlo, comparar sus versiones o usarlo como entrada en un paso posterior.

Patrón B: habilidades + shell para flujos de trabajo repetibles

Una vez que hayas creado uno o dos flujos de trabajo con shell que funcionen bien, notarás el siguiente problema: esto funciona, pero la confiabilidad disminuye a medida que los prompts se van modificando.

Ahí es donde entran las habilidades. Esta es una estructura que puedes seguir y mantener a largo plazo:

1. Define el flujo de trabajo (pasos, medidas de protección y plantillas) en una habilidad.
2. Monta la habilidad en tu entorno de shell.
3. Haz que el agente siga la habilidad para producir artefactos de forma determinista.

Esto es especialmente eficaz para flujos de trabajo como:

• Análisis o edición de hojas de cálculo.
• Limpieza de conjuntos de datos y generación de resúmenes.
• Generación de informes estandarizados para procesos empresariales recurrentes.

Patrón C (avanzado): habilidades que encapsulan flujos de trabajo empresariales

Uno de los primeros patrones que observamos es una pérdida de precisión al pasar de invocar una sola herramienta a orquestar varias. Las habilidades pueden cerrar esa brecha al hacer que el razonamiento sobre el uso de herramientas siga procedimientos más definidos, sin aumentar excesivamente el tamaño de los prompts del sistema.

Un ejemplo concreto de Glean:

• Una habilidad orientada a Salesforce aumentó la precisión en las evaluaciones ( 73 % -> 85 % ) y redujo el tiempo hasta el primer token en un 18,1 %.
• Las tácticas prácticas incluyeron un enrutamiento cuidadoso, ejemplos negativos y la incorporación de plantillas y ejemplos dentro de la habilidad.
• Glean también usa habilidades para definir tareas recurrentes dentro de los flujos de trabajo empresariales, como la planificación de cuentas, la clasificación y priorización de casos escalados y la generación de contenido alineado con la marca.

Aquí es donde empieza a verse su potencial. Las habilidades se convierten en procedimientos operativos estándar (SOP) vivos: se actualizan a medida que tu organización evoluciona y los agentes los ejecutan de manera consistente.

Desarrolla una vez, ejecuta en cualquier lugar

Los agentes de larga duración se vuelven mucho más útiles cuando pueden tanto seguir procedimientos como realizar trabajo real en una computadora. Las habilidades, la terminal alojada en la nube y la compactación crean esa base. En resumen:

• Usa habilidades para definir cómo hacer el trabajo (procedimientos, plantillas y medidas de protección).
• Usa shell para llevarlo a cabo (instalar, ejecutar y escribir artefactos).
• Usa la compactación para mantener la coherencia en ejecuciones largas (sin gestionar el contexto manualmente).
• Empieza de forma local cuando estés iterando rápidamente.
• Pasa a contenedores alojados en la nube cuando busques una ejecución repetible y aislada.
• Mantén restringido el acceso a la red con listas de destinos permitidos por organización y por solicitud, y usa secretos de dominio para las llamadas autenticadas.

Empieza en tu propia aplicación. Consulta la documentación de habilidades, la documentación de shell y la documentación de compactación para aprender cómo hacerlo.