Casos de Utilização Multi-Agentes
Nesta página
Do Conceito à Realidade
Agora que compreende as transferências (handoffs), os modos de execução e o encadeamento, esta lição reúne esses blocos de construção em três sistemas completos, cada um baseado numa topologia diferente: uma cadeia de escalonamento, um pipeline e um router. À medida que lê, observe como a arquitetura flui a partir do problema, e não o contrário: a natureza da necessidade dita a forma, não a tecnologia.
Caso 1: Apoio ao Cliente Multinível
As operações de apoio funcionam por níveis: a maioria dos pedidos resolve-se no primeiro contacto, uma minoria requer diagnóstico técnico e um punhado acaba nas mãos de um humano. Esta realidade mapeia-se diretamente numa cadeia de escalonamento, onde cada nível transfere apenas para o seguinte.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Level 1: FAQ and simple questions
level1 = client.beta.agents.create(
model="mistral-medium-latest",
name="support-level1",
description="Level 1 support: FAQ, common questions, basic information.",
instructions="""You are the first level of support.
- Answer simple questions (hours, rates, FAQ)
- If the question is technical or complex, transfer to level 2
- Be polite and professional""",
tools=[{"type": "document_library", "library_ids": ["faq-library-id"]}]
)
# Level 2: Technical support
level2 = client.beta.agents.create(
model="mistral-large-latest",
name="support-level2",
description="Technical support: diagnosis, troubleshooting, configuration.",
instructions="""You are technical support.
- Diagnose technical issues
- Propose step-by-step solutions
- If the problem requires manual intervention, transfer to level 3""",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}]
)
# Level 3: Human escalation (simulation)
level3 = client.beta.agents.create(
model="mistral-large-latest",
name="support-level3",
description="Escalation: critical issues requiring human intervention.",
instructions="""Prepare a summary of the issue for the technical team:
- Problem context
- Diagnostic steps performed
- Solutions attempted
- Recommendation"""
)
# Chain the escalations
level1 = client.beta.agents.update(agent_id=level1.id, handoffs=[level2.id])
level2 = client.beta.agents.update(agent_id=level2.id, handoffs=[level3.id])
Duas decisões destacam-se. O Nível 1 executa no mistral-medium-latest, enquanto os níveis subsequentes usam o mistral-large-latest. O Nível 1 absorve o maior volume; atribuir-lhe o modelo mais caro significaria pagar por competências desnecessárias para perguntas sobre horários de funcionamento. O Nível 3, entretanto, não resolve nada; apenas redige um dossier do caso. É exatamente isso que se espera de um escalonamento humano: o engenheiro que assume a tarefa recebe o contexto, os passos de diagnóstico já realizados e as soluções já tentadas, em vez de reiniciar o interrogatório do zero.
Na prática, um cliente escreve: «Não consigo aceder à minha conta». O Nível 1 consulta as FAQ, não encontra nenhum caso correspondente e transfere. O Nível 2 diagnostica um problema de base de dados fora do seu âmbito e transfere novamente. O Nível 3 prepara o ticket com todo o histórico.
Caso 2: Pipeline de Inteligência Estratégica
Aqui, a ordem é fixa e conhecida antecipadamente: não se pode analisar o que ainda não foi recolhido, nem escrever o que ainda não foi analisado. Uma cadeia linear é, portanto, obrigatória, e o ponto de entrada não é um router, mas sim o primeiro elo.
# Collector — searches for raw information
collector = client.beta.agents.create(
model="mistral-large-latest",
name="intelligence-collector",
description="Collects strategic information via web search.",
instructions="""Search for information on the requested topic.
- Cover multiple sources
- Include numerical data
- Note publication dates""",
tools=[{"type": "web_search"}]
)
# Analyst — extracts insights
analyst = client.beta.agents.create(
model="mistral-large-latest",
name="intelligence-analyst",
description="Analyzes and extracts insights from raw data.",
instructions="""Analyze the collected data:
- Identify trends
- Spot opportunities and threats
- Quantify when possible""",
tools=[{"type": "code_interpreter"}]
)
# Reporter — produces the report
reporter = client.beta.agents.create(
model="mistral-large-latest",
name="intelligence-reporter",
description="Writes structured intelligence reports.",
instructions="""Write a professional intelligence report:
## Executive Summary (3 sentences)
## Key Facts (bullet points)
## Analysis (2-3 paragraphs)
## Recommendations (concrete actions)
## Sources"""
)
# Pipeline
collector = client.beta.agents.update(agent_id=collector.id, handoffs=[analyst.id])
analyst = client.beta.agents.update(agent_id=analyst.id, handoffs=[reporter.id])
# Launch
response = client.beta.conversations.start(
agent_id=collector.id,
inputs="Strategic intelligence: sovereign AI market in Europe, Q1 2026."
)
O esboço do relatório está escrito preto no branco nas instruções do agente repórter, até ao número de frases no resumo executivo. Este nível de precisão é o que torna a inteligência acionável ao longo do tempo: todos os relatórios saem no mesmo formato, permitindo comparações semana a semana e a sua distribuição sem necessidade de edição. Note também a instrução dada ao coletor para registar as datas de publicação; sem ela, um relatório de inteligência pode parecer sólido enquanto se baseia em fontes desatualizadas.
Caso 3: O Assistente Versátil
Quando os pedidos envolvem competências não relacionadas, não há escalonamento nem pipeline; existe roteamento. O router central lê o pedido e envia-o para um dos seus quatro especialistas, nenhum dos quais precisa de saber da existência dos outros.
# Specialists
web_researcher = client.beta.agents.create(
model="mistral-large-latest",
name="web-researcher",
description="Searches for current information on the internet.",
tools=[{"type": "web_search"}]
)
data_analyst = client.beta.agents.create(
model="mistral-large-latest",
name="data-analyst",
description="Data analysis, statistics, and visualizations.",
tools=[{"type": "code_interpreter"}]
)
doc_expert = client.beta.agents.create(
model="mistral-large-latest",
name="doc-expert",
description="Queries and synthesizes internal documents.",
tools=[{"type": "document_library", "library_ids": ["docs-lib-id"]}]
)
creative = client.beta.agents.create(
model="mistral-large-latest",
name="creative-agent",
description="Creates visual content and illustrations.",
tools=[{"type": "image_generation"}]
)
# Central router
assistant = client.beta.agents.create(
model="mistral-large-latest",
name="research-assistant",
description="Versatile research assistant.",
instructions="""You are a research assistant. Analyze each request and transfer to the appropriate specialist:
- Current information → web-researcher
- Calculations and data → data-analyst
- Questions about our documents → doc-expert
- Need for illustrations → creative-agent""",
handoffs=[web_researcher.id, data_analyst.id, doc_expert.id, creative.id]
)
Cada especialista possui exatamente uma ferramenta, e as quatro descrições não se sobrepõem em lado nenhum. Esta ausência de sobreposição é o que torna o roteamento estável: se dois agentes pudessem plausivelmente tratar o mesmo pedido, a escolha variaria de uma execução para outra, e os seus utilizadores experienciariam uma qualidade inconsistente sem compreender o motivo.
O que Distingue um Protótipo de um Sistema
Estes três sistemas partilham a mesma regra de conceção: um agente, uma responsabilidade. Assim que um agente acumula duas funções, as suas instruções contradizem-se e a sua descrição torna-se demasiado vaga para que o router decida corretamente. Escreva, portanto, cada descrição tendo em mente a decisão que esta deve permitir, e redija cada conjunto de instruções para declarar tanto o que o agente não deve fazer como o que deve fazer.
A passagem para produção adiciona quatro requisitos que um protótipo ignora. Primeiro, o registo (logging): o modo cliente permite rastrear cada transferência com os seus próprios identificadores, o que será o seu único recurso no dia em que um utilizador reportar uma resposta aberrante. Segundo, os tempos limite (timeouts), essenciais em cadeias longas onde um elo bloqueado imobiliza o restante. Terceiro, os mecanismos de fallback, porque a pergunta «o que acontece se este agente falhar?» deve ter uma resposta escrita antes da entrada em produção, e não após o primeiro incidente. Por fim, o acompanhamento de custos: uma cadeia de três agentes consome tokens em cada retransmissão, e apenas um contador por conversação lhe dirá se o seu pipeline de inteligência custa alguns cêntimos ou muito mais.
Pontos-chave
- O apoio ao cliente multinível é um caso de utilização natural para transferências (handoffs)
- Os pipelines de inteligência (recolher → analisar → escrever) aproveitam o encadeamento linear
- Os assistentes versáteis utilizam um router central para especialistas
- Em produção: registo, tempos limite, mecanismos de fallback e monitorização de custos são essenciais
- Um agente = uma responsabilidade, com uma descrição precisa para o roteamento