Ir al contenido principal
Español— Elegir un idioma
Menú

Herramientas asíncronas y paralelas

Lección 8 de 25 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Herramientas asíncronas y paralelas
  2. Herramientas asíncronas
  3. Paralelismo automático
  4. Control del paralelismo
  5. Patrón: agregación de resultados paralelos
  6. Tiempos de espera y resiliencia
  7. Rendimiento: impacto del paralelismo
  8. Puntos clave

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 async para herramientas que realizan llamadas de red o de E/S
  • El SDK ejecuta automáticamente herramientas independientes en paralelo
  • parallel_tool_calls=False fuerza 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