Skaljar u Arkitetturi Multi-Aġent
F'din il-paġna
Skaljar u Arkitetturi Multi-Aġent
L-aġent tiegħek jaħdem għal 10 utenti. Kif tagħmlu jaħdem għal 10,000? L-isfidi jinbidlu: m’għadx huwa dwar istruzzjonijiet li jfallu, iżda dwar limiti ta’ rata tal-fornitur, memorja tas-server, u l-kont mensili tiegħek. F’din il-lezzjoni finali, se titgħallem kif tiskalja l-aġenti tiegħek, tiddisinja arkitetturi multi-aġent b’prestazzjoni għolja, u timmaniġġja r-restrizzjonijiet tal-produzzjoni fuq skala kbira.
Arkitettura tal-Produzzjoni
Il-Backend tal-Aġent b’FastAPI
L-ewwel deċiżjoni strutturali tikkonċerna ċ-ċiklu tal-ħajja tal-aġent. Il-bini ta’ Agent għal kull talba jħassar il-ħin u jferrex il-konfigurazzjoni; il-lifespan ta’ FastAPI jippermettilek tistanzjahom darba waqt l-istartup u żżommhom f’reġistru indicizzat skont it-tip. Ir-rotta taqra t-tip mitlub, tirrifjutah b’mod nadif jekk ma jeżistix, imbagħad tittrasmetti r-risposta: run_streamed toħroġ id-deltas hekk kif il-ġenerazzjoni tipproċedi, u tagħmel it-test jidher fuq l-iskrin immedjatament minflok ma tħalli lill-utent iħares lejn spinner ta’ tagħbija għal tmien sekondi.
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")
Ġestjoni tal-Konkorrenza
Il-qsim ta’ oġġetti Agent bejn it-talbiet kollha b’dan il-mod huwa sikur għax kull talba toħloq Runner indipendenti: l-aġent iżomm il-konfigurazzjoni, ir-Runner iżomm l-istat tal-eżekuzzjoni. L-SDK jimmaniġġja l-konkorrenza nativament, u l-ipproċessar ta’ lott ta’ messagi jfisser li tpoġġi l-korutini f’asyncio.gather. Id-dettall ewlieni hawnhekk huwa return_exceptions=True: mingħajru, talba waħda li tfalli tikkanċella l-lott kollu. Bih, tikseb l-iżbalji bħala valuri, tqabbilhom mal-messaġġ oriġinali tagħhom, u tipproċessa d-disgħa u disgħin riżultat validu.
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
Mudelli Multi-Aġent
Mudell tas-Superviżur
Lil hinn minn ċerta skala, aġent wieħed b’ħmistax-il għodda jsir imprevedibbli: l-istruzzjonijiet tiegħu jikbru wisq, u l-għażliet tiegħu jiddeterjoraw. Il-mudell tas-superviżur jaqsam ix-xogħol bejn aġenti speċjalizzati—riċerka, analiżi, kittieb—u jiddelega r-routing lil aġent dedikat permezz ta’ handoff. Kull speċjalista jżomm istruzzjonijiet qosra u mudell adattat għall-kompitu tiegħu: l-analiżi tirrenja mudell tar-raġunar, filwaqt li s-superviżur, li jagħżel biss ir-riċevitur, jaħdem fuq mudell veloċi peress li d-deċiżjoni tiegħu tiddependi fuq ftit kliem.
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
)
Mudell tal-Pipeline
Meta s-sekwenza tkun magħrufa minn qabel, li tħalli lill-mudell jiddeċiedi l-katina hija spiża mhux meħtieġa. Il-mudell tal-pipeline jgħaqqad il-passi fil-kodiċi tiegħek: iġbor, analizza, ikteb. Għalhekk, analiżi kompetittiva tibda b’żewġ ġbir imnedija flimkien—il-web u l-CRM m’għandhomx raġuni jistennew lil xulxin—imbagħad tgħaddi kollox lill-analiżi, li l-output tagħha jgħaqqad mal-kitba. Tikseb fluss ta’ xogħol riproduċibbli, traċċabbli pass pass, li t-tul totali tiegħu huwa dak tal-aktar ġbir bil-mod flimkien maż-żewġ passi li jmiss.
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
Mudell Map-Reduce
It-tielet mudell jindirizza problema ta’ volum aktar milli ta’ kumplessità. Elfew verbatim ta’ klijenti ma joqogħdux f’talba waħda u ma jistgħux jiġu analizzati b’mod sekwenzjali f’ħin raġonevoli. Il-fażi MAP tikklassifika kull feedback b’mod parallel b’mudell veloċi u output ittajpjat; il-fażi REDUCE taggrega dawn il-klassifikazzjonijiet, ferm iktar kompatti mit-testi oriġinali, u tfid is-sinteżi lil mudell aktar kapaċi. L-ispiża tonqos b’mod drastiku meta mqabbla mal-analiżi sħiħa, għax il-biċċa l-kbira tal-volum tiġi pproċessata mill-aktar mudell irħis.
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
Ġestjoni tal-Limiti ta’ Rata
It-tnedija ta’ elfejn sejħa simultanja ma tagħmilhomx jispiċċaw aktar malajr: il-fornitur jirrifjutak u titlef il-lott. Semaphora tillimita n-numru ta’ eżekuzzjonijiet konkurrenti, u l-maniġer hawn taħt iżid backoff esponenzjali limitat għal sittin sekonda meta sseħħ żball ta’ limitu. Il-kontatur tal-iżbalji jiġi rriżettjat hekk kif sejħa tirnexxi, u jevita piena fit-tul għas-servizz għal inċident tranżitorju.
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)
Ottimizzazzjoni tal-Ispejjeż fuq Skala
Imbagħad hemm il-kont. Żewġ lievi jnaqqsuh mingħajr ma jiddeterjoraw is-servizz. L-ewwel waħda hija li ma tħallasx għal mudell tar-raġunar biex iwieġeb “xinhuma l-ħinijiet tal-ftuħ tiegħek”: tabella ta’ lookup timmappja l-livell ta’ kumplessità mal-mudell xieraq, mill-aktar ekonomiku għal mistoqsijiet sempliċi sal-aktar kapaċi għal każijiet kritiċi, b’default għal kull ma mhux ikklassifikat. It-tieni waħda tisfrutta r-ripetizzjoni—fis-sostenn lill-klijenti, l-istess mistoqsijiet jerġgħu jidhru mijiet ta’ drabi kuljum, u cache indicizzat fuq hash tal-messaġġ jirritorna t-tweġiba istantanjament u b’xejn. Irriżerva din il-cache għal mistoqsijiet li t-tweġiba tagħhom ma tiddependix la mill-utent u lanqas mill-ħin: politika ta’ ritorn taċċettaha sewwa cache, status ta’ ordni qatt ma jagħmel hekk.
# 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
Punti Ewlenin
- Ipprekonfigura l-aġenti tiegħek fl-istartup u użahom mill-ġdid bejn it-talbiet
- L-SDK jimmaniġġja l-konkorrenza nativament permezz ta’
asyncio.gather() - Il-mudell tas-superviżur jikkoordina aġenti speċjalizzati permezz ta’ handoffs
- Il-mudell map-reduce jparallelizza l-ipproċessar ta’ volum kbir
- Immaniġġja l-limiti ta’ rata b’semaphora u backoff esponenzjali
- Ottimizza l-ispejjeż bl-għażla tal-mudell skont il-kumplessità u l-caching
Ittestja l-Għarfien Tiegħek
Qabel ma tiskalja, iċċekkja l-għarfien tiegħek dwar l-arkitettura tal-aġenti.
1. Xinhuma l-blokki tal-bini tal-SDK tal-Aġenti?
Tweġiba: Agent (ir-rwol u l-istruzzjonijiet tiegħu), Runner (iċ-ċiklu tal-eżekuzzjoni), Tool (il-kapaċitajiet), u Guardrail (validazzjonijiet tal-input/output)—l-anatomija ta’ kwalunkwe aġent fl-SDK.
2. Għal xiex iservu l-Guardrails?
Tweġiba: Biex jivvalidaw x’jidħol u x’joħroġ mill-aġent: jiffiltraw talbiet barra mill-iskop, jikkontrollaw l-outputs qabel ma jaġixxu—sigurtà ddikjarata fl-arkitettura, mhux mitluba mill-prompt.
3. X'inhu handoff?
Tweġiba: It-trasferiment ta’ konversazzjoni minn aġent għal ieħor, aktar speċjalizzat: orkestrazzjoni multi-aġent fejn kull aġent jagħmel dak li jaf l-aħjar, bil-kuntest isegwi.
4. Għaliex it-traċċar huwa indispensabbli fil-produzzjoni?
Tweġiba: Għax aġent jiddeċiedi b’mod dinamiku: mingħajr traċċi tal-passi, l-għodod imsejħa, u d-deċiżjonijiet, id-debugging jew l-evalwazzjoni huma impossibbli—il-gradwazzjoni tat-traċċar tippunteġġja preċiżament dawn l-eżekuzzjonijiet.
5. Meta għandek timxi lejn arkitettura multi-aġent?
Tweġiba: Meta aġent wieħed jakkumula wisq rwoli u għodod: tispeċjalizza (trijaġġ, esperjenza, eżekuzzjoni) u torganizza permezz ta’ handoffs—kull aġent isir sempliċi u testjabbli mill-ġdid.
SDK, guardrails, handoffs, traċċar: l-impalcatura hija kompluta—l-iskaljar hawn fuq jgħidlek kif tiddispjegaha mingħajr ma ddgħajjifha.