Herramientas asíncronas y paralelas
En esta página
Herramientas asíncronas y paralelas
En producción, tus herramientas llaman a APIs externas, consultan bases de datos o realizan operaciones de E/S. Estas operaciones consumen tiempo, y ese tiempo se acumula: un agente que encadena cinco llamadas de un segundo tarda cinco segundos en responder. Convertir las herramientas en asíncronas y aprovechar el paralelismo nativo del SDK es lo que separa una demostración de un servicio utilizable.
Herramientas asíncronas
El decorador @function_tool admite de forma nativa funciones async. No requiere configuración alguna: declara async def, utiliza un cliente HTTP asíncrono y el SDK se encarga del resto.
import httpx
from agents import function_tool
@function_tool
async def search_company(name: str) -> str:
"""Busca información de la empresa mediante la API de Societe.com."""
async with httpx.AsyncClient() as client:
response = await client.get(
"https://api.societe.com/v1/search",
params={"q": name},
timeout=10,
)
if response.status_code == 200:
data = response.json()
return f"Empresa: {data['name']}, SIREN: {data['siren']}, Ingresos: {data['revenue']}"
return f"No hay resultados para '{name}'"
@function_tool
async def verify_solvency(siren: str) -> str:
"""Verifica la solvencia de una empresa por su número SIREN."""
async with httpx.AsyncClient() as client:
response = await client.get(
f"https://api.credit-scoring.com/v1/{siren}",
timeout=10,
)
data = response.json()
return f"Puntuación de solvencia: {data['score']}/100, riesgo: {data['risk_level']}"
Cuando el Runner ejecuta una herramienta asíncrona, no bloquea el bucle de eventos. En un servidor FastAPI, esto significa que otras solicitudes siguen procesándose mientras tu agente espera la respuesta de la API de Societe.com.
Paralelismo automático
Dos herramientas asíncronas independientes pueden ejecutarse simultáneamente. El modelo decide esto, y tus instrucciones pueden fomentarlo explícitamente.
from agents import Agent, Runner
agent = Agent(
name="Analista B2B",
instructions="""Analizas empresas para tomar decisiones de negocio.
Cuando te pidan analizar una empresa, recupera su información
Y verifica su solvencia al mismo tiempo.""",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
)
# El modelo lanzará ambas herramientas en paralelo
result = await Runner.run(
agent,
"Analiza la empresa Acme Corp (SIREN 123456789)"
)
Dado que el SIREN se proporciona en la consulta, la comprobación de solvencia no espera a la búsqueda de la empresa: el SDK ejecuta ambas llamadas simultáneamente. El tiempo total equivale a la duración de la herramienta más lenta, no a la suma de ambas.
Control del paralelismo
El paralelismo no siempre es deseable. Si tus herramientas escriben en el mismo registro o si el orden importa para la consistencia de los datos, fuerza la ejecución secuencial.
from agents import Agent
agent = Agent(
name="Agente precavido",
instructions="Ejecuta las herramientas una por una para garantizar la consistencia de los datos.",
tools=[search_company, verify_solvency],
model="gpt-5.6-terra",
parallel_tool_calls=False, # Fuerza la ejecución secuencial
)
El parámetro parallel_tool_calls=False obliga al modelo a llamar a una sola herramienta cada vez. Intercambias latencia por previsibilidad.
Patrón: agregación de resultados paralelos
El caso práctico más común consiste en recopilar datos de múltiples fuentes para la misma entidad. Aquí, el clima de una ciudad y su agenda cultural no tienen nada que ver entre sí, pero la respuesta necesita ambos.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def get_weather(city: str) -> str:
"""Obtiene el clima actual de una ciudad."""
# Simulación - en producción: llamada a API meteorológica
weather_data = {
"Paris": {"temp": 22, "conditions": "sunny"},
"Lyon": {"temp": 19, "conditions": "cloudy"},
"Marseille": {"temp": 26, "conditions": "sunny"},
}
data = weather_data.get(city, {"temp": 0, "conditions": "unknown"})
return json.dumps({"city": city, **data}, ensure_ascii=False)
@function_tool
async def get_events(city: str) -> str:
"""Obtiene próximos eventos en una ciudad."""
events = {
"Paris": ["Concierto en el Stade de France", "Exposición en el Louvre"],
"Lyon": ["Festival de las Luces", "Feria de la Gastronomía"],
"Marseille": ["Regata del Mediterráneo"],
}
return json.dumps({
"city": city,
"events": events.get(city, [])
}, ensure_ascii=False)
agent = Agent(
name="Agente de viajes",
instructions="""Eres un agente de viajes. Cuando te pidan
recomendaciones para una ciudad, recupera el clima Y los eventos
simultáneamente para ofrecer un consejo completo.""",
tools=[get_weather, get_events],
model="gpt-5.6-terra",
)
# El modelo llamará a ambas herramientas en paralelo para cada ciudad
result = await Runner.run(
agent,
"Quiero visitar París este fin de semana. ¿Qué me recomiendas?"
)
print(result.final_output)
Ambas herramientas devuelven JSON, lo que facilita al modelo recombinar los datos. Observa la redacción de la instrucción: el “Y … simultáneamente” desencadena la llamada paralela en lugar de una cadena perezosa.
Tiempos de espera y resiliencia
Una API que nunca responde bloquea tu agente con la misma certeza que una herramienta síncrona. Limita cada llamada lenta con un tiempo de espera y convierte los fallos en mensajes inteligibles.
import asyncio
from agents import function_tool
@function_tool
async def slow_api_call(query: str) -> str:
"""Llama a una API que podría ser lenta."""
try:
async with asyncio.timeout(5): # Tiempo de espera de 5 segundos
# Tu llamada a la API aquí
await asyncio.sleep(0.1) # Simulación
return f"Resultado para '{query}'"
except asyncio.TimeoutError:
return "La API no respondió a tiempo. Por favor, inténtalo de nuevo."
Rendimiento: impacto del paralelismo
Pongamos la escala en perspectiva. Tres herramientas de 500 ms ejecutadas secuencialmente cuestan 1500 ms; las mismas tres herramientas en paralelo cuestan unos 500 ms, es decir, la duración de la más lenta. Para un agente que utiliza muchas herramientas, la diferencia es inmediatamente notable en la práctica.
Puntos clave
- Utiliza
asyncpara herramientas que realizan llamadas de red o de E/S - El SDK ejecuta automáticamente herramientas independientes en paralelo
parallel_tool_calls=Falsefuerza la ejecución secuencial cuando es necesario- Añade tiempos de espera con
asyncio.timeout()para mejorar la resiliencia - El paralelismo puede dividir la latencia por el número de herramientas