Una de las partes más difíciles de construir un sistema de agentes es diseñar su espacio de acciones.
Claude actúa mediante 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 (puedes leer más sobre el uso programático de herramientas en la API de Claude en el nuevo artículo de @RLanceMartin).
Con todas estas opciones, ¿cómo diseñas las herramientas de tu agente? ¿Necesitas solo una herramienta como ejecución de código o bash? ¿Qué pasaría si tuvieras 50 herramientas, una para cada caso de uso que tu agente pudiera encontrar?
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 potente sería una computadora, pero tendrías que saber cómo usarla para escribir y ejecutar código.
Este es un marco útil para diseñar tu agente. Quieres darle herramientas adaptadas a sus propias capacidades. Pero, ¿cómo sabes 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 llevar 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 - Editar el ExitPlanTool
Lo primero que probamos fue agregar un parámetro al ExitPlanTool para que tuviera un conjunto 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 - Cambiar el Formato de Salida
Luego probamos modificar las instrucciones de salida de Claude para que usara un formato markdown ligeramente modificado que pudiera usar para 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 para el usuario.
Si bien este era el cambio más general que podíamos hacer y Claude parecía ser bastante bueno generando esto, no estaba garantizado. Claude añadía frases 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 estaba especialmente indicada para hacerlo durante el modo de planificación. Cuando se activaba la herramienta, mostrábamos un modal para mostrar las preguntas y bloquear el bucle del agente hasta que el usuario respondiera.
Esta herramienta nos permitió indicar a Claude que generara una salida estructurada y nos ayudó a asegurarnos de que Claude ofreciera al usuario múltiples opciones. También les dio a los usuarios formas de componer esta funcionalidad, por ejemplo, llamándola en el SDK del agente o usándola como referencia en skills.
Lo más importante es que a Claude parecía gustarle llamar a esta herramienta y descubrimos que sus resultados funcionaban bien. Incluso la herramienta mejor diseñada no funciona si Claude no entiende cómo llamarla.
¿Es esta la forma definitiva 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 encaminado. Los Todos podían escribirse al inicio y marcarse como completados a medida que el modelo trabajaba. Para ello, le dimos a Claude la herramienta TodoWrite, que escribía o actualizaba los Todos y los mostraba al usuario.
Pero incluso así, a menudo veíamos que Claude olvidaba 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 podrían los subagentes coordinarse en una lista de tareas compartida?
Al ver esto, reemplazamos TodoWrite con la herramienta Task (lee más sobre Tasks aquí). Mientras que los 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 necesitaban tus modelos ahora podrían estar limitándolos. Es importante revisar constantemente las suposiciones anteriores sobre qué herramientas se necesitan. Esta también es la razón por la que es útil limitarse a 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 se pueden usar para construir su propio contexto.
Cuando Claude Code apareció 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 una variedad de entornos diferentes. Más importante aún, Claude recibía este contexto en lugar de encontrarlo por sí mismo.
Pero si Claude podía buscar en la web, ¿por qué no buscar en tu base de código? Al darle a Claude una herramienta Grep, podíamos permitirle buscar archivos y construir contexto por sí mismo.
Este es un patrón que hemos visto: a medida que Claude se vuelve más inteligente, es cada vez mejor para construir su contexto si se le dan las herramientas adecuadas.
Cuando introdujimos Agent Skills, formalizamos la idea de la divulgación progresiva, 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 actualmente tiene ~20 herramientas, y constantemente nos preguntamos si necesitamos todas ellas. El listón 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 de barra inclinada, 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 añadido contexto innecesario (context rot) e interferido con la tarea principal de Claude Code: escribir código.
En su lugar, probamos una forma de divulgación progresiva. Le dimos a Claude un enlace a su documentación que luego 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 realmente solo necesitabas la respuesta.
Así que construimos el subagente Guía de Claude Code, al que Claude está indicado para llamar cuando le preguntas 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.
