Diseñando subagentes efectivos

Cómo se usan los datos de configuración del subagente

Cuando envías un mensaje al agente de la ventana de contexto principal, el nombre y la descripción de cada subagente disponible se incluyen en la indicación del sistema. Así es como el agente principal decide qué subagente lanzar y cuándo. Si quieres tener mejor control sobre cuándo se activa automáticamente un subagente, el nombre y la descripción son lo que debes ajustar.

La descripción también cumple un segundo papel. Cuando el agente principal lanza un subagente, escribe una indicación de entrada para iniciar la tarea. Usa la descripción como guía para escribir esa indicación. Así que la descripción no solo controla cuándo se ejecuta un subagente, sino que también moldea qué se le indica hacer al subagente.



Escribir descripciones que moldean las indicaciones de entrada

Considera un subagente de revisión de código. Con una descripción genérica, el agente principal podría escribir una indicación de entrada como "usa git diff para encontrar los cambios actuales". Eso es vago. El subagente tiene que averiguar por su cuenta qué archivos importan.

Si actualizas la descripción para incluir algo como "Debes indicarle al agente con precisión qué archivos quieres que revise", el agente principal ahora escribirá una indicación de entrada mucho más específica que enumera los archivos reales a revisar.

Esta misma técnica funciona en diferentes tipos de subagentes. Por ejemplo, agregar "devuelve fuentes que se puedan citar" a la descripción de un subagente de búsqueda web hace que el agente principal incluya esa instrucción al delegar la tarea.



Definir un formato de salida

La mejora más importante que puedes hacer a un subagente es definir un formato de salida en su indicación del sistema. Esto logra dos cosas:

• Crea puntos de parada naturales: el subagente sabe que ha terminado cuando ha completado cada sección del formato.
• Evita que el subagente se ejecute demasiado tiempo. Sin una salida definida, los subagentes tienen dificultades para decidir cuándo se ha hecho suficiente investigación y tienden a ejecutarse mucho más tiempo del necesario.

Aquí tienes un ejemplo de un formato de salida estructurado para un subagente de revisión de código:

Este formato le da al subagente una lista de verificación clara para trabajar. Una vez que se completa cada sección, el subagente sabe que puede detenerse.

Reportar obstáculos

Cuando un subagente descubre una solución alternativa durante su trabajo, como resolver un problema de dependencia o descubrir que cierto comando necesita indicadores particulares, esos detalles deben aparecer en el resumen que devuelve. Si no lo hacen, el hilo principal tiene que redescubrir las mismas soluciones por su cuenta, lo que desperdicia tiempo y tokens.

El tipo de cosas que quieres que salgan a la luz incluyen:

• Problemas de configuración o peculiaridades del entorno
• Soluciones alternativas descubiertas durante la tarea
• Comandos que necesitaron indicadores o configuración especiales
• Dependencias o importaciones que causaron problemas

La forma de obtener esta información es pedirla explícitamente en el formato de salida. Agregar una sección de "Obstáculos encontrados" a tu plantilla de salida hace que esta información salga a la luz de manera confiable.



Limitar el acceso a herramientas

No todos los subagentes necesitan acceso a todas las herramientas. Piensa en lo que un subagente realmente necesita hacer, y dale solo las herramientas requeridas para ese trabajo. Esto logra dos cosas: evita efectos secundarios no deseados y hace que el rol de cada subagente sea más claro cuando tienes varios de ellos.

Así es como debes pensar sobre el acceso a herramientas para los tipos comunes de subagentes:

• Subagente de investigación / solo lectura -- Solo necesita Glob, Grep y Read. No puede modificar archivos accidentalmente.
• Revisor de código -- Necesita acceso a Bash para ejecutar git diff y ver qué cambió, pero aún así no necesita Edit ni Write.
• Agente de estilo / modificación de código -- Aquí es donde das acceso a Edit y Write, porque el trabajo del subagente es realmente cambiar tu código.

Uniendo todo

Los subagentes efectivos comparten cuatro características:

1. Descripciones específicas -- La descripción controla cuándo se lanza el subagente y qué instrucciones recibe. Escríbela para orientar ambas cosas.
2. Salida estructurada -- Define un formato de salida en la indicación del sistema para que el subagente sepa cuándo ha terminado y devuelva información que el hilo principal pueda usar.
3. Reporte de obstáculos -- Incluye una sección en el formato de salida para soluciones alternativas, peculiaridades y problemas, de modo que el hilo principal no tenga que redescubrirlos.
4. Acceso limitado a herramientas -- Dale a un subagente solo las herramientas que realmente necesita. Solo lectura para investigación, bash para revisores, edición/escritura solo para agentes que deban cambiar código.

Cada uno de estos patrones es simple por sí solo, pero juntos convierten a un subagente de algo que intenta ayudar de manera vaga en un trabajador enfocado y predecible que termina a tiempo y reporta con claridad.