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

Criar agentes especializados e um router

Aula 13 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Da teoria à prática
  2. Passo 1: Criar os agentes especialistas
  3. Passo 2: Criar o agente router
  4. Passo 3: Definir os alvos de transferência
  5. Passo 4: Iniciar a conversa
  6. A alavanca principal: a descrição
  7. Exemplo completo
  8. Pontos-chave

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