Skálázás és többügynökös architektúrák
Ezen az oldalon
Skálázás és többügynökös architektúrák
Az ügynököd 10 felhasználó számára működik. Hogyan érheted el, hogy 10 000 számára fusson? A kihívások megváltoznak: többé nem arról van szó, hogy az utasítások meghiúsulnak, hanem a szolgáltatói sebességkorlátokról, a szervermemóriáról és a havi számládról. Ebben az utolsó leckében megtanulod, hogyan skálázd az ügynökeidet, hogyan tervezz nagy teljesítményű többügynökös architektúrákat, és hogyan kezeld a gyártási korlátokat nagy méretben.
Gyártási architektúra
Az ügynök backendje FastAPI-val
Az első strukturális döntés az ügynök életciklusára vonatkozik. Ha minden kéréshez létrehozol egy Agent példányt, az időpocsékolás és szétszórja a konfigurációt; a FastAPI lifespan funkciója lehetővé teszi, hogy indításkor egyszer példányosítsd őket, és egy típus szerint indexelt regiszterben tartsd őket. Az útvonal beolvassa a kért típust, tisztán elutasítja, ha nem létezik, majd streameli a választ: a run_streamed deltákat bocsát ki a generálás során, így a szöveg azonnal megjelenik a képernyőn, ahelyett, hogy a felhasználónak nyolc másodpercig egy betöltő ikont kellene bámulnia.
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
# Előre konfigurált ügynökök készlete
agents_registry = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
# Ügynökök inicializálása indításkor
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")
Egyidejűség kezelése
Az Agent objektumok ilyen módon történő megosztása minden kérés között biztonságos, mivel minden kérés egy független Runnert hoz létre: az ügynök tárolja a konfigurációt, a Runner pedig a végrehajtási állapotot. Az SDK natívan kezeli az egyidejűséget, és az üzenetek kötegének feldolgozása azt jelenti, hogy korutinokat halmozunk az asyncio.gather segítségével. Itt a kulcsfontosságú részlet a return_exceptions=True: enélkül egyetlen sikertelen kérés megszakítja az egész köteget. Ezzel azonban értékként kapod meg a hibákat, párosítod őket az eredeti üzenettel, és feldolgozod a kilencvenkilenc érvényes eredményt.
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]):
"""Több kérés párhuzamos feldolgozása."""
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
Többügynökös minták
Felügyelő minta
Egy bizonyos méret felett egyetlen ügynök tizenöt eszközzel kiszámíthatatlanná válik: az utasításai felfúvódnak, a döntései romlanak. A felügyelő minta specializált ügynökök között osztja szét a munkát – kutatás, elemzés, írás –, és egy dedikált ügynökre bízza az útvonalválasztást handoff (átadás) révén. Minden specialista rövid utasításokat és a feladatához illő modellt kap: az elemzés egy következtető modellt örököl, míg a felügyelő, amely csak címzettet választ, egy gyors modellen fut, mivel döntése néhány szón múlik.
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", # Fast for routing
)
Pipeline minta
Amikor a sorrend előre ismert, felesleges költség, ha egy modell dönt a láncolatról. A pipeline minta a kódodban köti össze a lépéseket: gyűjtés, elemzés, írás. Egy versenyhelyzet-elemzés így két párhuzamosan indított gyűjtéssel kezdődik – a webnek és a CRM-nek nincs oka várni egymásra –, majd mindent átad az elemzésnek, amelynek kimenete táplálja az írást. Így egy reprodukálható, lépésről lépésre nyomon követhető munkafolyamatot kapsz, amelynek teljes időtartama a leglassabb gyűjtés ideje plusz a két következő lépésé.
async def competitive_analysis_pipeline(company: str):
# 1. lépés: Párhuzamos adatgyűjtés
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}"""
# 2. lépés: Elemzés
analysis = await Runner.run(analysis_agent, f"Analyze this data: {data}")
# 3. lépés: Jelentés
report = await Runner.run(
writing_agent,
f"Write a competitive analysis report: {analysis.final_output}"
)
return report.final_output
Map-Reduce minta
A harmadik minta nem a bonyolultságot, hanem a mennyiséget kezeli. Kétezer ügyfélvélemény nem fér bele egyetlen kérésbe, és ésszerű időn belül nem elemezhető sorosan. A MAP fázis minden visszajelzést párhuzamosan osztályoz egy gyors modellel és típusos kimenettel; a REDUCE fázis aggregálja ezeket az osztályozásokat – amelyek sokkal kompaktabbak, mint az eredeti szövegek –, és a szintézist egy képesebb modellre bízza. A költség drasztikusan csökken a teljes elemzéshez képest, mivel a mennyiség nagy részét a legolcsóbb modell dolgozza fel.
async def analyze_feedbacks(feedbacks: list[str]):
# MAP: minden visszajelzés párhuzamos elemzése
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: eredmények szintetizálása
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
Sebességkorlátok kezelése
Kétezer egyidejű hívás indítása nem gyorsítja meg a befejezést: a szolgáltató elutasít, és elveszíted a köteget. Egy szemafor korlátozza az egyidejű végrehajtások számát, és az alábbi kezelő exponenciális visszalépést (backoff) alkalmaz, maximum hatvan másodpercre korlátozva, ha sebességkorlát-hiba lép fel. A hibaszámláló nullázódik, amint egy hívás sikerül, elkerülve ezzel, hogy egy átmeneti incidens hosszú távon büntesse a szolgáltatást.
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)
Költségoptimalizálás nagy méretben
Aztán ott van a számla. Két kar van, amellyel csökkentheted anélkül, hogy rontanád a szolgáltatást. Az első, hogy ne fizess egy következtető modellért olyan kérdésekre, mint „mik a nyitvatartási órák“: egy keresőtábla rendeli a komplexitási szinthez a megfelelő modellt, az egyszerű kérdésekhez a legolcsóbbtól a kritikus esetekhez a legképesebbig, alapértelmezéssel minden nem kategorizált esetre. A második a repetitivitást használja ki: az ügyfélszolgálaton ugyanazok a kérdések százszor térnek vissza naponta, és egy üzenet-hash alapján indexelt gyorsítótár azonnal és ingyen adja vissza a választ. Ezt a gyorsítótárat olyan kérdésekre tartogasd, amelyek válasza sem a felhasználótól, sem az időtől nem függ: egy visszaküldési szabályzat jól gyorsítótárazható, egy rendelés állapota soha.
# Modellstratégia komplexitás szerint
def choose_model(complexity: str) -> str:
models = {
"simple": "gpt-5.6-terra", # Egyszerű kérdések: olcsó
"medium": "gpt-5.6-terra", # Legtöbb eset
"complex": "gpt-5.6-terra", # Gyors következtetés
"critical": "gpt-5.6-sol", # Kritikus esetek: maximális minőség
}
return models.get(complexity, "gpt-5.6-terra")
# Gyorsítótár gyakori válaszokhoz
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
Főbb megállapítások
- Konfiguráld előre az ügynökeidet indításkor, és használd őket újra a kérések között
- Az SDK natívan kezeli az egyidejűséget az
asyncio.gather()segítségével - A felügyelő minta specializált ügynököket koordinál handoffokon keresztül
- A map-reduce minta párhuzamosítja a nagy mennyiségű feldolgozást
- Kezeld a sebességkorlátokat szemaforral és exponenciális visszalépéssel
- Optimalizáld a költségeket komplexitás szerinti modellválasztással és gyorsítótárazással
Teszteld a tudásod
Mielőtt nagy méretre skáláznál, ellenőrizd az ügynök-architektúrával kapcsolatos ismereteidet.
1. Mik az Agents SDK építőkövei?
Válasz: Agent (a szerep és annak utasításai), Runner (a végrehajtási ciklus), Tool (a képességek) és Guardrail (bemeneti/kimeneti validációk) – bármely SDK-ügynök anatómiája.
2. Mire valók a Guardrailek?
Válasz: Arra, hogy validálják, ami belép és kilép az ügynökből: kiszűrik a hatókörön kívüli kéréseket, és vezérlik a kimeneteket, mielőtt azok cselekednének – a biztonság az architektúrába van deklarálva, nem pedig a prompttól reméljük.
3. Mi a handoff?
Válasz: A beszélgetés átadása egyik ügynöktől egy másik, specializáltabb ügynöknek: többügynökös orchestráció, ahol minden ügynök azt csinálja, amihez a legjobban ért, a kontextus pedig követi az átadást.
4. Miért nélkülözhetetlen a nyomkövetés (tracing) gyártási környezetben?
Válasz: Mert az ügynök dinamikusan dönt: lépések, meghívott eszközök és döntések nyomai nélkül lehetetlen a hibakeresés vagy az értékelés – a nyomkövetési osztályozás pontosan pontozza ezeket a végrehajtásokat.
5. Mikor kell áttérni többügynökös architektúrára?
Válasz: Amikor egyetlen ügynök túl sok szerepet és eszközt halmoz fel: specializálódsz (triázs, szakértelem, végrehajtás), és handoffokon keresztül orchestrálsz – így minden ügynök ismét egyszerű és tesztelhető lesz.
SDK, guardrailek, handoffok, nyomkövetés: az állványzat kész – a fenti skálázás megmutatja, hogyan telepítsd anélkül, hogy gyengítenéd.