Razširljivost in arhitekture z več agenti
Na tej strani
Razširljivost in arhitekture z več agenti
Tvoj agent deluje za 10 uporabnikov. Kako ga pripraviti, da bo deloval za 10.000? Izzivi se spremenijo: ne gre več za napake v navodilih, temveč za omejitve hitrosti ponudnika, pomnilnik strežnika in tvoj mesečni račun. V tej zadnji lekciji se boš naučil, kako razširiti svoje agente, zasnovati visoko zmogljive arhitekture z več agenti in upravljati proizvodne omejitve pri velikem obsegu.
Proizvodna arhitektura
Zaledje agenta s FastAPI
Prva strukturna odločitev se nanaša na življenjski cikel agenta. Izgradnja novega Agent za vsako zahtevo zapravlja čas in razprši konfiguracijo; FastAPI-jev lifespan ti omogoča, da jih ustvariš enkrat ob zagonu in jih hraniš v registru, indeksiranem po vrsti. Usmerjevalnik prebere zahtevano vrsto, jo čisto zavrne, če ne obstaja, nato pa pretaka odgovor: run_streamed oddaja delte med generiranjem, kar omogoča takojšen pojav besedila na zaslonu, namesto da bi uporabnik čakal pred vrtečim se krogcem osem sekund.
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 of pre-configured agents
agents_registry = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
# Initialize agents at startup
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")
Upravljanje sočasnosti
Deljenje predmetov Agent med vsemi zahtevami, kot je prikazano zgoraj, je varno, ker vsaka zahteva ustvari neodvisen Runner: agent hrani konfiguracijo, Runner pa stanje izvajanja. SDK samodejno obravnava sočasnost, obdelava paketa sporočil pa pomeni skladiščenje korutin v asyncio.gather. Ključna podrobnost tukaj je return_exceptions=True: brez tega ena sama neuspešna zahteva prekliče celoten paket. Z njim dobiš napake kot vrednosti, jih povežeš z izvirnim sporočilom in obdelaš devetindevetdeset veljavnih rezultatov.
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]):
"""Process multiple requests in 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"Error for '{msg}': {res}")
else:
print(f"'{msg}' -> {res.final_output[:50]}...")
return results
Vzorci z več agenti
Vzorec nadzornika
Onkraj določenega obsega postane en sam agent s petnajstimi orodji nepredvidljiv: njegova navodila nabreknejo, njegove odločitve pa se poslabšajo. Vzorec nadzornika razdeli delo med specializirane agente – raziskovanje, analizo, pisanje – in delegira usmerjanje namenskem agentu prek predaje (handoff). Vsak specialist ohranja kratka navodila in model, prilagojen svoji nalogi: analitični agent podeduje model za sklepanje, medtem ko nadzornik, ki le izbira prejemnika, teče na hitrem modelu, saj njegova odločitev temelji na nekaj besedah.
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
)
Vzorec cevovoda
Ko je zaporedje vnaprej znano, je dopuščanje modelu, da odloči o verigi, nepotreben strošek. Vzorec cevovoda poveže korake v tvoji kodi: zberi, analiziraj, napiši. Konkurenčna analiza se tako začne z dvema hkrati zagnanima zbiranjema – splet in CRM nimata razloga čakati drug na drugega – nato pa se vse posreduje analizi, katere izhod napaja pisanje. Dobiš ponovljivo delovno pot, sledljivo korak za korakom, katere skupno trajanje je enako trajanju najpočasnejšega zbiranja plus dveh naslednjih korakov.
async def competitive_analysis_pipeline(company: str):
# Step 1: Parallel data collection
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}"""
# Step 2: Analysis
analysis = await Runner.run(analysis_agent, f"Analyze this data: {data}")
# Step 3: Report
report = await Runner.run(
writing_agent,
f"Write a competitive analysis report: {analysis.final_output}"
)
return report.final_output
Vzorec Map-Reduce
Tretji vzorec naslavlja problem obsega, ne kompleksnosti. Dva tisoč odzivov strank ne more biti v eni sami zahtevi in jih ni mogoče analizirati zaporedno v razumnem času. Faza MAP vzporedno razvrsti vsako povratno informacijo s hitrim modelom in tipiziranim izhodom; faza REDUCE združi te razvrstitve, ki so veliko bolj kompaktne od izvirnih besedil, in sintezo zaupa zmogljivejšemu modelu. Stroški drastično padejo v primerjavi s popolno analizo, saj večino obsega obdela najcenejši model.
async def analyze_feedbacks(feedbacks: list[str]):
# MAP: analyze each feedback in 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: synthesize results
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
Upravljanje omejitev hitrosti
Zagon dveh tisoč sočasnih klicev jih ne bo hitreje zaključil: ponudnik te bo zavrnil in izgubil boš paket. Semaforski mehanizem omeji število sočasnih izvajanj, spodnji upravitelj pa doda eksponentno zamudo, omejeno na šestdeset sekund, ko pride do napake omejitve. Števec napak se ponastavi takoj, ko klic uspe, s čimer se izogneš dolgoročni kazni storitve zaradi prehodnega incidenta.
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)
Optimizacija stroškov pri velikem obsegu
Tu je še račun. Dva vzvoda ga zmanjšata brez poslabšanja storitve. Prvi je, da ne plačaš modela za sklepanje za odgovor na vprašanje „kakšni so vaši delovni časi”: tabela za iskanje preslika raven kompleksnosti na ustrezen model, od najcenejšega za preprosta vprašanja do najbolj zmogljivega za kritične primere, s privzetim za vse nerazvrščeno. Drugi izkorišča ponavljanje – v podpori strankam se ista vprašanja vračajo stokrat na dan, medpomnilnik, indeksiran s hashem sporočila, pa vrne odgovor takoj in brezplačno. Ta medpomnilnik rezerviraj za vprašanja, katerih odgovor ni odvisen niti od uporabnika niti od časa: politika vračil se dobro predpomni, status naročila pa nikoli.
# Model strategy by complexity
def choose_model(complexity: str) -> str:
models = {
"simple": "gpt-5.6-terra", # Simple questions: cheap
"medium": "gpt-5.6-terra", # Most cases
"complex": "gpt-5.6-terra", # Fast reasoning
"critical": "gpt-5.6-sol", # Critical cases: maximum quality
}
return models.get(complexity, "gpt-5.6-terra")
# Cache for frequent responses
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
Ključne ugotovitve
- Vnaprej konfiguriraj svoje agente ob zagonu in jih ponovno uporabi med zahtevami
- SDK samodejno obravnava sočasnost prek
asyncio.gather() - Vzorec nadzornika usklajuje specializirane agente prek predaj (handoffs)
- Vzorec map-reduce vzporedno obdeluje velike količine podatkov
- Upravljaj omejitve hitrosti s semaforjem in eksponentno zamudo
- Optimiziraj stroške z izbiro modela glede na kompleksnost in predpomnjenjem
Preveri svoje znanje
Preden povečaš obseg, preveri svoje znanje o arhitekturi agentov.
1. Kateri so gradniki SDK Agents?
Odgovor: Agent (vloga in njena navodila), Runner (zanke izvajanja), Tool (zmogljivosti) in Guardrail (validacije vhoda/izhoda) – anatomija katerega koli agenta SDK.
2. Čemu služijo Guardrails?
Odgovor: Za validacijo tega, kar vstopi in izstopi iz agenta: filtriranje zahtev izven obsega, nadzor izhodov pred dejanjem – varnost, deklarirana v arhitekturi, ne upanje v poziv.
3. Kaj je handoff (predaja)?
Odgovor: Prenos pogovora od enega agenta k drugemu, bolj specializiranemu: orkestracija z več agenti, kjer vsak agent dela tisto, kar najbolje zna, kontekst pa sledi.
4. Zakaj je sledenje v proizvodnji nepogrešljivo?
Odgovor: Ker se agent odloča dinamično: brez sledi korakov, poklicanih orodij in odločitev je razhroščevanje ali evalvacija nemogoča – ocenjevanje sledenja natančno oceni ta izvajanja.
5. Kdaj bi moral preiti na arhitekturo z več agenti?
Odgovor: Ko en sam agent nabere preveč vlog in orodij: specializiraš se (trijaža, strokovnost, izvajanje) in orkestriraš prek predaj – vsak agent ponovno postane preprost in testirljiv.
SDK, guardrails, handoffs, sledenje: oder je postavljen – zgornje razširjanje ti pove, kako ga namestiti, ne da bi ga oslabil.