Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Dimensionamento e Arquiteturas Multi-Agentes

Aula 25 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Dimensionamento e Arquiteturas Multi-Agentes
  2. Arquitetura de Produção
  3. Padrões Multi-Agentes
  4. Gestão de Limites de Taxa
  5. Otimização de Custos em Larga Escala
  6. Pontos-chave
  7. Teste os Seus Conhecimentos

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.