Shell, habilidades y compactación: consejos para agentes que realizan tareas concretas de larga duración

Estamos pasando de asistentes que responden en un solo turno a agentes que trabajan durante períodos prolongados y realizan tareas intelectuales concretas, como leer grandes conjuntos de datos, actualizar archivos y desarrollar aplicaciones.

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

• Habilidades (compatibles 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 guardar resultados, como informes y otros artefactos.
• Compactación del lado del servidor: una forma sencilla de compactar automáticamente el contexto en ejecuciones prolongadas de agentes para que nunca alcances el límite de contexto.

La documentación y la referencia de la API describen cada elemento por separado. En este artículo compartimos consejos y patrones menos evidentes que, hasta ahora, han dado los mejores resultados tanto en nuestro trabajo en OpenAI como en el entorno de producción de Glean, uno de los primeros clientes en usar habilidades.

Cómo funciona cada pieza

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

Una habilidad reúne varios archivos y un archivo de manifiesto llamado 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 realizar una tarea.

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

Herramienta de shell: “ejecución” para agentes

La herramienta de shell permite que los modelos trabajen en un entorno de terminal real. Puedes elegir entre dos opciones:

• Contenedores alojados y administrados por OpenAI.
• Un entorno de ejecución de shell local que ejecutas en tu propia máquina (la herramienta funciona de la misma manera, pero tú controlas la máquina).

La terminal alojada en la nube funciona a través de la API de Responses. Así puedes conservar el estado del trabajo entre solicitudes, llamar a herramientas, continuar el trabajo a lo largo de varios turnos y recuperar artefactos.

Compactación: cómo dar continuidad a las ejecuciones prolongadas

A medida que se alargan los flujos de trabajo, alcanzan los límites de la ventana de contexto. La compactación del lado del servidor permite que las ejecuciones prolongadas continúen, ya que administra la ventana de contexto y comprime automáticamente el historial de la conversación.

La API de Responses ofrece dos formas de usar la compactación:

• Compactación del lado del servidor (nueva): cuando el contexto supera el umbral, la compactación se ejecuta automáticamente dentro del mismo flujo, sin necesidad de una llamada aparte.
• Punto de acceso independiente para la compactación: usa /responses/compact cuando quieras controlar explícitamente en qué momento se realiza la compactación.

Por qué funcionan mejor en conjunto

• Las habilidades simplifican los prompts al agrupar los procedimientos y ejemplos estables en un paquete reutilizable.
• El shell ofrece un entorno de ejecución completo que te permite instalar código, ejecutar scripts y guardar resultados.
• La compactación mantiene la continuidad en ejecuciones prolongadas, de modo que el mismo flujo de trabajo puede seguir ejecutándose sin que tengas que ajustar el contexto a mano.
• En conjunto, te permiten crear flujos de trabajo repetibles que ejecutan tareas reales sin convertir el prompt del sistema en un documento enorme y difícil de mantener.

Consejos prácticos

1) Escribe descripciones que indiquen cuándo elegir cada habilidad (evita el lenguaje publicitario)

La descripción de tu habilidad define, en la práctica, cuándo el modelo decide usarla. Debe responder estas preguntas:

• ¿Cuándo debo usarla?
• ¿Cuándo debo evitarla?
• ¿Qué resultados debo producir y con qué criterios se evalúa el éxito?

Una opción práctica es incluir directamente en la descripción una breve sección titulada “Cuándo usarla y cuándo evitarla”, con detalles concretos sobre las entradas, las herramientas que intervienen y los artefactos esperados.

2) Agrega ejemplos negativos y casos límite para reducir los errores de activación

Puede ocurrir algo inesperado: al principio, poner habilidades a disposición del modelo puede hacer que las active con menos frecuencia cuando corresponde. Una solución que nos ha dado resultado es incluir tanto ejemplos negativos como casos límite.

En la práctica, esto significa describir algunos casos explícitos de “No invoques esta habilidad cuando…” e indicar qué hacer en su lugar. Esto ayuda al modelo a elegir con mayor precisión, sobre todo cuando varias habilidades se parecen a primera vista.

Glean lo observó directamente en evaluaciones específicas: al principio, cuando el modelo decidía qué habilidad usar, la tasa de activación cayó alrededor de un 20 %. La tasa se recuperó cuando el equipo agregó ejemplos negativos y casos límite a las descripciones.

3) Incluye plantillas y ejemplos en la habilidad (si no se usan, su costo es prácticamente nulo)

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

Incluir plantillas y ejemplos resueltos en las habilidades tiene dos ventajas:

• Están disponibles justo cuando se necesitan, es decir, cuando se invoca la habilidad.
• No aumentan el consumo de tokens en consultas que no tienen relación con la habilidad.

Esto funciona especialmente bien cuando el trabajo intelectual produce resultados como los siguientes:

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

Según Glean, este patrón les permitió lograr algunas de sus mayores mejoras de calidad y latencia en producción, porque los ejemplos solo se cargan cuando se activa la habilidad.

4) Planifica desde el principio la reutilización de contenedores y la compactación para las ejecuciones prolongadas

Los agentes que realizan tareas de larga duración rara vez logran completarlas con un único prompt. Planifica la continuidad desde el principio:

• Reutiliza el mismo contenedor en varios pasos cuando quieras mantener las dependencias estables y conservar los archivos en caché y los resultados intermedios.
• Pasa previous_response_id para que el modelo pueda seguir trabajando en el mismo hilo.
• Usa la compactación de forma predeterminada en las ejecuciones prolongadas, sin esperar a que surja una emergencia.

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

5) Cuando necesites un comportamiento determinista, 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 si ejecutas un flujo de trabajo en producción con un contrato claro y necesitas que el modelo siempre elija la misma habilidad, basta con decir:

“Usa la habilidad <skill name>”.

Es la forma más sencilla de mejorar la confiabilidad. Convierte una decisión ambigua sobre qué habilidad usar en un contrato explícito.

6) Considera de alto riesgo la combinación de habilidades y acceso a la red (diseña medidas de contención)

Es fácil pasar por alto este consejo de seguridad al principio, pero corregir el problema después es difícil.

Combinar habilidades con acceso abierto a la red crea una vía de alto riesgo para la exfiltración de datos. Si habilitas el acceso a la red, aplica listas estrictas de destinos permitidos y trata los resultados de las herramientas como datos no confiables. Evita combinar el acceso abierto a internet con procedimientos de gran alcance en flujos dirigidos a consumidores que esperan controles de confirmación rigurosos.

Una configuración predeterminada segura sería la siguiente:

• Habilidades: permitidas
• Shell: permitido
• Red: habilitada solo con una lista mínima de destinos permitidos, definida 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 ubicación estándar para guardar los resultados que luego vas a recuperar, revisar o pasar a otros pasos. Por ejemplo, puedes guardar informes, conjuntos de datos depurados y hojas de cálculo terminadas.

Una forma sencilla de verlo: las herramientas escriben en el disco, los modelos razonan sobre lo que hay en él y los desarrolladores recuperan los resultados del disco.

8) Entiende cómo funcionan los dos niveles de las listas de destinos permitidos (organización y solicitud)

El acceso a la red se controla en dos lugares:

• Una lista de destinos permitidos para la organización, configurada por un administrador, define el conjunto máximo de destinos autorizados.
• La política network_policy de cada solicitud solo puede incluir destinos que figuren en la lista de la organización.

En la práctica, esto tiene dos implicaciones importantes:

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

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

9) Usa domain_secrets para las llamadas autenticadas (evita exponer las credenciales)

Si un dominio permitido requiere 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 contenedor auxiliar inserta los valores reales solo para los destinos aprobados. Es una buena configuración predeterminada siempre que tu agente necesite llamar a una API protegida desde un contenedor.

10) Usa las mismas API en la nube y en tu entorno local

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

• Las habilidades funcionan tanto con la terminal alojada en la nube como con el shell en modo local.
• El 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 SDK de Agents, también puedes integrar tu propio ejecutor de shell.

Un ciclo de desarrollo práctico sigue estos pasos:

1. Empieza en tu entorno local para iterar rápidamente, acceder a herramientas internas y depurar con facilidad.
2. Pasa a contenedores alojados cuando necesites repetibilidad, aislamiento y uniformidad en los despliegues.
3. Usa las mismas habilidades en ambos modos para que el flujo de trabajo se mantenga estable aunque cambie el entorno de ejecución.

Tres patrones de desarrollo

Puedes experimentar con estas nuevas primitivas para agentes. Estos tres ejemplos muestran cómo combinarlas para crear aplicaciones útiles.

Patrón A: instalar -> obtener datos -> guardar 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 genera un entregable concreto.

Por ejemplo:

• Instala un par de bibliotecas.
• Extrae datos de una página web o llama a una API.
• Guarda un informe en /mnt/data/report.md.

Este patrón sirve de base para los agentes que realizan tareas concretas porque define un punto claro de revisión: tu aplicación puede mostrarle el artefacto al usuario, registrarlo, compararlo con otra versión o usarlo como entrada en un paso posterior.

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

Una vez que hayas creado uno o dos flujos de trabajo con shell que den buenos resultados, notarás el siguiente problema: el flujo funciona, pero pierde confiabilidad a medida que los prompts se apartan de su formulación original.

Las habilidades te permiten conservar el procedimiento. Puedes seguir estos pasos:

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

Este enfoque es especialmente eficaz en flujos de trabajo como los siguientes:

• Análisis o edición de hojas de cálculo.
• Depuración 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 incorporan flujos de trabajo empresariales

En los primeros casos de uso, observamos que la precisión disminuía al pasar de invocar una sola herramienta a coordinar varias. Las habilidades pueden cerrar esa brecha al darle al modelo un procedimiento que guíe su razonamiento sobre el uso de las herramientas, sin alargar los prompts del sistema.

Un ejemplo concreto de Glean:

• Con una habilidad para Salesforce, la precisión en las evaluaciones pasó del 73 % al 85 % y el tiempo hasta el primer token se redujo un 18,1 %.
• El equipo definió con cuidado cuándo invocar la habilidad, incluyó ejemplos negativos e incorporó plantillas y ejemplos en la propia habilidad.
• Glean también usa habilidades para definir tareas recurrentes dentro de sus 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 acorde con la marca.

Ahí se ve el potencial de este enfoque. Las habilidades se convierten en procedimientos operativos estándar que se mantienen al día a medida que evoluciona tu organización y que los agentes ejecutan de manera uniforme.

Desarrolla una vez y ejecuta en cualquier entorno

Los agentes que trabajan durante períodos prolongados resultan mucho más útiles cuando pueden seguir procedimientos y realizar tareas concretas en una computadora. Las habilidades, la terminal alojada en la nube y la compactación les dan esa base. En resumen:

• Usa habilidades para definir cómo realizar el trabajo (procedimientos, plantillas y medidas de protección).
• Usa el shell para llevar a cabo las acciones (instalar dependencias, ejecutar scripts y guardar artefactos).
• Usa la compactación para mantener la coherencia en ejecuciones prolongadas sin tener que administrar el contexto a mano.
• Empieza en tu entorno local cuando necesites iterar rápidamente.
• Pasa a contenedores alojados cuando necesites una ejecución repetible y aislada.
• Restringe 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 a usar estas herramientas en tu propia aplicación. Para saber cómo, consulta la documentación de habilidades, la documentación de shell y la documentación de compactación.