Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Mjerilo i arhitekture s više agenata

Lekcija 25 od 25 Ažurirano 29. srpnja 2026. Programer
Na ovoj stranici
  1. Mjerilo i arhitekture s više agenata
  2. Produkcijska arhitektura
  3. Obrasci s više agenata
  4. Upravljanje ograničenjima stope (Rate Limits)
  5. Optimizacija troškova u velikom mjerilu
  6. Ključne točke
  7. Provjeri svoje znanje

Mjerilo i arhitekture s više agenata

Tvoj agent radi za 10 korisnika. Kako ga natjerati da radi za 10 000? Izazovi se mijenjaju: više nije riječ o tome da upute ne uspijevaju, već o ograničenjima stope pružatelja usluga, memoriji poslužitelja i tvojem mjesečnom računu. U ovoj završnoj lekciji naučit ćeš kako skalirati svoje agente, dizajnirati visokoučinkovite arhitekture s više agenata i upravljati produkcijskim ograničenjima u velikom mjerilu.

Produkcijska arhitektura

Agentski pozadinski sustav s FastAPI-jem

Prva strukturna odluka tiče se životnog ciklusa agenta. Izgradnja instance Agent za svaki zahtjev gubi vrijeme i raspršuje konfiguraciju; FastAPI-jev lifespan omogućuje ti da ih instanciraš jednom pri pokretanju i zadržiš u registru indeksiranom po vrsti. Ruta očituje traženu vrstu, uredno je odbija ako ne postoji, a zatim strimira odgovor: run_streamed emitira delte kako generiranje napreduje, čineći da se tekst pojavljuje na zaslonu odmah umjesto da korisnik gleda u ikonu učitavanja osam sekundi.

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 istovremenošću

Dijeljenje objekata Agent između svih zahtjeva na ovaj način sigurno je jer svaki zahtjev stvara neovisnog Runnera: agent drži konfiguraciju, a Runner drži stanje izvršavanja. SDK nativno rukuje istovremenošću, a obrada serije poruka znači slaganje korutina u asyncio.gather. Ključni detalj ovdje je return_exceptions=True: bez njega, jedan neuspjeli zahtjev poništava cijelu seriju. S njim dobivaš pogreške kao vrijednosti, povezuješ ih s izvornom porukom i obrađuješ devedeset i devet valjanih rezultata.

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

Obrasci s više agenata

Obrazac nadzornika

Iznad određenog mjerila, jedan agent s petnaest alata postaje nepredvidiv: njegove upute nabubre, a izbori se pogoršavaju. Obrazac nadzornika dijeli posao između specijaliziranih agenata – istraživanje, analiza, pisanje – i delegira usmjeravanje namjenskom agentu putem predaje (handoff). Svaki specijalist zadržava kratke upute i model prilagođen svom zadatku: analiza nasljeđuje model za rezoniranje, dok nadzornik, koji samo bira primatelja, radi na brzom modelu jer njegova odluka ovisi o nekoliko riječi.

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
)

Obrazac cjevovoda (Pipeline)

Kada je slijed unaprijed poznat, dopuštanje modelu da odluči o lancu nepotreban je trošak. Obrazac cjevovoda povezuje korake u tvom kodu: prikupi, analiziraj, napiši. Konkurentska analiza tako započinje s dva istovremeno pokrenuta prikupljanja – web i CRM nemaju razloga čekati jedno drugo – zatim sve prosljeđuje analizi, čiji izlaz napaja pisanje. Dobivaš reproducibilan radni tijek, korak po korak sljediv, čije je ukupno trajanje jednako trajanju najsporijeg prikupljanja plus dva sljedeća koraka.

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

Obrazac Map-Reduce

Treći obrazac rješava problem volumena, a ne složenosti. Dvije tisuće izravnih izjava kupaca ne stane u jedan zahtjev i ne mogu se analizirati sekvencijalno u razumnom vremenu. Faza MAP paralelno klasificira svaku povratnu informaciju brzim modelom i tipiziranim izlazom; faza REDUCE agregira te klasifikacije, koje su puno kompaktnije od izvornih tekstova, i povjerava sintezu sposobnijem modelu. Trošak drastično pada u usporedbi s potpunom analizom jer se većina volumena obrađuje najjeftinijim modelom.

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 ograničenjima stope (Rate Limits)

Pokretanje dvije tisuće istovremenih poziva ne znači da će brže završiti: pružatelj te odbija i gubiš seriju. Semaforski mehanizam ograničava broj istovremenih izvršavanja, a donji upravitelj dodaje eksponencijalno kašnjenje (backoff) s maksimumom od šezdeset sekundi kada dođe do pogreške ograničenja. Brojač pogrešaka resetira se čim poziv uspije, izbjegavajući dugoročnu kaznu za uslugu zbog prolaznog 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 troškova u velikom mjerilu

Tu je i račun. Dvije poluge smanjuju ga bez degradacije usluge. Prva je da ne plaćaš model za rezoniranje da odgovori na „koje je vaše radno vrijeme“: tablica pretraživanja mapira razinu složenosti na prikladan model, od najekonomičnijeg za jednostavna pitanja do najsposobnijeg za kritične slučajeve, s zadanim za sve neklasificirano. Druga iskorištava ponavljanje – u korisničkoj podršci ista se pitanja vraćaju stotinama puta dnevno, a predmemorija (cache) indeksirana hashom poruke vraća odgovor trenutno i besplatno. Rezerviraj ovu predmemoriju za pitanja čiji odgovor ne ovisi ni o korisniku ni o vremenu: politika povrata dobro se kešira, status narudžbe nikada.

# 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 točke

  • Unaprijed konfiguriraj svoje agente pri pokretanju i ponovno ih koristi kroz zahtjeve
  • SDK nativno rukuje istovremenošću putem asyncio.gather()
  • Obrazac nadzornika koordinira specijalizirane agente putem predaja (handoffs)
  • Obrazac map-reduce paralelizira obradu velikog volumena
  • Upravljaj ograničenjima stope pomoću semafora i eksponencijalnog kašnjenja
  • Optimiziraj troškove odabirom modela prema složenosti i predmemoriranjem

Provjeri svoje znanje

Prije povećanja mjerila, provjeri svoje znanje o arhitekturi agenata.

1. Koji su gradivni blokovi Agents SDK-a?

Odgovor: Agent (uloga i njezine upute), Runner (petlja izvršavanja), Tool (mogućnosti) i Guardrail (validacije ulaza/izlaza) – anatomija svakog SDK agenta.

2. Čemu služe Guardrails?

Odgovor: Za validaciju onoga što ulazi i izlazi iz agenta: filtriranje zahtjeva izvan opsega, kontrola izlaza prije nego što djeluju – sigurnost deklarirana u arhitekturi, a ne samo poželjna u promptu.

3. Što je handoff (predaja)?

Odgovor: Prijenos razgovora s jednog agenta na drugog, specijaliziranijeg: orchestracija s više agenata gdje svaki agent radi ono što najbolje zna, uz praćenje konteksta.

4. Zašto je praćenje (tracing) neophodno u produkciji?

Odgovor: Zato što agent dinamički odlučuje: bez tragova koraka, pozvanih alata i odluka, otklanjanje pogrešaka ili evaluacija su nemogući – ocjenjivanje tragova precizno boduje ova izvršavanja.

5. Kada trebaš prijeći na arhitekturu s više agenata?

Odgovor: Kada jedan agent akumulira previše uloga i alata: specijaliziraš (trijaža, ekspertiza, izvršenje) i orchestriraš putem handoffova – svaki agent ponovno postaje jednostavan i testabilan.

SDK, guardrails, handoffs, tracing: skela je dovršena – gornje skaliranje govori ti kako je rasporediti bez slabljenja.