Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Skaljar u Arkitetturi Multi-Aġent

Lezzjoni 25 / 25 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Skaljar u Arkitetturi Multi-Aġent
  2. Arkitettura tal-Produzzjoni
  3. Mudelli Multi-Aġent
  4. Ġestjoni tal-Limiti ta’ Rata
  5. Ottimizzazzjoni tal-Ispejjeż fuq Skala
  6. Punti Ewlenin
  7. Ittestja l-Għarfien Tiegħek

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.