Un agente de IA es tan fiable como las API a las que llama. El modelo elige una herramienta, rellena los argumentos y envía una solicitud; si esa solicitud falla, devuelve la forma incorrecta o se cuelga, su agente toma una decisión segura basada en datos erróneos. La mayoría de las demostraciones de agentes omiten esta parte. Los agentes de producción viven o mueren por ello.
Esta guía muestra cómo construir un agente que llama a herramientas reales y, lo que es más importante, cómo usar Apidog como capa de API y como arnés de pruebas. Diseñará los endpoints de las herramientas, los simulará para poder desarrollar offline, y escribirá aserciones que detecten una llamada a una herramienta rota antes de que llegue a un usuario. El objetivo es un agente en el que pueda confiar porque lo ha probado, no porque el camino feliz funcionó una vez.
botónbotón
Qué hace realmente un agente en la capa de API
Despojándonos de la terminología, un ciclo de agente es simple:
- El modelo recibe un objetivo de usuario y una lista de herramientas.
- Devuelve una llamada a una herramienta: un nombre de herramienta más argumentos JSON.
- Su código ejecuta esa llamada; normalmente una solicitud HTTP a alguna API.
- El resultado vuelve al modelo.
- El modelo o llama a otra herramienta o responde.
Cada fallo interesante ocurre en el paso 3 y el paso 4. El modelo alucina un argumento, la API devuelve un 422, el esquema de respuesta se desvió, la llamada expira, o un límite de velocidad entra en acción a mitad del ciclo. Si ha leído sobre los agentes de IA como los nuevos consumidores de API, esta es la versión concreta de esa idea: su agente es un cliente que accede a sus API, y merece el mismo rigor de pruebas que cualquier otro cliente.
Así que el trabajo se divide en dos: definir las herramientas como operaciones de API reales y probables, luego verificar que el agente las llama correctamente tanto en condiciones buenas como malas.
Paso 1: Diseñar las herramientas como operaciones de API reales
Antes de escribir una sola línea de código de agente, defina cada herramienta como un endpoint de API en Apidog. Trate el esquema de la herramienta y el esquema de la API como lo mismo, porque lo son. Una herramienta `get_weather` y el endpoint `GET /weather` comparten un contrato: los mismos parámetros, la misma forma de respuesta.
En Apidog, cree un endpoint para cada herramienta con su esquema OpenAPI; parámetros de ruta, consulta y cuerpo, y una respuesta tipificada. Esto le da tres cosas de forma gratuita:
- Una única fuente de verdad para el contrato de la herramienta que tanto su prompt de agente como sus pruebas leen.
- Documentación autogenerada que puede entregar al modelo como la definición de la herramienta.
- Un esquema para validar posteriormente, de modo que detecte la desviación en el momento en que una respuesta deja de coincidir.
Este hábito de empezar por el esquema es el mismo que subyace a un buen trabajo de diseño de API en general. La ventaja para los agentes es específica: cuando la definición de su herramienta y su endpoint real provienen de un mismo esquema, el modelo no puede llamar a una herramienta que su API no soporta.
Paso 2: Simular las herramientas para poder construir offline
No querrá que cada ejecución de desarrollo acceda a API en vivo que cuestan dinero, imponen límites de velocidad o simplemente aún no están construidas. Apidog genera un servidor mock directamente desde el esquema que acaba de definir. Cada endpoint de herramienta devuelve datos de muestra realistas y válidos según el esquema sin ningún backend.
Esto cambia la forma en que construye agentes. Puede:
- Desarrollar el ciclo completo del agente antes de que existan las API reales, utilizando mocks que coincidan con el contrato acordado.
- Ejecutar pruebas de integración en CI que nunca tocan un endpoint de pago.
- Forzar respuestas específicas; un resultado vacío, un 500, un campo malformado; para ver cómo reacciona su agente.
Apunte el ejecutor de herramientas de su agente a la URL base del mock durante el desarrollo. El modelo llama a `get_weather`, su código accede al mock de Apidog, y una respuesta válida vuelve instantáneamente. Cuando esté listo para la versión real, cambie la URL base a través de una variable de entorno. La simulación es lo que hace que el desarrollo de agentes sea rápido y determinista; el mismo enfoque impulsa cualquier flujo de trabajo serio de pruebas de agentes de IA.
Paso 3: Conectar el agente para que llame a las herramientas
Con los endpoints y los mocks en su lugar, el código del agente se mantiene delgado. Aquí está la forma de un bucle de llamada a herramientas usando la API de Mensajes de Claude; las definiciones de las herramientas reflejan los esquemas que construyó en Apidog.
import anthropic, requests, os
client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"] # Apidog mock during dev, real API in prod
tools = [{
"name": "get_weather",
"description": "Get current weather for a city",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
def run_tool(name, args):
if name == "get_weather":
r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
r.raise_for_status()
return r.json()
messages = [{"role": "user", "content": "What should I wear in Tokyo today?"}]
while True:
resp = client.messages.create(
model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages
)
if resp.stop_reason == "tool_use":
block = next(b for b in resp.content if b.type == "tool_use")
result = run_tool(block.name, block.input)
messages.append({"role": "assistant", "content": resp.content})
messages.append({"role": "user", "content": [{
"type": "tool_result", "tool_use_id": block.id,
"content": str(result),
}]})
else:
print(resp.content[0].text)
break
Las líneas `timeout=10` y `raise_for_status()` importan más que la llamada al modelo. Son la diferencia entre un agente que falla ruidosamente y uno que silenciosamente alimenta una solicitud colgada o con error de vuelta al bucle. Para una visión más amplia de cómo los agentes encajan en los flujos de trabajo de API, los patrones en 5 agentes de IA para su flujo de trabajo de API son un compañero útil.
Paso 4: Probar las llamadas a las herramientas, no solo las "vibes"
Aquí está la parte que la mayoría de los equipos se saltan. Ejecute cada endpoint de herramienta como una solicitud guardada en Apidog con aserciones, independientemente del modelo. La fiabilidad del agente está limitada por la fiabilidad de sus herramientas, así que pruebe las herramientas primero.
Para cada endpoint de herramienta, afirme:
- El estado es `200` para una entrada válida.
- El cuerpo de la respuesta coincide con el esquema; Apidog valida la respuesta contra su definición OpenAPI automáticamente.
- Los campos requeridos que leerá el modelo están presentes y tienen el tipo correcto.
- El tiempo de respuesta está dentro del tiempo de espera que su agente impone.
Luego pruebe los caminos infelices, porque ahí es donde los agentes se comportan mal:
- Envíe los argumentos malformados que un modelo podría alucinar; una `city` vacía, un número donde debería haber una cadena; y asegúrese de obtener un `400`/`422` limpio, no un `500`.
- Fuerce una respuesta de error del mock y confirme que el `run_tool` de su agente lanza una excepción en lugar de devolver basura.
- Pruebe un resultado vacío y verifique que el agente maneje "sin datos" en lugar de inventar una respuesta.
Esto es pruebas de contrato aplicadas a herramientas de agente; la misma disciplina cubierta en pruebas de contrato de API, dirigida a los endpoints que su modelo llama. Cuando la forma de respuesta de una herramienta se desvía, la aserción falla en CI y usted lo corrige antes de que el agente comience a razonar sobre una carga útil rota.
Paso 5: Gestionar reintentos, tiempos de espera y límites de velocidad
Los agentes amplifican las API inestables. Un solo reintento en una aplicación normal es un reintento; en un ciclo de agente, un modelo que sigue volviendo a llamar a una herramienta que falla puede agotar rápidamente su límite de velocidad y su presupuesto. Construya los controles y pruébelos:
- Tiempos de espera. Establezca un tiempo de espera explícito en cada solicitud de herramienta, como en el ejemplo anterior. Luego, use Apidog para simular un endpoint lento y confirme que su cliente se rinde limpiamente en lugar de colgar todo el ciclo.
- Reintentos con retroceso exponencial. Reintente los fallos transitorios, pero limite el número y aplique un retroceso. Pruébelo con un mock que falla dos veces y luego tiene éxito, y asegúrese de que su agente se recupera en lugar de entrar en un bucle infinito.
- Límites de velocidad. Espere `429`s bajo carga. Simule una respuesta con límite de velocidad y verifique que su agente espera y reintenta en lugar de insistir. Si ya ha lidiado con esto en API de modelos puros; vea límites de velocidad de la API de GPT para la misma clase de problema; la versión del agente es más estricta porque el ciclo multiplica cada llamada.
- Corte de circuito. Después de N fallos en una herramienta, deje de llamarla y permita que el agente informe del fallo en lugar de seguir girando. Pruebe que el disyuntor se activa.
Ejecute estos escenarios repetibles en Apidog para que una regresión en su manejo de errores se muestre como una prueba fallida, no como un incidente de producción.
Paso 6: Ejecutar de extremo a extremo contra mocks en CI
Conéctelo todo. En CI, inicie su agente apuntando al servidor mock de Apidog, suminístrele un conjunto fijo de objetivos de usuario y haga aserciones sobre el resultado final y la secuencia de llamadas a herramientas. Dado que los mocks son deterministas, la misma entrada produce las mismas llamadas a herramientas en cada ejecución, por lo que las pruebas de su agente dejan de ser inestables. Cuando esté seguro, cambie la URL base a las API reales para una prueba de humo en vivo más pequeña. Esta división; mocks deterministas para la mayor parte de las pruebas, una fina verificación en vivo para la realidad; es lo que hace que las pruebas de IA agéntica sean prácticas en lugar de aspiracionales.
Una lista de verificación para un agente confiable
- [ ] Cada herramienta se define como una operación de API real con un esquema OpenAPI.
- [ ] Existen mocks para cada herramienta para que pueda construir y probar offline.
- [ ] Cada endpoint de herramienta tiene aserciones sobre el estado, el esquema y el tiempo.
- [ ] Los caminos infelices; argumentos incorrectos, errores, resultados vacíos; se prueban explícitamente.
- [ ] Los tiempos de espera, los reintentos con retroceso exponencial y el manejo de límites de velocidad están en el código y se prueban.
- [ ] Una ejecución de CI de extremo a extremo ejerce el ciclo completo contra mocks deterministas.
Cumpla los seis puntos y tendrá un agente cuya fiabilidad podrá describir con pruebas, no con esperanza.
Preguntas frecuentes
¿Por qué usar un cliente de API para probar un agente en lugar de simplemente ejecutar el agente? Ejecutar el agente prueba el modelo y las herramientas juntas, por lo que un fallo es ambiguo. Probar cada endpoint de herramienta en Apidog aísla la capa de la API, por lo que sabe si un problema es el razonamiento del modelo o una herramienta rota.
¿Tengo que construir las API reales antes de construir el agente? No. Defina los contratos de las herramientas como esquemas en Apidog, genere mocks y construya todo el ciclo del agente contra esos mocks. Cambie a los endpoints reales más tarde a través de una variable de entorno.
¿Cómo evito que mi agente entre en un bucle infinito con una herramienta que falla? Limite los reintentos, añada retroceso exponencial y active un disyuntor después de fallos repetidos para que el agente informe del problema en lugar de seguir girando. Pruebe cada control contra un mock que devuelva errores.
¿Puedo probar el agente sin gastar dinero en llamadas al modelo y a la API? En su mayor parte, sí. Simule las API de herramientas en Apidog para pruebas de integración deterministas y gratuitas, y mantenga las llamadas al modelo en vivo en un pequeño conjunto de pruebas de humo.
¿Funciona esto con frameworks como LangChain o el SDK de Agente de Claude? Sí. La capa de herramientas es simplemente HTTP. Cualquier framework que impulse el bucle, apunte sus llamadas a herramientas a los mocks de Apidog para las pruebas y a los endpoints reales para la producción. Vea la guía del SDK de Código de Claude para uno de esos bucles.
Conclusión
Un agente fiable no es un prompt más inteligente; es una capa de herramientas probada. Defina sus herramientas como operaciones de API reales, simúlelas para que el desarrollo sea rápido y determinista, afirme cada forma de respuesta y pruebe los fallos a propósito. Apidog le ofrece un único lugar para diseñar esos endpoints, simularlos y ejecutarlos como un arnés de pruebas, de modo que el comportamiento de su agente sea algo que pueda probar. Descargue Apidog y construya el agente en el que realmente puede confiar en producción.
botón