Skalowanie i architektury wieloagentowe
Na tej stronie
Skalowanie i architektury wieloagentowe
Twój agent obsługuje 10 użytkowników. Jak sprawić, by działał dla 10 000? Wyzwania się zmieniają: nie chodzi już o błędne instrukcje, lecz o limity częstotliwości dostawcy, pamięć serwera i miesięczny rachunek. W tej ostatniej lekcji nauczysz się skalować swoje agenty, projektować wydajne architektury wieloagentowe oraz zarządzać ograniczeniami produkcyjnymi na dużą skalę.
Architektura produkcyjna
Backend agenta z FastAPI
Pierwsza decyzja strukturalna dotyczy cyklu życia agenta. Budowanie obiektu Agent dla każdego żądania marnuje czas i rozprasza konfigurację; mechanizm lifespan w FastAPI pozwala utworzyć je raz podczas uruchamiania i przechowywać w rejestrze indeksowanym według typu. Trasa odczytuje żądany typ, odrzuca go poprawnie, jeśli nie istnieje, a następnie strumieniuje odpowiedź: run_streamed emituje delty w miarę postępu generowania, dzięki czemu tekst pojawia się na ekranie natychmiast, zamiast kazać użytkownikowi patrzeć na wirujące kółko ładowania przez osiem 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
# Pula prekonfigurowanych agentów
agents_registry = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
# Inicjalizacja agentów przy starcie
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")
Zarządzanie współbieżnością
Współdzielenie obiektów Agent między wszystkimi żądaniami w ten sposób jest bezpieczne, ponieważ każde żądanie tworzy niezależny obiekt Runner: agent przechowuje konfigurację, a Runner stan wykonania. SDK obsługuje współbieżność natywnie, a przetwarzanie partii wiadomości oznacza układanie korutyn w asyncio.gather. Kluczowym szczegółem jest tutaj return_exceptions=True: bez niego pojedyncze nieudane żądanie anulowałoby całą partię. Dzięki niemu otrzymujesz błędy jako wartości, dopasowujesz je do oryginalnej wiadomości i przetwarzasz dziewięćdziesiąt dziewięć poprawnych wyników.
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]):
"""Przetwarzanie wielu żądań równolegle."""
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"Błąd dla '{msg}': {res}")
else:
print(f"'{msg}' -> {res.final_output[:50]}...")
return results
Wzorce wieloagentowe
Wzorzec nadzorcy
Powyżej pewnej skali pojedynczy agent z piętnastoma narzędziami staje się nieprzewidywalny: jego instrukcje puchną, a jakość wyborów spada. Wzorzec nadzorcy dzieli pracę między wyspecjalizowanych agentów – badanie, analiza, pisanie – i deleguje routing do dedykowanego agenta poprzez handoff. Każdy specjalista utrzymuje krótkie instrukcje i model dopasowany do swojego zadania: analiza dziedziczy model rozumujący, podczas gdy nadzorca, który jedynie wybiera odbiorcę, działa na szybkim modelu, ponieważ jego decyzja zależy od kilku słów.
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", # Szybki do routingu
)
Wzorzec potokowy (Pipeline)
Gdy sekwencja jest znana z góry, pozwalanie modelowi decydować o łańcuchu jest niepotrzebnym wydatkiem. Wzorzec potokowy łączy kroki w kodzie: zbieranie, analiza, pisanie. Analiza konkurencji zaczyna się więc od dwóch równoległych zadań zbierania – sieć i CRM nie mają powodu czekać na siebie – a następnie wszystko trafia do analizy, której wynik zasila moduł pisania. Otrzymujesz powtarzalny przepływ pracy, możliwy do prześledzenia krok po kroku, którego całkowity czas trwania równa się czasowi najwolniejszego zbierania plus dwa kolejne kroki.
async def competitive_analysis_pipeline(company: str):
# Krok 1: Równoległe zbieranie danych
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}"""
# Krok 2: Analiza
analysis = await Runner.run(analysis_agent, f"Analyze this data: {data}")
# Krok 3: Raport
report = await Runner.run(
writing_agent,
f"Write a competitive analysis report: {analysis.final_output}"
)
return report.final_output
Wzorzec Map-Reduce
Trzeci wzorzec rozwiązuje problem objętości, a nie złożoności. Dwa tysiące wypowiedzi klientów nie zmieści się w pojedynczym żądaniu i nie da się ich przeanalizować sekwencyjnie w rozsądnym czasie. Faza MAP klasyfikuje każdą opinię równolegle przy użyciu szybkiego modelu i typowanego wyjścia; faza REDUCE agreguje te klasyfikacje, znacznie bardziej zwięzłe niż oryginalne teksty, i powierza syntezę bardziej wydajnemu modelowi. Koszt drastycznie spada w porównaniu do pełnej analizy, ponieważ większość objętości jest przetwarzana przez najtańszy model.
async def analyze_feedbacks(feedbacks: list[str]):
# MAP: analiza każdej opinii równolegle
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: synteza wyników
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
Zarządzanie limitami częstotliwości (Rate Limits)
Uruchomienie dwóch tysięcy jednoczesnych wywołań nie sprawi, że zakończą się one szybciej: dostawca cię odrzuci i stracisz całą partię. Semafory ograniczają liczbę równoczesnych wykonań, a poniższy menedżer dodaje wykładnicze opóźnienie (exponential backoff) z cappedem na sześćdziesiąt sekund w przypadku błędu limitu. Licznik błędów resetuje się natychmiast po udanym wywołaniu, unikając długoterminowej kary dla usługi za incydent przejściowy.
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)
Optymalizacja kosztów na dużą skalę
Jest jeszcze rachunek. Dwa mechanizmy pozwalają go zmniejszyć bez degradacji usługi. Pierwszy to niepłacenie modelowi rozumującemu za odpowiedź na pytanie „jakie macie godziny otwarcia“: tabela wyszukiwania mapuje poziom złożoności na odpowiedni model, od najbardziej ekonomicznego dla prostych pytań po najbardziej wydajny dla przypadków krytycznych, z wartością domyślną dla wszystkiego niesklasyfikowanego. Drugi wykorzystuje powtarzalność – w obsłudze klienta te same pytania wracają setki razy dziennie, a pamięć podręczna (cache) indeksowana hashem wiadomości zwraca odpowiedź natychmiast i za darmo. Zarezerwuj tę pamięć podręczną dla pytań, których odpowiedź nie zależy ani od użytkownika, ani od czasu: polityka zwrotów cache’uje się dobrze, status zamówienia – nigdy.
# Strategia modelu w zależności od złożoności
def choose_model(complexity: str) -> str:
models = {
"simple": "gpt-5.6-terra", # Proste pytania: tanie
"medium": "gpt-5.6-terra", # Większość przypadków
"complex": "gpt-5.6-terra", # Szybkie rozumowanie
"critical": "gpt-5.6-sol", # Przypadki krytyczne: maksymalna jakość
}
return models.get(complexity, "gpt-5.6-terra")
# Cache dla częstych odpowiedzi
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
Kluczowe wnioski
- Prekonfiguruj swoje agenty przy starcie i wykorzystuj je ponownie między żądaniami
- SDK obsługuje współbieżność natywnie poprzez
asyncio.gather() - Wzorzec nadzorcy koordynuje wyspecjalizowanych agentów poprzez handoffy
- Wzorzec map-reduce równolegli przetwarzanie dużych wolumenów
- Zarządzaj limitami częstotliwości za pomocą semafora i wykładniczego opóźnienia
- Optymalizuj koszty poprzez dobór modelu według złożoności i cache’owanie
Sprawdź swoją wiedzę
Zanim przejdziesz do skalowania, sprawdź swoją wiedzę na temat architektury agentów.
1. Jakie są podstawowe elementy budulcowe Agents SDK?
Odpowiedź: Agent (rola i jej instrukcje), Runner (pętla wykonania), Tool (możliwości) oraz Guardrail (walidacje wejścia/wyjścia) – anatomia każdego agenta w SDK.
2. Do czego służą Guardrails?
Odpowiedź: Do walidacji tego, co wchodzi i wychodzi z agenta: filtrowanie żądań spoza zakresu, kontrola wyników przed ich wykonaniem – bezpieczeństwo zadeklarowane w architekturze, a nie tylko oczekiwane od promptu.
3. Czym jest handoff?
Odpowiedź: Przekazanie konwersacji od jednego agenta do drugiego, bardziej wyspecjalizowanego: orkiestracja wieloagentowa, w której każdy agent robi to, co potrafi najlepiej, z zachowaniem kontekstu.
4. Dlaczego śledzenie (tracing) jest niezbędne w produkcji?
Odpowiedź: Ponieważ agent podejmuje decyzje dynamicznie: bez śladów kroków, wywołanych narzędzi i decyzji debugowanie lub ewaluacja są niemożliwe – ocena śladów precyzyjnie punktuję te wykonania.
5. Kiedy należy przejść na architekturę wieloagentową?
Odpowiedź: Gdy pojedynczy agent gromadzi zbyt wiele ról i narzędzi: specjalizujesz (triage, eksperckość, wykonanie) i orkiestrujesz poprzez handoffy – każdy agent znów staje się prosty i łatwy do przetestowania.
SDK, guardrails, handoffy, tracing: rusztowanie jest kompletne – powyższe wskazówki dotyczące skalowania mówią ci, jak je wdrożyć bez osłabiania.