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

Escalado y arquitecturas multiagente

Lección 25 de 25 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Escalado y arquitecturas multiagente
  2. Arquitectura de producción
  3. Patrones multiagente
  4. Gestión de límites de tasa
  5. Optimización de costes a gran escala
  6. Puntos clave
  7. Pon a prueba tus conocimientos

Escalado y arquitecturas multiagente

Tu agente funciona para 10 usuarios. ¿Cómo haces que funcione para 10.000? Los desafíos cambian: ya no se trata de instrucciones que fallan, sino de límites de tasa del proveedor, memoria del servidor y tu factura mensual. En esta última lección, aprenderás a escalar tus agentes, diseñar arquitecturas multiagente de alto rendimiento y gestionar las restricciones de producción a gran escala.

Arquitectura de producción

El backend del agente con FastAPI

La primera decisión estructural afecta al ciclo de vida del agente. Crear un Agent para cada solicitud desperdicia tiempo y dispersa la configuración; el parámetro lifespan de FastAPI te permite instanciarlos una sola vez al inicio y mantenerlos en un registro indexado por tipo. La ruta lee el tipo solicitado, lo rechaza limpiamente si no existe y luego transmite la respuesta: run_streamed emite deltas a medida que avanza la generación, haciendo que el texto aparezca en pantalla de inmediato en lugar de dejar al usuario mirando un indicador de carga durante ocho segundos.

from fastapi import FastAPI, Request, Depends, HTTPException
from fastapi.responses import StreamingResponse
from agents import Agent, Runner, function_tool
from contextlib import asynccontextmanager
import asyncio

# Grupo de agentes preconfigurados
agents_registry = {}

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Inicializar agentes al arrancar
    agents_registry["sales"] = Agent(
        name="Sales Agent",
        instructions="You assist customers with their purchases.",
        model="gpt-5.6-terra",
        tools=[search_product, calculate_price],
    )
    agents_registry["support"] = Agent(
        name="Support Agent",
        instructions="You provide technical support.",
        model="gpt-5.6-terra",
        tools=[check_ticket, create_ticket],
    )
    yield
    agents_registry.clear()

app = FastAPI(lifespan=lifespan)

@app.post("/api/chat/{agent_type}")
async def chat(agent_type: str, request: Request):
    agent = agents_registry.get(agent_type)
    if not agent:
        raise HTTPException(404, f"Agent '{agent_type}' not found")

    body = await request.json()

    async def stream():
        result = Runner.run_streamed(agent, body["messages"])
        async for event in result.stream_events():
            if event.type == "raw_response_event":
                if hasattr(event.data, "delta") and event.data.delta:
                    yield f"data: {event.data.delta}\n\n"
        yield "data: [DONE]\n\n"

    return StreamingResponse(stream(), media_type="text/event-stream")

Gestión de la concurrencia

Compartir objetos Agent entre todas las solicitudes de esta forma es seguro porque cada solicitud crea un Runner independiente: el agente contiene la configuración y el Runner mantiene el estado de ejecución. El SDK gestiona la concurrencia de forma nativa, y procesar un lote de mensajes implica apilar corrutinas en asyncio.gather. El detalle clave aquí es return_exceptions=True: sin él, una única solicitud fallida cancela todo el lote. Con él, obtienes los errores como valores, los asocias a su mensaje original y procesas los noventa y nueve resultados válidos.

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="Concurrent Agent",
    instructions="You answer questions.",
    model="gpt-5.6-terra",
)

async def process_parallel_requests(messages: list[str]):
    """Procesar múltiples solicitudes en paralelo."""
    tasks = [Runner.run(agent, msg) for msg in messages]
    results = await asyncio.gather(*tasks, return_exceptions=True)

    for msg, res in zip(messages, results):
        if isinstance(res, Exception):
            print(f"Error para '{msg}': {res}")
        else:
            print(f"'{msg}' -> {res.final_output[:50]}...")

    return results

Patrones multiagente

Patrón supervisor

Más allá de cierta escala, un único agente con quince herramientas se vuelve impredecible: sus instrucciones se inflan y sus decisiones se degradan. El patrón supervisor divide el trabajo entre agentes especializados (investigación, análisis, redacción) y delega el enrutamiento a un agente dedicado mediante un traspaso (handoff). Cada especialista mantiene instrucciones breves y un modelo adecuado a su tarea: el análisis hereda un modelo de razonamiento, mientras que el supervisor, que solo elige un destinatario, se ejecuta en un modelo rápido ya que su decisión depende de pocas palabras.

from agents import Agent, Runner, Handoff

search_agent = Agent(
    name="Search",
    instructions="You search for information on the web and in databases.",
    tools=[WebSearchTool(), search_crm],
    model="gpt-5.6-terra",
)

analysis_agent = Agent(
    name="Analysis",
    instructions="You analyze data and produce insights.",
    model="gpt-5.6-sol",
)

writing_agent = Agent(
    name="Writing",
    instructions="You write professional reports in English.",
    model="gpt-5.6-terra",
)

supervisor_agent = Agent(
    name="Supervisor",
    instructions="""You coordinate a team of specialized agents.
    For each request:
    1. Analyze what is needed
    2. Delegate to specialized agents via handoff
    3. The last agent produces the final response

    Available agents:
    - Search: to collect data
    - Analysis: to analyze and interpret
    - Writing: to produce the final deliverable""",
    handoffs=[
        Handoff(agent=search_agent, description="Collect data"),
        Handoff(agent=analysis_agent, description="Analyze data"),
        Handoff(agent=writing_agent, description="Write a report"),
    ],
    model="gpt-5.6-terra",  # Rápido para el enrutamiento
)

Patrón de canalización (Pipeline)

Cuando la secuencia se conoce de antemano, dejar que un modelo decida la cadena es un gasto innecesario. El patrón de canalización cablea los pasos en tu código: recopilar, analizar, redactar. Un análisis competitivo comienza así con dos recogidas lanzadas simultáneamente —la web y el CRM no tienen razón para esperarse mutuamente— y luego pasa todo al análisis, cuya salida alimenta la redacción. Obtienes un flujo de trabajo reproducible, trazable paso a paso, cuya duración total es la de la recogida más lenta más los dos pasos siguientes.

async def competitive_analysis_pipeline(company: str):
    # Paso 1: Recogida de datos en paralelo
    web_task = Runner.run(search_agent, f"Search for information about {company}")
    crm_task = Runner.run(crm_agent, f"CRM data for {company}")
    results = await asyncio.gather(web_task, crm_task)

    data = f"""Web data: {results[0].final_output}
    CRM data: {results[1].final_output}"""

    # Paso 2: Análisis
    analysis = await Runner.run(analysis_agent, f"Analyze this data: {data}")

    # Paso 3: Informe
    report = await Runner.run(
        writing_agent,
        f"Write a competitive analysis report: {analysis.final_output}"
    )

    return report.final_output

Patrón Map-Reduce

El tercer patrón aborda un problema de volumen más que de complejidad. Dos mil verbatims de clientes no caben en una única solicitud y no pueden analizarse secuencialmente en un tiempo razonable. La fase MAP clasifica cada comentario en paralelo con un modelo rápido y una salida tipada; la fase REDUCE agrega estas clasificaciones, mucho más compactas que los textos originales, y confía la síntesis a un modelo más capaz. El coste se desploma en comparación con el análisis completo, porque la mayor parte del volumen se procesa con el modelo más económico.

async def analyze_feedbacks(feedbacks: list[str]):
    # MAP: analizar cada comentario en paralelo
    classifier_agent = Agent(
        name="Classifier",
        instructions="Classify the feedback: positive, negative, or neutral. Identify the main theme.",
        model="gpt-5.6-terra",
        output_type=FeedbackClassification,
    )

    tasks = [Runner.run(classifier_agent, fb) for fb in feedbacks]
    classifications = await asyncio.gather(*tasks)

    # REDUCE: sintetizar resultados
    summary_data = [
        {"feedback": fb, "class": c.final_output.dict()}
        for fb, c in zip(feedbacks, classifications)
    ]

    synthesizer_agent = Agent(
        name="Synthesizer",
        instructions="Synthesize the feedback classifications into a report with statistics and insights.",
        model="gpt-5.6-terra",
    )

    import json
    report = await Runner.run(
        synthesizer_agent,
        f"Synthesize these {len(feedbacks)} classified feedbacks: {json.dumps(summary_data, ensure_ascii=False)}"
    )

    return report.final_output

Gestión de límites de tasa

Lanzar dos mil llamadas simultáneas no hace que terminen antes: el proveedor te rechaza y pierdes el lote. Un semáforo limita el número de ejecuciones concurrentes, y el gestor siguiente añade un retroceso exponencial con un tope de sesenta segundos cuando ocurre un error de límite. El contador de errores se reinicia tan pronto como una llamada tiene éxito, evitando penalizar a largo plazo al servicio por un incidente transitorio.

import asyncio
from agents import Runner

class RateLimitManager:
    def __init__(self, max_concurrent: int = 10):
        self.semaphore = asyncio.Semaphore(max_concurrent)
        self.error_count = 0

    async def execute(self, agent, message, **kwargs):
        async with self.semaphore:
            try:
                result = await Runner.run(agent, message, **kwargs)
                self.error_count = 0
                return result
            except Exception as e:
                if "rate_limit" in str(e).lower():
                    self.error_count += 1
                    wait_time = min(2 ** self.error_count, 60)
                    await asyncio.sleep(wait_time)
                    return await self.execute(agent, message, **kwargs)
                raise

manager = RateLimitManager(max_concurrent=20)

Optimización de costes a gran escala

Luego está la factura. Dos palancas la reducen sin degradar el servicio. La primera es no pagar un modelo de razonamiento para responder «¿cuál es vuestro horario?»: una tabla de búsqueda asigna el nivel de complejidad al modelo adecuado, desde el más económico para preguntas simples hasta el más capaz para casos críticos, con un valor por defecto para cualquier cosa no clasificada. La segunda explota la repetición: en atención al cliente, las mismas preguntas vuelven cientos de veces al día, y una caché indexada por un hash del mensaje devuelve la respuesta al instante y gratis. Reserva esta caché para preguntas cuya respuesta no dependa ni del usuario ni del tiempo: una política de devoluciones se cachea bien, el estado de un pedido nunca.

# Estrategia de modelo por complejidad
def choose_model(complexity: str) -> str:
    models = {
        "simple": "gpt-5.6-terra",      # Preguntas simples: barato
        "medium": "gpt-5.6-terra",       # La mayoría de los casos
        "complex": "gpt-5.6-terra",     # Razonamiento rápido
        "critical": "gpt-5.6-sol",      # Casos críticos: máxima calidad
    }
    return models.get(complexity, "gpt-5.6-terra")

# Caché para respuestas frecuentes
from functools import lru_cache
import hashlib

response_cache = {}

async def execute_with_cache(agent, message: str):
    key = hashlib.md5(message.encode()).hexdigest()
    if key in response_cache:
        return response_cache[key]

    result = await Runner.run(agent, message)
    response_cache[key] = result.final_output
    return result.final_output

Puntos clave

  • Preconfigura tus agentes al inicio y reutilízalos entre solicitudes
  • El SDK gestiona la concurrencia de forma nativa mediante asyncio.gather()
  • El patrón supervisor coordina agentes especializados mediante traspasos (handoffs)
  • El patrón map-reduce paraleliza el procesamiento de grandes volúmenes
  • Gestiona los límites de tasa con un semáforo y retroceso exponencial
  • Optimiza costes con selección de modelo por complejidad y caché

Pon a prueba tus conocimientos

Antes de escalar, verifica tus conocimientos sobre la arquitectura de agentes.

1. ¿Cuáles son los bloques de construcción del SDK de Agentes?

Respuesta: Agent (el rol y sus instrucciones), Runner (el bucle de ejecución), Tool (las capacidades) y Guardrail (validaciones de entrada/salida): la anatomía de cualquier agente del SDK.

2. ¿Para qué sirven los Guardrails?

Respuesta: Para validar lo que entra y sale del agente: filtrar solicitudes fuera de alcance, controlar las salidas antes de que actúen; seguridad declarada en la arquitectura, no esperada del prompt.

3. ¿Qué es un handoff?

Respuesta: La transferencia de una conversación de un agente a otro más especializado: orquestación multiagente donde cada agente hace lo que mejor sabe hacer, con el contexto siguiéndole.

4. ¿Por qué es indispensable el trazado en producción?

Respuesta: Porque un agente decide dinámicamente: sin trazas de los pasos, las herramientas llamadas y las decisiones, la depuración o evaluación es imposible; la calificación de trazas puntuúa precisamente estas ejecuciones.

5. ¿Cuándo debes pasar a una arquitectura multiagente?

Respuesta: Cuando un único agente acumula demasiados roles y herramientas: te especializas (triage, experiencia, ejecución) y orquestas mediante traspasos; cada agente vuelve a ser simple y comprobable.

SDK, guardrails, handoffs, trazado: el andamiaje está completo; el escalado anterior te indica cómo desplegarlo sin debilitarlo.