Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Skaalaus ja moniagenttiarkkitehtuurit

Oppitunti 25 / 25 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Skaalaus ja moniagenttiarkkitehtuurit
  2. Tuotantoarkkitehtuuri
  3. Moniagenttimallit
  4. Nopeusrajoitusten hallinta
  5. Kustannusten optimointi suurissa mittakaavoissa
  6. Keskeiset asiat
  7. Testaa tietämyksesi

Skaalaus ja moniagenttiarkkitehtuurit

Agenttisi toimii 10 käyttäjälle. Miten saat sen toimimaan 10 000 käyttäjälle? Haasteet muuttuvat: kyse ei enää ole epäonnistuvista ohjeista, vaan tarjoajan nopeusrajoituksista, palvelimen muistista ja kuukausilaskustasi. Tässä viimeisessä oppitunnissa opit skaalaamaan agenttejasi, suunnittelemaan suorituskykyisiä moniagenttiarkkitehtuureja ja hallitsemaan tuotannon rajoitteita suurissa mittakaavoissa.

Tuotantoarkkitehtuuri

Agentin taustajärjestelmä FastAPIlla

Ensimmäinen rakenteellinen päätös koskee agentin elinkaarta. Agent-olion luominen jokaista pyyntöä varten tuhlaa aikaa ja hajauttaa konfiguraatiota; FastAPIn lifespan-toiminnallisuuden avulla voit luoda ne kerran käynnistyksen yhteydessä ja pitää ne rekisterissä tyypin mukaan indeksoituna. Reitti lukee pyydetyn tyypin, hylkää sen siististi, jos sitä ei ole olemassa, ja lähettää vastauksen virtana: run_streamed emittoi deltoja generoinnin edetessä, jolloin teksti ilmestyy näytölle välittömästi sen sijaan, että käyttäjä tuijottaisi latausindikaattoria kahdeksan sekunnin ajan.

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

# Esikonfiguroitujen agenttien pooli
agents_registry = {}

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Alustetaan agentit käynnistyksen yhteydessä
    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")

Samanaikaisuuden hallinta

Agent-olioiden jakaminen kaikkien pyyntöjen kesken tällä tavalla on turvallista, koska jokainen pyyntö luo itsenäisen Runnerin: agentti pitää hallussaan konfiguraatiota, kun taas Runner hallinnoi suoritus tilaa. SDK käsittelee samanaikaisuuden natiivisti, ja viestierän käsittely tarkoittaa korutiinien pinomista asyncio.gather-funktiolla. Tässä avainasia on return_exceptions=True: ilman sitä yksikin epäonnistunut pyyntö peruuttaa koko erän. Sen kanssa saat virheet arvoina, voit yhdistää ne alkuperäiseen viestiin ja käsitellä yhdeksänkymmentäyhdeksän validia tulosta.

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]):
    """Käsittele useita pyyntöjä rinnakkain."""
    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 for '{msg}': {res}")
        else:
            print(f"'{msg}' -> {res.final_output[:50]}...")

    return results

Moniagenttimallit

Valvojamalli (Supervisor Pattern)

Tietyn skaalan ylittyessä yhdestä agentista, jolla on viisitoista työkalua, tulee arvaamaton: sen ohjeet paisuvat ja sen valinnat heikkenevät. Valvojamalli jakaa työn erikoistuneiden agenttien kesken – tutkimus, analyysi, kirjoittaminen – ja delegoi reitityksen omistetulle agentille handoff-mekanismin kautta. Jokainen asiantuntija pitää yllä lyhyitä ohjeita ja tehtäväänsä sopivaa mallia: analyysi perii päättelymallin, kun taas valvoja, joka vain valitsee vastaanottajan, toimii nopealla mallilla, sillä sen päätös riippuu muutamasta sanasta.

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",  # Nopea reititykseen
)

Putkimalli (Pipeline Pattern)

Kun sekvenssi on tiedossa etukäteen, mallin päätöksenteon ketjuttaminen on tarpeeton kulu. Putkimalli kytkentää vaiheet koodiisi: kerää, analysoi, kirjoita. Kilpailuanalyysi alkaa siis kahdella samanaikaisesti käynnistetyllä keruulla – verkkolla ja CRM:llä ei ole syytä odottaa toisiaan – minkä jälkeen kaikki siirretään analyysille, jonka syöte ruokkii kirjoitusvaihetta. Saat toistettavan työnkulun, jonka voi jäljittää vaihe vaiheelta ja jonka kokonaiskesto on hitaimman keruun plus kahden seuraavan vaiheen kesto.

async def competitive_analysis_pipeline(company: str):
    # Vaihe 1: Rinnakkainen tiedonkeruu
    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}"""

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

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

    return report.final_output

Map-Reduce-malli

Kolmas malli ratkoo volume-ongelmaa eikä kompleksisuutta. Kaksi tuhatta asiakaspalautetta eivät mahdu yhteen pyyntöön, eikä niitä voi analysoida peräkkäin kohtuullisessa ajassa. MAP-vaihe luokittelee jokaisen palautteen rinnakkain nopealla mallilla ja tyypitetyllä tulosteella; REDUCE-vaihe aggregoi nämä luokitukset, jotka ovat paljon alkuperäisiä tekstejä kompaktimpia, ja uskoo synteesin kyvykkäämmälle mallille. Kustannukset romahtavat verrattuna täydelliseen analyysiin, koska suurin osa volumesta käsitellään halvimmalla mallilla.

async def analyze_feedbacks(feedbacks: list[str]):
    # MAP: analysoi jokainen palaute rinnakkain
    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: syntetisoi tulokset
    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

Nopeusrajoitusten hallinta

Kahdentuhannen samanaikaisen puhelun käynnistäminen ei saa niitä valmistumaan nopeammin: tarjoaja kieltäytyy pyynnöstäsi ja menetät erän. Semafori rajoittaa samanaikaisten suoritusten määrää, ja alla oleva manageri lisää eksponentiaalisen odotusajan (backoff), joka on rajoitettu kuuteenkymmeneen sekuntiin, kun nopeusvirhe tapahtuu. Virhelaskuri nollautuu heti, kun puhelu onnistuu, välttäen palvelun pitkäaikaisen rankaisemisen ohimenevästä häiriöstä johtuen.

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)

Kustannusten optimointi suurissa mittakaavoissa

Sitten on lasku. Sitä voi pienentää kahdella vivulla palvelua heikentämättä. Ensimmäinen on olla maksamatta päättelymallista vastauksesta kysymykseen “mitkä ovat aukioloaikanne”: hakutaulukko kuvaa kompleksisuustason sopivaan malliin, halvimmasta yksinkertaisiin kysymyksiin kyvykkäimpään kriittisiin tapauksiin, oletusarvolla kaikelle luokittelemattomalle. Toinen hyödyntää toistoa – asiakastuessa samat kysymykset palaavat satoja kertoja päivässä, ja viestiin hash-arvon perusteella indeksoitu välimuisti palauttaa vastauksen välittömästi ja ilmaiseksi. Varaa tämä välimuisti kysymyksille, joiden vastaus ei riipu käyttäjästä eikä ajasta: palautuskäytäntö välimuistioituu hyvin, tilauksen status ei koskaan.

# Mallistrategia kompleksisuuden mukaan
def choose_model(complexity: str) -> str:
    models = {
        "simple": "gpt-5.6-terra",      # Yksinkertaiset kysymykset: halpa
        "medium": "gpt-5.6-terra",       # Useimmat tapaukset
        "complex": "gpt-5.6-terra",     # Nopea päättely
        "critical": "gpt-5.6-sol",      # Kriittiset tapaukset: maksimilaatu
    }
    return models.get(complexity, "gpt-5.6-terra")

# Välimuisti yleisille vastauksille
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

Keskeiset asiat

  • Esikonfiguroi agenttisi käynnistyksen yhteydessä ja uudelleenkäytä niitä pyyntöjen yli
  • SDK käsittelee samanaikaisuuden natiivisti asyncio.gather()-funktiolla
  • Valvojamalli koordinoi erikoistuneita agentteja handoffien kautta
  • Map-reduce-malli rinnakkaistaa suurten volyymien käsittelyn
  • Hallitse nopeusrajoituksia semaforilla ja eksponentiaalisella odotusajalla
  • Optimoi kustannuksia mallivalinnalla kompleksisuuden mukaan ja välimuistilla

Testaa tietämyksesi

Ennen skaalausta tarkista agenttiarkkitehtuuritietämyksesi.

1. Mitkä ovat Agents SDK:n rakennuspalikat?

Vastaus: Agent (rooli ja sen ohjeet), Runner (suoritussilmukka), Tool (ominaisuudet) ja Guardrail (syöte/tuloste-validoinnit) – minkä tahansa SDK-agentin anatomia.

2. Mihin Guardrailit ovat tarkoitettu?

Vastaus: Validoimaan agenttiin saapuva ja sieltä lähtevä data: suodattamaan aiheen ulkopuoliset pyynnöt, hallitsemaan tulosteita ennen niiden toimintaa – turvallisuus määriteltynä arkkitehtuuriin, ei toivottuna kehotteesta.

3. Mikä on handoff?

Vastaus: Keskustelun siirto yhdeltä agentilta toiselle, erikoistuneemmalle agentille: moniagentti-orkestrointia, jossa jokainen agentti tekee sen, minkä osaa parhaiten, kontekstin seuraten mukana.

4. Miksi jäljitettävyys (tracing) on välttämätöntä tuotannossa?

Vastaus: Koska agentti päättää dynaamisesti: ilman jälkiä vaiheista, kutsutuista työkaluista ja päätöksistä vianetsintä tai arviointi on mahdotonta – trace-gradaus pisteyttää nämä suoritukset tarkasti.

5. Milloin tulisi siirtyä moniagenttiarkkitehtuuriin?

Vastaus: Kun yksittäinen agentti kerää liian monta roolia ja työkalua: erikoistut (lajittelu, asiantuntemus, suoritus) ja orkestroit handoffien kautta – jokaisesta agentista tulee jälleen yksinkertainen ja testattava.

SDK, guardrailit, handoffit, jäljitettävyys: telineet ovat valmiit – yllä oleva skaalaus kertoo, miten otat sen käyttöön heikentämättä sitä.