Saltar al contenido principal

Crear agentes con la API

Avanzado
What you'll learn
  • Definir qué es realmente un agente: un modelo que se ejecuta en un bucle
  • Aplicar el test de decisión para elegir entre llamada única, flujo de trabajo o agente
  • Diseñar un bucle de agente mínimo con las salvaguardas adecuadas
  • Saber cuándo recurrir al Claude Agent SDK en lugar de programarlo a mano
  • Hacer que un agente sea robusto: acotarlo, gestionar fallos, restringir privilegios y evaluarlo

Un agente es un modelo que se ejecuta en un bucle: persigue un objetivo llamando a herramientas, observando los resultados y decidiendo el siguiente paso hasta terminar. Antes de crear uno, elige lo más simple que funcione.

El test de decisión (no sobredimensiones)​

No toda tarea necesita un agente. Recorre primero este árbol: la mayoría de las tareas se detienen en la parte superior.

Tres opciones, de la más simple a la más compleja:

  • Llamada única — un solo prompt lo resuelve. La mayoría de las tareas. Lo más barato y fiable.
  • Flujo de trabajo — orquestas una secuencia fija de llamadas en código (flujo de control determinista). Úsalo cuando los pasos son conocidos.
  • Agente — el modelo decide los pasos dinámicamente. Úsalo solo cuando el camino realmente no se puede codificar de forma fija.
Watch out

Recurre a un agente cuando la adaptabilidad sea la clave, no porque suene impresionante. Un flujo de trabajo que tú controlas es más fácil de probar y depurar.

Diseñar el bucle​

Un agente personalizado mínimo se compone de solo cuatro piezas móviles. Constrúyelas en este orden:

Guided walkthrough1 of 4
  1. Indica el objetivo, las restricciones y las herramientas disponibles. Es lo que el modelo razona en cada turno.

El Claude Agent SDK te ofrece este bucle —herramientas, permisos, gestión del contexto— todo incluido, para que no tengas que construirlo a mano.

Pro tip

Antes de escribir tu propio bucle, pregúntate si el Agent SDK ya lo cubre. Incluye el bucle, los permisos y la gestión del contexto, para que puedas centrarte en las herramientas y el objetivo.

Hazlo robusto​

Un bucle que puede llamar a herramientas también puede comportarse mal. Cuatro hábitos mantienen fiable a un agente:

  • Acota todo: iteraciones, tiempo, coste. Los agentes pueden quedar en bucle.
  • Gestiona los fallos de las herramientas con elegancia (devuelve el error como resultado).
  • Mínimo privilegio + humano en el bucle para acciones arriesgadas: consulta Proteger agentes.
  • Evalúalo con casos reales antes de confiar en él: consulta Evaluaciones.
Key takeaways
  • Un agente es un modelo en un bucle que llama a herramientas hacia un objetivo: úsalo solo cuando el camino no se pueda codificar de forma fija
  • Orden de decisión: llamada única → flujo de trabajo → agente → agentes gestionados; prefiere lo más simple que funcione
  • Un bucle mínimo = prompt de sistema + bucle tool_use/tool_result + salvaguardas + gestión del contexto
  • El Claude Agent SDK incluye el bucle, las herramientas, los permisos y la gestión del contexto por ti
  • Robustez = acotar iteraciones/tiempo/coste, gestionar fallos de herramientas, mínimo privilegio + humano en el bucle, y evaluar antes de confiar

Compruébalo tú mismo​

Compruébalo tú mismo

0/5
  1. ¿Qué describe mejor a un agente en este contexto?
  2. La tarea tiene pasos fijos y conocidos. ¿A qué deberías recurrir?
  3. ¿Cuándo está realmente justificado un agente personalizado?
  4. En el bucle, ¿qué ocurre cuando el modelo responde con un tool_use?
  5. ¿Cuál NO es una de las salvaguardas para hacer robusto a un agente?

Siguiente​