Мащабиране и многоагентни архитектури
На тази страница
Мащабиране и многоагентни архитектури
Вашият агент работи за 10 потребители. Как да го накарате да работи за 10 000? Предизвикателствата се променят: вече не става въпрос за неуспешни инструкции, а за лимити на заявките от доставчика, паметта на сървъра и месечната Ви сметка. В този последен урок ще научите как да мащабирате агентите си, да проектирате високопроизводителни многоагентни архитектури и да управлявате производствените ограничения при големи обеми.
Производствена архитектура
Бекенд на агента с FastAPI
Първото структурно решение засяга жизнения цикъл на агента. Създаването на нов Agent за всяка заявка губи време и разпръсква конфигурацията; функцията lifespan на FastAPI Ви позволява да ги инстанцирате веднъж при стартиране и да ги поддържате в регистър, индексиран по тип. Рутът прочита искания тип, го отхвърля чисто, ако не съществува, и след това предава отговора в поток: run_streamed излъчва делти, докато генерирането продължава, карайки текста да се появява на екрана незабавно, вместо да оставя потребителя да гледа въртящ се индикатор за зареждане в продължение на осем секунди.
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")
Управление на конкурентността
Споделянето на обекти Agent между всички заявки по този начин е безопасно, защото всяка заявка създава независим Runner: агентът съдържа конфигурацията, а Runner държи състоянието на изпълнение. SDK обработва конкурентността нативно, а обработката на пакет от съобщения означава натрупване на корутини в asyncio.gather. Ключовият детайл тук е return_exceptions=True: без него една единствена неуспешна заявка анулира целия пакет. С него получавате грешките като стойности, съпоставяте ги с оригиналното им съобщение и обработвате деветдесет и деветте валидни резултата.
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
Многоагентни шаблони
Шаблон „Надзорник“ (Supervisor)
Отвъд определен мащаб един единствен агент с петнадесет инструмента става непредсказуем: инструкциите му се раздуват, а изборите му се влошават. Шаблонът „надзорник“ разделя работата между специализирани агенти – проучване, анализ, писане – и делегира насочването на специален агент чрез предаване (handoff). Всеки специалист запазва кратки инструкции и модел, подходящ за задачата му: анализът наследява модел за разсъждения, докато надзорникът, който само избира получател, работи на бърз модел, тъй като решението му зависи от няколко думи.
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
)
Шаблон „Тръбопровод“ (Pipeline)
Когато последователността е известна предварително, оставянето на модел да решава веригата е ненужен разход. Шаблонът „тръбопровод“ свързва стъпките във Вашия код: събиране, анализ, писане. Един конкурентен анализ така започва с две едновременно стартирани събирания – уеб и CRM нямат причина да чакат един друг – след което всичко се предава на анализа, чийто изход захранва писането. Получавате възпроизводим работен поток, проследим стъпка по стъпка, чиято обща продължителност е тази на най-бавното събиране плюс двете следващи стъпки.
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
Шаблон „Map-Reduce“
Третият шаблон адресира проблем с обема, а не със сложността. Две хиляди клиентски отзиви не се побират в една единствена заявка и не могат да бъдат анализирани последователно за разумно време. Фазата MAP класифицира всеки отзив паралелно с бърз модел и типизиран изход; фазата REDUCE агрегира тези класификации, които са много по-компактни от оригиналните текстове, и възлага синтеза на по-способен модел. Разходите се сриват в сравнение с пълния анализ, защото основната част от обема се обработва от най-евтиния модел.
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
Управление на лимитите на заявките
Стартирането на две хиляди едновременни повиквания не ги кара да приключат по-бързо: доставчикът Ви отказва и губите целия пакет. Семафор ограничава броя на едновременните изпълнения, а мениджърът по-долу добавя експоненциално забавяне (exponential backoff), ограничено до шестдесет секунди, когато възникне грешка поради лимит. Броячът на грешките се нулира веднага щом едно повикване успее, избягвайки дългосрочно наказание за услугата поради преходен инцидент.
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)
Оптимизация на разходите в мащаб
След това идва сметката. Два лоста я намаляват без влошаване на услугата. Първият е да не плащате за модел за разсъждения, за да отговори на „какви са работните Ви часове“: таблица за търсене картографира нивото на сложност към подходящия модел, от най-икономичния за прости въпроси до най-способния за критични случаи, с подразбираща се стойност за всичко некласифицирано. Вторият използва повторението – в поддръжката на клиенти едни и същи въпроси се връщат стотици пъти на ден, а кеш, индексиран чрез хеш на съобщението, връща отговора мигновено и безплатно. Запазете този кеш за въпроси, чийто отговор не зависи нито от потребителя, нито от времето: политиката за връщане се кешира добре, статусът на поръчка – никога.
# 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
Ключови изводи
- Предеконирирайте агентите си при стартиране и ги преизползвайте между заявките
- SDK обработва конкурентността нативно чрез
asyncio.gather() - Шаблонът „надзорник“ координира специализирани агенти чрез предавания (handoffs)
- Шаблонът „map-reduce“ паралелизира обработката на големи обеми
- Управлявайте лимитите на заявките със семафор и експоненциално забавяне
- Оптимизирайте разходите чрез избор на модел според сложността и кеширане
Проверете знанията си
Преди да мащабирате, проверете знанията си за архитектурата на агентите.
1. Кои са основните градивни елементи на Agents SDK?
Отговор: Agent (ролята и нейните инструкции), Runner (цикълът на изпълнение), Tool (възможностите) и Guardrail (валидации на входа/изхода) – анатомията на всеки агент в SDK.
2. За какво служат Guardrails?
Отговор: За валидиране на това, което влиза и излиза от агента: филтриране на заявки извън обхвата, контрол на изходите, преди те да действат – сигурност, декларирана в архитектурата, а не оставена на надеждата от промпта.
3. Какво е handoff (предаване)?
Отговор: Прехвърляне на разговора от един агент към друг, по-специализиран: многоагентна оркестрация, при която всеки агент прави това, което знае най-добре, с последващ контекст.
4. Защо проследяването (tracing) е незаменимо в производствена среда?
Отговор: Защото агентът взема решения динамично: без следи от стъпки, извикани инструменти и решения, отстраняването на грешки или оценяването е невъзможно – оценяването на проследяването точно оценява тези изпълнения.
5. Кога трябва да преминете към многоагентна архитектура?
Отговор: Когато един единствен агент натрупа твърде много роли и инструменти: Вие специализирате (триаж, експертиза, изпълнение) и оркестрирате чрез handoffs – всеки агент отново става прост и лесен за тестване.
SDK, guardrails, handoffs, tracing: скелетът е завършен – мащабирането по-горе Ви казва как да го разположите, без да го отслабвате.