Criar agentes especializados e um router
Nesta página
Da teoria à prática
A lição anterior introduziu o conceito de transferências (handoffs). Agora, vai construir o sistema completo na ordem real de construção: primeiro os especialistas, depois o router, em seguida a ligação entre eles e, finalmente, a conversa que coloca tudo em movimento. Esta ordem não é arbitrária: o router só pode apontar para agentes que já existem.
Passo 1: Criar os agentes especialistas
Cada agente recebe um domínio de especialização preciso e nada mais.
from mistralai.client import Mistral
from mistralai.client.models import CompletionArgs, ResponseFormat, JSONSchema
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Agente de pesquisa web
web_agent = client.beta.agents.create(
model="mistral-large-latest",
name="web-search-agent",
description="Agent that searches for information online.",
instructions="Perform precise web searches. Always cite your sources.",
tools=[{"type": "web_search"}]
)
# Agente financeiro
finance_agent = client.beta.agents.create(
model="mistral-large-latest",
name="finance-agent",
description="Agent specialized in financial questions.",
instructions="""You are a financial expert.
- Use numerical data
- Explain concepts clearly
- Flag risks"""
)
# Agente calculadora
calculator_agent = client.beta.agents.create(
model="mistral-large-latest",
name="calculator-agent",
description="Agent for detailed mathematical calculations.",
instructions="Explain each step of the calculation. Use the code interpreter for complex calculations.",
tools=[{"type": "code_interpreter"}]
)
Estes quatro campos desempenham papéis muito diferentes, e um merece atenção especial. O name em kebab-case é para si: aparece nos seus registos e testes, e um nome legível poupa-o de comparar IDs opacos. As instructions dirigem-se ao modelo assim que este começa a trabalhar, pelo que devem ser específicas do domínio — «sinalizar riscos» significa algo para um agente financeiro, enquanto «ser prestativo» não significa nada para ninguém. As tools seguem o princípio da estrita necessidade: o agente financeiro acima não tem ferramentas porque raciocina sem precisar delas, e dar-lhe ferramentas apenas convidaria a um uso indevido. Por fim, a description não é documentação: é o texto que o router lê para decidir se transfere a tarefa para aqui ou para outro lado.
Passo 2: Criar o agente router
O router não tem ferramentas. Toda a sua função consiste em analisar o pedido e escolher o destinatário.
router_agent = client.beta.agents.create(
model="mistral-large-latest",
name="router-agent",
description="Router agent that distributes requests.",
instructions="""You are an orchestrator.
Analyze each request and transfer to the right agent:
- Questions requiring online data → web-search-agent
- Financial questions → finance-agent
- Calculations and numerical analysis → calculator-agent
Never answer directly—always transfer."""
)
Essa última linha impede que o sistema colapse. Sem ela, um router baseado num modelo grande responderá a perguntas que lhe parecem fáceis, contornará os seus especialistas e produzirá respostas sem as ferramentas que estes teriam utilizado. Acabará com uma arquitetura multi-agente onde metade dos agentes nunca é utilizada.
Passo 3: Definir os alvos de transferência
Agora precisa de dizer ao router para quais agentes lhe é permitido transferir tarefas.
router_agent = client.beta.agents.update(
agent_id=router_agent.id,
handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)
O parâmetro handoffs aceita uma lista de IDs de agentes, e o router pode transferir para qualquer um deles. Isto não é um privilégio reservado ao router: os especialistas também podem declarar os seus próprios alvos.
# O agente financeiro pode transferir para a pesquisa web e para a calculadora
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Uma cadeia como router → financeiro → pesquisa web → calculadora torna-se então possível. Quando o agente financeiro se depara com uma pergunta que exige uma taxa atual, não devolve a tarefa ao router: vai diretamente para o especialista de que precisa, tal como um consultor que chama um colega em vez de voltar à receção.
Passo 4: Iniciar a conversa
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Find the current ECB key interest rate and calculate compound interest over 10 years for €100,000."
)
# Analisar o fluxo
for entry in response.outputs:
if entry.type == "agent.handoff":
print(f"[HANDOFF] → {entry.next_agent_id}")
elif entry.type == "tool.execution":
print(f"[TOOL] {entry.tool_name}")
elif entry.type == "message.output":
print(f"[RESPONSE] {entry.content[:200]}...")
Execute este pedido e observe o rasto antes de olhar para a resposta. Deve ver duas transferências e pelo menos uma execução de ferramenta; se não vir nenhuma, o seu router respondeu por conta própria e é altura de reforçar as suas instruções.
A alavanca principal: a descrição
Quando o roteamento falha, a culpa é quase sempre da descrição. O router não conhece as suas intenções; lê apenas este texto para cada agente candidato.
# Mau — demasiado vago
description="A useful agent."
# Bom — o router sabe quando transferir
description="Agent that searches for current information on the Internet and cites its sources."
Escreva cada descrição como uma resposta à pergunta «em que caso devo chamar este agente?» em vez de como um resumo do que ele é. O segundo exemplo nomeia a situação — informação atual, na Internet — enquanto o primeiro deixa o router a adivinhar. Verifique também se nenhum par de descrições se sobrepõe: dois agentes descritos em termos semelhantes produzirão um roteamento instável de uma execução para a outra.
Exemplo completo
Aqui está a versão condensada, com handoffs passados diretamente durante a criação do router, uma vez que os especialistas já existem nesse momento.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Agentes especialistas
research = client.beta.agents.create(
model="mistral-large-latest",
name="research-agent",
description="Online information search with sources.",
tools=[{"type": "web_search"}]
)
analyst = client.beta.agents.create(
model="mistral-large-latest",
name="analyst-agent",
description="Data analysis and calculations with Python.",
tools=[{"type": "code_interpreter"}]
)
writer = client.beta.agents.create(
model="mistral-large-latest",
name="writer-agent",
description="Drafting structured and professional reports.",
instructions="Write clear reports with an introduction, analysis, and recommendations."
)
# 2. Router com transferências
router = client.beta.agents.create(
model="mistral-large-latest",
name="router",
description="Orchestrates complex requests.",
instructions="Analyze the request and transfer to the appropriate specialist.",
handoffs=[research.id, analyst.id, writer.id]
)
# 3. Lançamento
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analyze the European cloud computing market in 2026: size, players, trends."
)
Pontos-chave
- Crie agentes especialistas com descrições precisas e orientadas para tarefas
- O router utiliza as descrições para escolher o agente alvo
client.beta.agents.update(handoffs=[...])define os alvos de transferência- As transferências podem ser aninhadas (agente A → agente B → agente C)
- A descrição de cada agente é a alavanca principal para a qualidade do roteamento