Škálovanie a architektúry s viacerými agentmi
Na tejto strane
Škálovanie a architektúry s viacerými agentmi
Tvoj agent funguje pre 10 používateľov. Ako ho rozbehneš pre 10 000? Výzvy sa menia: už nejde o zlyhávajúce inštrukcie, ale o limity rýchlosti poskytovateľa, pamäť servera a tvoju mesačnú faktúru. V tejto záverečnej lekcii sa naučíš, ako škálovať svojich agentov, navrhovať vysoko výkonné architektúry s viacerými agentmi a riadiť produkčné obmedzenia vo veľkom meradle.
Produkčná architektúra
Backend agenta s FastAPI
Prvé štrukturálne rozhodnutie sa týka životného cyklu agenta. Vytváranie inštancie Agent pre každú požiadavku plytvá časom a roztriešti konfiguráciu; lifespan vo FastAPI ti umožňuje vytvoriť ich raz pri štarte a uchovávať v registri indexovanom podľa typu. Trasa číta požadovaný typ, ak neexistuje, požiadavku čisto odmietne a následne streamuje odpoveď: run_streamed vysiela delty počas generovania, čo spôsobí, že text sa objaví na obrazovke okamžite, namiesto toho, aby používateľ hľadel na načítavací spinner osem sekúnd.
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 predkonfigurovaných agentov
agents_registry = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
# Inicializácia agentov pri štarte
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")
Riadenie súbežnosti
Zdieľanie objektov Agent medzi všetkými požiadavkami týmto spôsobom je bezpečné, pretože každá požiadavka vytvára nezávislého Runnera: agent drží konfiguráciu, Runner drží stav vykonávania. SDK natívne rieši súbežnosť a spracovanie dávky správ znamená skladanie korutín v asyncio.gather. Kľúčovým detailom je tu return_exceptions=True: bez neho by jedna neúspešná požiadavka zrušila celú dávku. S ním dostaneš chyby ako hodnoty, priradíš ich k pôvodnej správe a spracuješ deväťdesiatdeväť platných výsledkov.
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]):
"""Spracovanie viacerých požiadaviek paralelne."""
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"Chyba pre '{msg}': {res}")
else:
print(f"'{msg}' -> {res.final_output[:50]}...")
return results
Vzory pre viacerých agentov
Vzor supervízora
Po dosiahnutí určitého meradla sa jeden agent s pätnástimi nástrojmi stáva nepredvídateľným: jeho inštrukcie nafukujú, jeho rozhodnutia sa zhoršujú. Vzor supervízora rozdeľuje prácu medzi špecializovaných agentov – výskum, analýza, písanie – a deleguje smerovanie vyhradenému agentovi prostredníctvom handoffu. Každý špecialista si udržuje krátke inštrukcie a model vhodný pre jeho úlohu: analýza dedí model zameraný na uvažovanie, zatiaľ čo supervízor, ktorý iba vyberá príjemcu, beží na rýchlom modeli, keďže jeho rozhodnutie závisí od niekoľkých slov.
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ýchly na smerovanie
)
Vzor pipeline (potrubia)
Keď je postupnosť známa vopred, nechať model rozhodovať o reťazci je zbytočným výdavkom. Vzor pipeline prepája kroky priamo v tvojom kóde: zber, analýza, písanie. Konkurenčná analýza tak začína dvoma súbežnými zbermi – web a CRM nemajú dôvod čakať jeden na druhého – a potom všetko odovzdá analýze, ktorej výstup napája písanie. Získaš reprodukovateľný pracovný postup, sledovateľný krok za krokom, ktorého celková dĺžka trvania zodpovedá najpomalšiemu zberu plus dvom nasledujúcim krokom.
async def competitive_analysis_pipeline(company: str):
# Krok 1: Paralelný zber dát
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}"""
# Krok 2: Analýza
analysis = await Runner.run(analysis_agent, f"Analyze this data: {data}")
# Krok 3: Správa
report = await Runner.run(
writing_agent,
f"Write a competitive analysis report: {analysis.final_output}"
)
return report.final_output
Vzor Map-Reduce
Tretí vzor rieši problém objemu, nie zložitosti. Dvetisíc priamych vyjadrení zákazníkov sa nezmestí do jednej požiadavky a nedá sa rozумne analyzovať sekvenčne. Fáza MAP klasifikuje každú spätnú väzbu paralelne pomocou rýchleho modelu a typovaného výstupu; fáza REDUCE agreguje tieto klasifikácie, ktoré sú oveľa kompaktnejšie ako pôvodné texty, a syntézu zverí schopnejšiemu modelu. Náklady sa v porovnaní s úplnou analýzou zrútia, pretože väčšina objemu sa spracúva najlacnejším modelom.
async def analyze_feedbacks(feedbacks: list[str]):
# MAP: analýza každej spätnej väzby paralelne
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: syntéza výsledkov
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
Riadenie limitov rýchlosti (Rate Limits)
Spustenie dvetisíc súbežných volaní ich neskončí rýchlejšie: poskytovateľ ťa odmietne a stratíš celú dávku. Semafór obmedzuje počet súbežných vykonaní a nižšie uvedený správca pridáva exponenciálne oneskorenie (backoff) s hornou hranicou šesťdesiat sekúnd, keď nastane chyba limitu. Počítadlo chýb sa resetuje hneď, ako sa volanie úspešne dokončí, čím sa predíde dlhodobému postihu služby pre prechodný incident.
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)
Optimalizácia nákladov vo veľkom meradle
Potom je tu faktúra. Dve páky ju znižujú bez zhoršenia služby. Prvou je neplatiť za model zameraný na uvažovanie, aby odpovedal na otázku „aké máte otváracie hodiny“: tabuľka vyhľadávania mapuje úroveň zložitosti na vhodný model, od najúspornejšieho pre jednoduché otázky až po najsilnejší pre kritické prípady, s predvolenou hodnotou pre všetko neklasifikované. Druhá využíva opakovanie – v zákazníckej podpore sa tie isté otázky vracajú stokrát denne a cache indexovaná hashom správy vráti odpoveď okamžite a zadarmo. Túto cache si vyhradź pre otázky, ktorých odpoveď nezávisí ani od používateľa, ani od času: politika vrátenia tovaru sa cacheuje dobre, stav objednávky nikdy.
# Stratégia modelu podľa zložitosti
def choose_model(complexity: str) -> str:
models = {
"simple": "gpt-5.6-terra", # Jednoduché otázky: lacné
"medium": "gpt-5.6-terra", # Väčšina prípadov
"complex": "gpt-5.6-terra", # Rýchle uvažovanie
"critical": "gpt-5.6-sol", # Kritické prípady: maximálna kvalita
}
return models.get(complexity, "gpt-5.6-terra")
# Cache pre časté odpovede
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
Kľúčové poznatky
- Predkonfiguruj svojich agentov pri štarte a opätovne ich využívaj naprieč požiadavkami
- SDK natívne rieši súbežnosť prostredníctvom
asyncio.gather() - Vzor supervízora koordinuje špecializovaných agentov prostredníctvom handoffov
- Vzor map-reduce paralelizuje spracovanie veľkých objemov
- Riad limity rýchlosti pomocou semaforu a exponenciálneho oneskorenia
- Optimalizuj náklady výberom modelu podľa zložitosti a používaním cache
Otestuj si svoje vedomosti
Predtým, ako začneš škálovať, over si svoje vedomosti o architektúre agentov.
1. Aké sú stavebné kamene SDK Agents?
Odpoveď: Agent (rola a jej inštrukcie), Runner (vykonávacia slučka), Tool (schopnosti) a Guardrail (validácie vstupu/výstupu) – anatómia akéhokoľvek agenta v SDK.
2. Na čo slúžia Guardrails?
Odpoveď: Na validáciu toho, čo vstupuje do agenta a čo z neho vychádza: filtrovanie požiadaviek mimo rozsah, kontrola výstupov pred ich vykonaním – bezpečnosť deklarovaná v architektúre, nie len dúfaná z promptu.
3. Čo je handoff?
Odpoveď: Prenos konverzácie z jedného agenta na druhého, špecializovanejšieho: orchestrácia viacerých agentov, kde každý robí to, v čom je najlepší, pričom kontext pokračuje ďalej.
4. Prečo je trasovanie (tracing) v produkcii nevyhnutné?
Odpoveď: Pretože agent rozhoduje dynamicky: bez stôp krokov, volaných nástrojov a rozhodnutí je ladenie alebo hodnotenie nemožné – hodnotenie trás presne boduje tieto vykonania.
5. Kedy by si mal prejsť na architektúru s viacerými agentmi?
Odpoveď: Keď jeden agent nahromadí príliš veľa rolí a nástrojov: špecializuješ sa (triedenie, expertíza, vykonávanie) a orchestruješ prostredníctvom handoffov – každý agent sa opäť stane jednoduchým a testovateľným.
SDK, guardrails, handoffs, trasovanie: lešenie je kompletné – vyššie uvedené škálovanie ti hovorí, ako ho nasadiť bez toho, aby si ho oslabil.