Dimensionamento e Arquiteturas Multi-Agentes
Nesta página
Dimensionamento e Arquiteturas Multi-Agentes
O seu agente funciona para 10 utilizadores. Como fazê-lo funcionar para 10.000? Os desafios mudam: já não se trata de instruções que falham, mas de limites de taxa do fornecedor, memória do servidor e da sua fatura mensal. Nesta última lição, irá aprender como dimensionar os seus agentes, conceber arquiteturas multi-agentes de alto desempenho e gerir restrições de produção em larga escala.
Arquitetura de Produção
O Backend do Agente com FastAPI
A primeira decisão estrutural diz respeito ao ciclo de vida do agente. Criar um Agent para cada pedido desperdiça tempo e dispersa a configuração; o lifespan do FastAPI permite instanciá-los uma única vez no arranque e mantê-los num registo indexado por tipo. A rota lê o tipo solicitado, rejeita-o limpa e claramente se não existir e, em seguida, transmite a resposta: run_streamed emite deltas à medida que a geração avança, fazendo o texto aparecer no ecrã imediatamente, em vez de deixar o utilizador a olhar para um indicador de carregamento durante oito segundos.
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 de agentes pré-configurados
agents_registry = {}
@asynccontextmanager
async def lifespan(app: FastAPI):
# Inicializar agentes no arranque
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")
Gestão de Concorrência
Partilhar objetos Agent entre todos os pedidos desta forma é seguro porque cada pedido cria um Runner independente: o agente detém a configuração, o Runner detém o estado de execução. O SDK gere a concorrência nativamente e processar um lote de mensagens significa empilhar corrotinas em asyncio.gather. O detalhe chave aqui é return_exceptions=True: sem ele, um único pedido falhado cancela todo o lote. Com ele, obtém erros como valores, associa-os à sua mensagem original e processa os noventa e nove resultados válidos.
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]):
"""Processar múltiplos pedidos em paralelo."""
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
Padrões Multi-Agentes
Padrão Supervisor
Além de uma certa escala, um único agente com quinze ferramentas torna-se imprevisível: as suas instruções incham, as suas escolhas degradam-se. O padrão supervisor divide o trabalho entre agentes especializados — pesquisa, análise, escrita — e delega o encaminhamento a um agente dedicado através de uma transferência (handoff). Cada especialista mantém instruções curtas e um modelo adequado à sua tarefa: a análise herda um modelo de raciocínio, enquanto o supervisor, que apenas escolhe um destinatário, corre num modelo rápido, uma vez que a sua decisão depende de poucas palavras.
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", # Rápido para encaminhamento
)
Padrão Pipeline
Quando a sequência é conhecida antecipadamente, deixar um modelo decidir a cadeia é uma despesa desnecessária. O padrão pipeline liga os passos no seu código: recolher, analisar, escrever. Uma análise competitiva começa assim com duas recolhas lançadas em conjunto — a web e o CRM não têm razão para esperar um pelo outro — passando depois tudo para a análise, cujo resultado alimenta a escrita. Obtém um fluxo de trabalho reproduzível, rastreável passo a passo, cuja duração total é a da recolha mais lenta mais os dois passos seguintes.
async def competitive_analysis_pipeline(company: str):
# Passo 1: Recolha de dados em paralelo
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}"""
# Passo 2: Análise
analysis = await Runner.run(analysis_agent, f"Analyze this data: {data}")
# Passo 3: Relatório
report = await Runner.run(
writing_agent,
f"Write a competitive analysis report: {analysis.final_output}"
)
return report.final_output
Padrão Map-Reduce
O terceiro padrão aborda um problema de volume e não de complexidade. Dois mil verbatims de clientes não cabem num único pedido e não podem ser analisados sequencialmente num tempo razoável. A fase MAP classifica cada feedback em paralelo com um modelo rápido e saída tipada; a fase REDUCE agrega estas classificações, muito mais compactas do que os textos originais, e confia a síntese a um modelo mais capaz. O custo colapsa em comparação com a análise completa, porque a maior parte do volume é processada pelo modelo mais barato.
async def analyze_feedbacks(feedbacks: list[str]):
# MAP: analisar cada feedback em paralelo
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: sintetizar resultados
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
Gestão de Limites de Taxa
Lançar duas mil chamadas simultâneas não as faz terminar mais rápido: o fornecedor recusa-o e perde o lote. Um semáforo limita o número de execuções concorrentes e o gestor abaixo adiciona um recuo exponencial limitado a sessenta segundos quando ocorre um erro de limite. O contador de erros repõe-se assim que uma chamada tem sucesso, evitando uma penalização a longo prazo do serviço por um incidente transitório.
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)
Otimização de Custos em Larga Escala
Depois há a fatura. Duas alavancas reduzem-na sem degradar o serviço. A primeira é não pagar por um modelo de raciocínio para responder a «quais são os vossos horários»: uma tabela de pesquisa mapeia o nível de complexidade ao modelo adequado, desde o mais económico para perguntas simples até ao mais capaz para casos críticos, com um padrão para qualquer coisa não classificada. A segunda explora a repetição — no apoio ao cliente, as mesmas perguntas retornam centenas de vezes por dia, e uma cache indexada num hash da mensagem devolve a resposta instantaneamente e gratuitamente. Reserve esta cache para perguntas cuja resposta não dependa nem do utilizador nem do tempo: uma política de devoluções coloca-se bem em cache, um estado de encomenda nunca o fará.
# Estratégia de modelo por complexidade
def choose_model(complexity: str) -> str:
models = {
"simple": "gpt-5.6-terra", # Perguntas simples: barato
"medium": "gpt-5.6-terra", # Maioria dos casos
"complex": "gpt-5.6-terra", # Raciocínio rápido
"critical": "gpt-5.6-sol", # Casos críticos: qualidade máxima
}
return models.get(complexity, "gpt-5.6-terra")
# Cache para respostas frequentes
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
Pontos-chave
- Pré-configure os seus agentes no arranque e reutilize-os entre pedidos
- O SDK gere a concorrência nativamente via
asyncio.gather() - O padrão supervisor coordena agentes especializados através de transferências (handoffs)
- O padrão map-reduce paraleliza o processamento de grandes volumes
- Gere os limites de taxa com um semáforo e recuo exponencial
- Otimize custos com seleção de modelo por complexidade e caching
Teste os Seus Conhecimentos
Antes de escalar, verifique o seu conhecimento sobre a arquitetura de agentes.
1. Quais são os blocos de construção do SDK Agents?
Resposta: Agent (a função e as suas instruções), Runner (o ciclo de execução), Tool (as capacidades) e Guardrail (validações de entrada/saída) — a anatomia de qualquer agente do SDK.
2. Para que servem os Guardrails?
Resposta: Para validar o que entra e sai do agente: filtrar pedidos fora do âmbito, controlar saídas antes de atuarem — segurança declarada na arquitetura, não esperada apenas do prompt.
3. O que é um handoff?
Resposta: A transferência de uma conversa de um agente para outro, mais especializado: orquestração multi-agente onde cada agente faz o que sabe fazer melhor, com o contexto a acompanhar.
4. Porque é o tracing indispensável em produção?
Resposta: Porque um agente decide dinamicamente: sem registos dos passos, ferramentas chamadas e decisões, a depuração ou avaliação é impossível — a classificação de traços pontua precisamente estas execuções.
5. Quando deve mudar para uma arquitetura multi-agente?
Resposta: Quando um único agente acumula demasiadas funções e ferramentas: especializa-se (triagem, perícia, execução) e orquestra via handoffs — cada agente torna-se novamente simples e testável.
SDK, guardrails, handoffs, tracing: a estrutura está completa — o dimensionamento acima diz-lhe como implementá-la sem a enfraquecer.