Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Schalen en multi-agent-architecturen

Les 25 van 25 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Schalen en multi-agent-architecturen
  2. Productie-architectuur
  3. Multi-agent-patronen
  4. Beheer van tarieflimieten
  5. Kostenoptimalisatie op schaal
  6. Belangrijkste punten
  7. Test uw kennis

Schalen en multi-agent-architecturen

Uw agent werkt voor 10 gebruikers. Hoe zorgt u ervoor dat deze draait voor 10.000 gebruikers? De uitdagingen veranderen: het gaat niet langer om mislukte instructies, maar om tarieflimieten van providers, servergeheugen en uw maandelijkse factuur. In deze laatste les leert u uw agents schalen, hoogperformante multi-agent-architecturen ontwerpen en productiebeperkingen op grote schaal beheren.

Productie-architectuur

De agent-backend met FastAPI

De eerste structurele keuze betreft de levenscyclus van de agent. Voor elk verzoek een nieuwe Agent instantiëren is tijdrovend en verspreidt de configuratie; dankzij de lifespan-functionaliteit van FastAPI kunt u ze één keer bij opstarten instantiëren en in een register bewaren, geïndexeerd op type. De route leest het gevraagde type, weigert het netjes als het niet bestaat, en streamt vervolgens het antwoord: run_streamed zendt delta’s uit terwijl de generatie vordert, waardoor tekst direct op het scherm verschijnt in plaats van dat de gebruiker acht seconden naar een laadspinner moet staren.

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

# Pool van voorgeconfigureerde agents
agents_registry = {}

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Initialiseer agents bij opstarten
    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")

Concurrentiebeheer

Het delen van Agent-objecten tussen alle verzoeken op deze manier is veilig, omdat elk verzoek een onafhankelijke Runner creëert: de agent bevat de configuratie, de Runner bevat de uitvoeringsstatus. De SDK behandelt concurrentie native, en het verwerken van een batch berichten betekent coroutines stapelen in asyncio.gather. Het cruciale detail hier is return_exceptions=True: zonder dit annuleert één mislukt verzoek de hele batch. Met deze optie krijgt u fouten als waarden, kunt u ze koppelen aan hun oorspronkelijke bericht en de negenennegentig geldige resultaten verwerken.

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]):
    """Verwerk meerdere verzoeken parallel."""
    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"Fout voor '{msg}': {res}")
        else:
            print(f"'{msg}' -> {res.final_output[:50]}...")

    return results

Multi-agent-patronen

Supervisor-patroon

Boven een bepaalde schaal wordt een enkele agent met vijftien tools onvoorspelbaar: de instructies zwellen aan en de keuzes verslechteren. Het supervisor-patroon verdeelt het werk over gespecialiseerde agents—onderzoek, analyse, schrijven—en delegeert de routing via een handoff aan een toegewijde agent. Elke specialist houdt korte instructies en een model dat bij de taak past: analyse erft een redeneermodel, terwijl de supervisor, die alleen een ontvanger kiest, draait op een snel model omdat zijn beslissing op slechts enkele woorden berust.

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",  # Snel voor routing
)

Pipeline-patroon

Wanneer de volgorde vooraf bekend is, is het laten beslissen van een model over de keten een onnodige kostenpost. Het pipeline-patroon verbindt stappen in uw code: verzamelen, analyseren, schrijven. Een concurrentieanalyse begint dus met twee gelijktijdig gestarte verzamelingen—het web en de CRM hoeven niet op elkaar te wachten—waarna alles naar de analyse gaat, waarvan de output dient als input voor het schrijven. U krijgt een reproduceerbare workflow, stap voor stap traceerbaar, waarvan de totale duur gelijk is aan die van de langzaamste verzameling plus de twee daaropvolgende stappen.

async def competitive_analysis_pipeline(company: str):
    # Stap 1: Parallelle dataverzameling
    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}"""

    # Stap 2: Analyse
    analysis = await Runner.run(analysis_agent, f"Analyze this data: {data}")

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

    return report.final_output

Map-reduce-patroon

Het derde patroon lost een volume-probleem op in plaats van complexiteit. Tweeduizend customer verbatims passen niet in één enkel verzoek en kunnen niet sequentieel worden geanalyseerd binnen een redelijke tijd. De MAP-fase classificeert elke feedback parallel met een snel model en getypeerde output; de REDUCE-fase aggregeert deze classificaties, die veel compacter zijn dan de originele teksten, en vertrouwt de synthese toe aan een capabeler model. De kosten zakken drastisch vergeleken met volledige analyse, omdat het gros van het volume wordt verwerkt door het goedkoopste model.

async def analyze_feedbacks(feedbacks: list[str]):
    # MAP: analyseer elke feedback parallel
    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: synthetiseer resultaten
    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

Beheer van tarieflimieten

Tweeduizend gelijktijdige oproepen lanceren zorgt er niet voor dat ze sneller klaar zijn: de provider weigert u en u verliest de batch. Een semaphore begrenst het aantal gelijktijdige uitvoeringen, en de onderstaande manager voegt exponentiële backoff toe, begrensd op zestig seconden, wanneer een limietfout optreedt. De foutenteller wordt gereset zodra een oproep slaagt, waardoor langdurige straffen voor de service vanwege een tijdelijk incident worden vermeden.

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)

Kostenoptimalisatie op schaal

Dan is er nog de factuur. Twee hefbomen verminderen deze zonder de service te degraderen. De eerste is niet betalen voor een redeneermodel om “wat zijn uw openingstijden” te beantwoorden: een opzoektabel koppelt complexiteitsniveau aan het geschikte model, van het meest economische voor simpele vragen tot het meest capabele voor kritieke gevallen, met een standaardoptie voor alles wat niet is geclassificeerd. De tweede maakt gebruik van herhaling: in klantenservice keren dezelfde vragen honderden keren per dag terug, en een cache geïndexeerd op een bericht-hash geeft het antwoord direct en gratis terug. Reserveer deze cache voor vragen waarvan het antwoord noch van de gebruiker, noch van de tijd afhangt: een retourbeleid cacheert goed, een bestelstatus nooit.

# Modelstrategie per complexiteit
def choose_model(complexity: str) -> str:
    models = {
        "simple": "gpt-5.6-terra",      # Simpele vragen: goedkoop
        "medium": "gpt-5.6-terra",       # De meeste gevallen
        "complex": "gpt-5.6-terra",     # Snel redeneren
        "critical": "gpt-5.6-sol",      # Kritieke gevallen: maximale kwaliteit
    }
    return models.get(complexity, "gpt-5.6-terra")

# Cache voor frequente antwoorden
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

Belangrijkste punten

  • Configureer uw agents vooraf bij opstarten en hergebruik ze tussen verzoeken
  • De SDK behandelt concurrentie native via asyncio.gather()
  • Het supervisor-patroon coördineert gespecialiseerde agents via handoffs
  • Het map-reduce-patroon parallelleert verwerking van grote volumes
  • Beheer tarieflimieten met een semaphore en exponentiële backoff
  • Optimaliseer kosten met modelselectie op basis van complexiteit en caching

Test uw kennis

Controleer uw kennis van agent-architectuur voordat u opschalt.

1. Wat zijn de bouwstenen van de Agents SDK?

Antwoord: Agent (de rol en de instructies), Runner (de uitvoeringslus), Tool (de mogelijkheden) en Guardrail (validaties voor input/output)—de anatomie van elke SDK-agent.

2. Waar dienen Guardrails voor?

Antwoord: Om te valideren wat de agent binnenkomt en verlaat: filter verzoeken buiten de scope, controleer outputs voordat ze actie ondernemen—beveiliging die in de architectuur is vastgelegd, niet gehoopt vanuit de prompt.

3. Wat is een handoff?

Antwoord: De overdracht van een gesprek van de ene agent naar een andere, meer gespecialiseerde agent: multi-agent-orchestratie waarbij elke agent doet waar hij goed in is, met behoud van context.

4. Waarom is tracing onmisbaar in productie?

Antwoord: Omdat een agent dynamisch beslist: zonder sporen van stappen, aangeroepen tools en beslissingen is debuggen of evalueren onmogelijk—trace grading scoort deze uitvoeringen nauwkeurig.

5. Wanneer moet u overstappen op een multi-agent-architectuur?

Antwoord: Wanneer een enkele agent te veel rollen en tools accumuleert: u specialiseert (triage, expertise, uitvoering) en orchestreert via handoffs—elke agent wordt weer simpel en testbaar.

SDK, guardrails, handoffs, tracing: de steigers zijn compleet—het bovenstaande over schalen vertelt u hoe u dit inzet zonder het te verzwakken.