Skaleerimine ja mitme agendi arhitektuurid
Sellel lehel
Skaleerimine ja mitme agendi arhitektuurid
Su agent töötab 10 kasutajaga. Kuidas panna see tööle 10 000 jaoks? Väljakutsed muutuvad: enam ei ole asi selles, et juhised ebaõnnestuvad, vaid pakkuja kiirusepiirangutes, serveri mälus ja sinu kuuarves. Selles viimases õppetükis õpid, kuidas oma agente skaleerida, projekteerida suure jõudlusega mitme agendi arhitektuure ja hallata tootmispiiranguid suurel skaalal.
Tootmisarhitektuur
Agendi taustsüsteem FastAPI-ga
Esimene struktuurne otsus puudutab agendi elutsüklit. Iga päringu jaoks uue Agenti loomine raiskab aega ja hajutab konfiguratsiooni; FastAPI lifespan võimaldab need käivitamisel üks kord luua ja hoida registris, mis on indekseeritud tüübi järgi. Ruut loeb soovitud tüübi, lükkab selle korrektselt tagasi, kui seda ei eksisteeri, ja edastab vastuse voona: run_streamed väljastab deltasid genereerimise käigus, pannes teksti ekraanile ilmuma koheselt, selle asemel et jätta kasutaja kaheksaks sekundiks laadimisketast vahtima.
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
# Eelkonfigureeritud agentide bassein
agents_registry = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
# Loo agendid käivitamisel
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")
Samaaegsuse haldamine
Agenti objektide jagamine kõigi päringute vahel on sellisel viisil ohutu, kuna iga päring loob sõltumatu Runneri: agent hoiab konfiguratsiooni, Runner aga täitmise olekut. SDK haldab samaaegsust loomupäraselt ja sõnumite partii töötlemine tähendab korutiinide virnastamist asyncio.gather abil. Siin on võtmeks return_exceptions=True: ilma selleta tühistab üks ebaõnnestunud päring kogu partii. Sellega saad vead väärtustena, seod need algse sõnumiga ja töötledd üheksakümmend üheksa kehtivat tulemust.
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öötle mitu päringut paralleelselt."""
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
Mitme agendi mustrid
Järelevaataja muster
Teatud skaalast alates muutub viieteistkümne tööriistaga üksik agent ettearvamatuks: selle juhised paisuvad, valikud halvenevad. Järelevaataja muster jaotab töö spetsialiseerunud agentide vahel – uurimine, analüüs, kirjutamine – ja delegeerib marsruutimise pühendatud agendile üleandmise (handoff) kaudu. Iga spetsialist hoiab lühikesi juhiseid ja oma ülesandele sobivat mudelit: analüüs pärib arutlusvõimelise mudeli, samas kui järelevaataja, kes vaid vastuvõtjat valib, töötab kiirel mudelil, kuna selle otsus sõltub paarist sõnast.
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", # Kiire marsruutimiseks
)
Torustiku muster
Kui järjestus on ette teada, on mudeli otsustada lasta ahela üle tarbetu kulu. Torustiku muster ühendab sammud sinu koodis: kogumine, analüüs, kirjutamine. Konkurentsianalüüs algab seega kahe samaaegse kogumisega – veebil ja CRM-il pole põhjust teineteist oodata – ning seejärel antakse kõik analüüsile, mille väljund toidab kirjutamist. Saad korratava töövoo, mida saab samm-sammult jälgida ja mille kogukestus on võrdne aeglaseima kogumise pluss kahe järgneva sammu kestusega.
async def competitive_analysis_pipeline(company: str):
# 1. samm: Paralleelne andmekogumine
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. samm: Analüüs
analysis = await Runner.run(analysis_agent, f"Analyze this data: {data}")
# 3. samm: Aruanne
report = await Runner.run(
writing_agent,
f"Write a competitive analysis report: {analysis.final_output}"
)
return report.final_output
Map-Reduce muster
Kolmas muster lahendab pigem mahuprobleemi kui keerukust. Kaks tuhat kliendi tagasisidet ei mahu ühte päringusse ja neid ei saa mõistliku aja jooksul järjestikku analüüsida. MAP-faas liigitab iga tagasiside paralleelselt kiire mudeli ja tüübitud väljundiga; REDUCE-faas koondab need liigitused, mis on algsetest tekstidest palju kompaktsemad, ja usaldab sünteesi võimekamale mudelile. Kulud kukuvad võrreldes täisanalüüsiga kokku, kuna suurem osa mahust töödeldakse odavaima mudeliga.
async def analyze_feedbacks(feedbacks: list[str]):
# MAP: analüüsi iga tagasisidet paralleelselt
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: sünteesi tulemused
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
Kiirusepiirangute haldamine
Kahe tuhande samaaegse kõne käivitamine ei pane neid kiiremini lõppema: pakkuja keeldub sind teenindamast ja sa kaotad kogu partii. Semaphor piirab samaaegsete täitmiste arvu ja allpool olev haldur lisab eksponentsiaalse tagasiminekuga viite, mis on piiratud kuuekümne sekundiga, kui tekib piirangu viga. Vealoendur lähtestatakse niipea, kui kõne õnnestub, vältides teenuse pikaajalist karistamist mööduva intsidenti eest.
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)
Kulude optimeerimine suurel skaalal
Siis on veel arve. Seda saab vähendada kahe hoovaga, teenust halvendamata. Esimene on mitte maksta arutlusvõimelisele mudelile vastuse eest küsimusele „millised on teie lahtiolekuajad“: otsingutabel seob keerukustaseme sobiva mudeliga, alates kõige ökonoomsemast lihtsate küsimuste jaoks kuni võimekaimani kriitiliste juhtumite jaoks, koos vaikimisi valikuga klassifitseerimata puhuks. Teine kasutab ära korduvust – klienditoes korduvad samad küsimused sadu kordi päevas – ja sõnumi räsil põhinev vahemälu tagastab vastuse koheselt ja tasuta. Reserveeri see vahemälu küsimustele, mille vastus ei sõltu ei kasutajast ega ajast: tagastuspoliitika vahemällu sobib hästi, tellimuse staatus aga mitte kunagi.
# Mudeli strateegia keerukuse järgi
def choose_model(complexity: str) -> str:
models = {
"simple": "gpt-5.6-terra", # Lihtsad küsimused: odav
"medium": "gpt-5.6-terra", # Enamik juhtumeid
"complex": "gpt-5.6-terra", # Kiire arutlus
"critical": "gpt-5.6-sol", # Kriitilised juhtumid: maksimaalne kvaliteet
}
return models.get(complexity, "gpt-5.6-terra")
# Vahemälu sagedastele vastustele
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
Peamised punktid
- Konfigureeri oma agendid käivitamisel eelnevalt ja kasuta neid päringute lõikes uuesti
- SDK haldab samaaegsust loomupäraselt
asyncio.gather()kaudu - Järelevaataja muster koordineerib spetsialiseerunud agente üleandmiste (handoffs) kaudu
- Map-reduce muster paralleliseerib suure mahuga töötlemist
- Halla kiirusepiiranguid semaphori ja eksponentsiaalse tagasiminekuga
- Optimeeri kulusid mudeli valikuga keerukuse järgi ja vahemäluga
Testi oma teadmisi
Enne skaleerimist kontrolli oma teadmisi agendi arhitektuuri kohta.
1. Mis on Agents SDK ehitusplokid?
Vastus: Agent (roll ja selle juhised), Runner (täitmise tsükkel), Tool (võimekused) ja Guardrail (sisendi/väljundi valideerimised) – iga SDK agendi anatoomia.
2. Milleks on Guardrails?
Vastus: Et valideerida seda, mis agentisse siseneb ja sealt väljub: filtreerida väljaspool teemat olevad päringud, kontrollida väljundeid enne nende toimimist – turvalisus, mis on deklareeritud arhitektuuris, mitte ei loodeta sellele vihje (prompt) põhjal.
3. Mis on üleandmine (handoff)?
Vastus: Vestluse ülekanne ühelt agendilt teisele, spetsialiseerunumale: mitme agendi orkestreerimine, kus iga agent teeb seda, mida ta kõige paremini oskab, koos konteksti edasikandmisega.
4. Miks on jälgimine tootmises hädavajalik?
Vastus: Sest agent otsustab dünaamiliselt: ilma sammude, kutsutud tööriistade ja otsuste jälgedeta on silumine või hindamine võimatu – jälgimise hindamine annab nende täitmiste jaoks täpse skooringu.
5. Millal peaksid liikuma mitme agendi arhitektuuri juurde?
Vastus: Kui üksik agent kogub liiga palju rolle ja tööriistu: spetsialiseerud (triage, ekspertiis, täitmine) ja orkestreerid üleandmiste kaudu – iga agent muutub taas lihtsaks ja testitavaks.
SDK, guardrails, üleandmised, jälgimine: tellingud on valmis – ülalpool kirjeldatud skaleerimine ütleb sulle, kuidas seda kasutusele võtta, seda nõrgendamata.