Una de las partes más difíciles de construir un harness para agentes es diseñar su espacio de acciones.
Claude actúa a través de Tool Calling, pero hay varias formas de construir herramientas en la API de Claude con primitivas como bash, skills y, recientemente, ejecución de código (lee más sobre tool calling programático en la API de Claude en el nuevo artículo de @RLanceMartin).
Con todas estas opciones, ¿cómo diseñar las herramientas de tu agente? ¿Necesitas solo una herramienta como ejecución de código o bash? ¿Qué tal si tuvieras 50 herramientas, una para cada caso de uso que tu agente pudiera enfrentar?
Para ponerme en la mente del modelo, me gusta imaginar que me dan un problema matemático difícil. ¿Qué herramientas querrías para resolverlo? ¡Dependería de tus propias habilidades!
El papel sería lo mínimo, pero estarías limitado por los cálculos manuales. Una calculadora sería mejor, pero necesitarías saber cómo usar las opciones más avanzadas. La opción más rápida y poderosa sería una computadora, pero tendrías que saber usarla para escribir y ejecutar código.
Este es un marco útil para diseñar tu agente. Quieres darle herramientas que se ajusten a sus propias capacidades. Pero, ¿cómo saber cuáles son esas capacidades? Prestas atención, lees sus resultados, experimentas. Aprendes a ver como un agente.
Aquí hay algunas lecciones que hemos aprendido al prestar atención a Claude mientras construíamos Claude Code.
Mejorando la Elicitación y la Herramienta AskUserQuestion
Al construir la herramienta AskUserQuestion, nuestro objetivo era mejorar la capacidad de Claude para hacer preguntas (a menudo llamada elicitación).
Si bien Claude podía hacer preguntas en texto plano, descubrimos que responder esas preguntas parecía tomar un tiempo innecesario. ¿Cómo podríamos reducir esta fricción y aumentar el ancho de banda de la comunicación entre el usuario y Claude?
Intento #1 - Editando el ExitPlanTool
Lo primero que intentamos fue agregar un parámetro al ExitPlanTool para tener un arreglo de preguntas junto con el plan. Esto fue lo más fácil de implementar, pero confundió a Claude porque estábamos pidiendo simultáneamente un plan y un conjunto de preguntas sobre el plan. ¿Qué pasaba si las respuestas del usuario entraban en conflicto con lo que decía el plan? ¿Necesitaría Claude llamar al ExitPlanTool dos veces? Necesitábamos otro enfoque.
(puedes leer más sobre por qué creamos un ExitPlanTool en nuestro artículo sobre prompt caching
Intento #2 - Cambiando el Formato de Salida
Luego intentamos modificar las instrucciones de salida de Claude para que usara un formato markdown ligeramente modificado con el que pudiera hacer preguntas. Por ejemplo, podríamos pedirle que generara una lista de preguntas con viñetas y alternativas entre corchetes. Luego podríamos analizar y formatear esa pregunta como interfaz de usuario.
Si bien este era el cambio más general que podíamos hacer y Claude parecía manejarlo bien, no estaba garantizado. Claude agregaba oraciones adicionales, omitía opciones o usaba un formato completamente diferente.
Intento #3 - La Herramienta AskUserQuestion
Finalmente, decidimos crear una herramienta que Claude pudiera llamar en cualquier momento, pero se le indicaba específicamente que lo hiciera durante el modo de planificación. Cuando la herramienta se activaba, mostrábamos un modal para mostrar las preguntas y bloquear el bucle del agente hasta que el usuario respondiera.
Esta herramienta nos permitió indicarle a Claude que generara una salida estructurada y nos ayudó a asegurarnos de que Claude le diera al usuario múltiples opciones. También les dio a los usuarios formas de componer esta funcionalidad, por ejemplo, llamándola en el Agent SDK o usándola en skills.
Lo más importante es que a Claude parecía gustarle llamar esta herramienta y descubrimos que sus resultados funcionaban bien. Incluso la herramienta mejor diseñada no funciona si Claude no entiende cómo usarla.
¿Es esta la forma final de elicitación en Claude Code? No estamos seguros. Como verás en el siguiente ejemplo, lo que funciona para un modelo puede no ser lo mejor para otro.
Actualizando con Capacidades - Tasks y Todos
Cuando lanzamos Claude Code por primera vez, nos dimos cuenta de que el modelo necesitaba una lista de Tareas (Todo list) para mantenerse enfocado. Las tareas podían escribirse al inicio y marcarse como completadas a medida que el modelo trabajaba. Para ello, le dimos a Claude la herramienta TodoWrite, que escribía o actualizaba tareas y las mostraba al usuario.
Pero incluso así, a menudo veíamos a Claude olvidando lo que tenía que hacer. Para adaptarnos, insertamos recordatorios del sistema cada 5 turnos que le recordaban a Claude su objetivo.
Pero a medida que los modelos mejoraron, no solo no necesitaban que se les recordara la lista de tareas, sino que podían encontrarla limitante. Recibir recordatorios de la lista de tareas hacía que Claude pensara que debía ceñirse a la lista en lugar de modificarla. También vimos que Opus 4.5 mejoró mucho en el uso de subagentes, pero ¿cómo podían coordinarse los subagentes en una lista de tareas compartida?
Al ver esto, reemplazamos TodoWrite con la herramienta Task (lee más sobre Tasks aquí). Mientras que las tareas (Todos) se trataban de mantener el modelo encaminado, las Tasks se centraban más en ayudar a los agentes a comunicarse entre sí. Las Tasks podían incluir dependencias, compartir actualizaciones entre subagentes y el modelo podía modificarlas y eliminarlas.
A medida que aumentan las capacidades del modelo, las herramientas que antes necesitabas podrían ahora estar limitándolo. Es importante revisar constantemente las suposiciones anteriores sobre qué herramientas se necesitan. También es por esto que es útil mantener un conjunto pequeño de modelos compatibles que tengan un perfil de capacidades bastante similar.
Diseñando una Interfaz de Búsqueda
Un conjunto de herramientas particularmente importante para Claude son las herramientas de búsqueda que puede usar para construir su propio contexto.
Cuando Claude Code salió por primera vez, usábamos una base de datos vectorial RAG para encontrar contexto para Claude. Si bien RAG era potente y rápido, requería indexación y configuración, y podía ser frágil en diferentes entornos. Más importante aún, a Claude se le daba este contexto en lugar de que él mismo lo encontrara.
Pero si Claude podía buscar en la web, ¿por qué no buscar en tu código fuente? Al darle a Claude una herramienta Grep, podíamos permitirle buscar archivos y construir su propio contexto.
Este es un patrón que hemos visto: a medida que Claude se vuelve más inteligente, mejora cada vez más en la construcción de su contexto si se le dan las herramientas adecuadas.
Cuando introdujimos Agent Skills, formalizamos la idea de divulgación progresiva (progressive disclosure), que permite a los agentes descubrir incrementalmente contexto relevante a través de la exploración.
Claude podía leer archivos de skills y esos archivos podían hacer referencia a otros archivos que el modelo podía leer de forma recursiva. De hecho, un uso común de las skills es agregar más capacidades de búsqueda a Claude, como darle instrucciones sobre cómo usar una API o consultar una base de datos.
En el transcurso de un año, Claude pasó de no poder construir su propio contexto a poder realizar búsquedas anidadas en varias capas de archivos para encontrar el contexto exacto que necesitaba.
La divulgación progresiva es ahora una técnica común que usamos para agregar nueva funcionalidad sin agregar una herramienta.
Divulgación Progresiva - El Agente Guía de Claude Code
Claude Code tiene actualmente ~20 herramientas, y constantemente nos preguntamos si necesitamos todas ellas. El estándar para agregar una nueva herramienta es alto, porque esto le da al modelo una opción más para considerar.
Por ejemplo, notamos que Claude no sabía lo suficiente sobre cómo usar Claude Code. Si le preguntabas cómo agregar un MCP o qué hacía un comando slash, no podía responder.
Podríamos haber puesto toda esta información en el prompt del sistema, pero dado que los usuarios rara vez preguntaban sobre esto, habría agregado contexto obsoleto (context rot) e interferido con la tarea principal de Claude Code: escribir código.
En cambio, probamos una forma de divulgación progresiva. Le dimos a Claude un enlace a su documentación que podía cargar para buscar más información. Esto funcionó, pero descubrimos que Claude cargaba muchos resultados en el contexto para encontrar la respuesta correcta, cuando en realidad solo necesitabas la respuesta.
Así que construimos el subagente Claude Code Guide, al que se le indica a Claude que llame cuando le preguntes sobre sí mismo. El subagente tiene instrucciones detalladas sobre cómo buscar bien en la documentación y qué devolver.
Si bien esto no es perfecto (Claude aún puede confundirse cuando le preguntas cómo configurarse), ¡es mucho mejor de lo que solía ser! Pudimos agregar cosas al espacio de acciones de Claude sin agregar una herramienta.
Un Arte, no una Ciencia
Si esperabas un conjunto de reglas rígidas sobre cómo construir tus herramientas, lamentablemente esta no es esa guía. Diseñar las herramientas para tus modelos es tanto un arte como una ciencia. Depende en gran medida del modelo que estés usando, el objetivo del agente y el entorno en el que opera.
Experimenta con frecuencia, lee tus resultados, prueba cosas nuevas. Ve como un agente.
