Execução no Servidor vs. no Cliente
Nesta página
Lição atualizada em 3 de novembro de 2026 com base no SDK
mistralai3.7.0 e na documentação Handoffs da Mistral: uma entradaagent.handoffidentifica o agente de destino através denext_agent_id(e nãoto_agent), econversations.appendnão aceita o parâmetroagent_id—códigos mais antigos falhariam. A retomada pelo agente de destino ocorre aqui numa nova conversa, à qual transmite o contexto. Fontes: Handoffs · client-python.
Duas Formas de Gerir Transferências
Quando um agente transfere o controlo para outro, a API Mistral oferece dois modos de execução: servidor (automático) e cliente (manual). A definição resume-se a uma palavra, mas determina quem conduz efetivamente o fluxo de trabalho. No modo servidor, delega toda a coreografia à Mistral e recebe o resultado. No modo cliente, recupera o controlo entre cada etapa. Todo o resto—os agentes, as suas ferramentas, os seus alvos de transferência—permanece exatamente igual.
Modo Servidor, o Padrão
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze and calculate market trends.",
handoff_execution="server" # Default — can be omitted
)
O fluxo é totalmente gerido: o router recebe o pedido, decide transferir para o agente de pesquisa e a Mistral executa a transferência; o agente de pesquisa realiza o seu trabalho e transfere depois para a calculadora, e a Mistral executa também essa etapa; a calculadora produz o resultado. Recebe a resposta final, acompanhada de todos os resultados intermédios—vê, portanto, o que aconteceu, mas a posteriori.
Este modo possui três qualidades que explicam por que é o padrão. É simples, pois não escreve qualquer lógica de controlo do seu lado. É rápido, porque toda a cadeia executa na Mistral sem idas e voltas de rede em cada retransmissão. É fiável, já que o tratamento de erros e os tempos limite entre agentes são geridos por si.
As suas limitações são o exato contraponto. Não tem controlo intermédio: é impossível validar ou modificar uma transferência enquanto esta ocorre. O custo é opaco, no sentido de que todos os agentes da cadeia executam sem que possa interromper, a meio do fluxo, um pedido que se dirige numa direção desnecessária. E não pode inserir qualquer lógica personalizada entre as etapas—sem registo detalhado, sem validação, sem decisões de negócio.
Modo Cliente, Quando Quer Controlo
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze the cloud market.",
handoff_execution="client"
)
O router recebe o pedido e decide transferir, exatamente como antes. Mas, em vez de a transferência ser executada, recebe um evento agent.handoff e a cadeia para aí. Cabe-lhe a si reiniciá-la chamando o agente de destino—o que lhe deixa a latitude para validar, registar, enriquecer o contexto ou simplesmente recusar.
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Search for the latest tech news.",
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target_agent_id = entry.next_agent_id
print(f"Handoff requested to: {target_agent_id}")
# Validate, then hand over to the target agent, with useful context
next_response = client.beta.conversations.start(
agent_id=target_agent_id,
inputs="Search for the latest tech news.",
)
# Process the target agent's response
for next_entry in next_response.outputs:
print(f"{next_entry.type}: {next_entry.content}")
Um ponto merece atenção: a documentação da Mistral descreve o modo client—o controlo regressa a si no momento da transferência—mas não fornece nenhum método para fazer o agente de destino retomar a mesma conversa, e conversations.append não aceita o parâmetro agent_id. O exemplo inicia, portanto, uma conversa com o agente de destino, ao qual transmite explicitamente o que ele necessita: o pedido original e, se aplicável, um resumo do que já foi feito. Esta é também uma oportunidade para transmitir apenas o que ele deve ver.
O fragmento acima trata apenas de um único retransmissor. Uma cadeia real liga vários, o que exige um ciclo.
def execute_with_control(router_id, query):
"""Executes a multi-agent workflow with control at each step."""
response = client.beta.conversations.start(
agent_id=router_id,
inputs=query,
handoff_execution="client"
)
conversation_id = response.conversation_id
results = []
while True:
handoff_found = False
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_found = True
target = entry.next_agent_id
print(f"[LOG] Handoff to {target}")
# Here you can add: validation, logging, metrics
response = client.beta.conversations.start(
agent_id=target,
inputs=query, # the original request, enriched if needed
handoff_execution="client",
)
conversation_id = response.conversation_id
break
elif entry.type == "message.output":
results.append(entry.content)
if not handoff_found:
break
return results
A estrutura assemelha-se a uma bomba: enquanto surgir uma transferência nos resultados, processa-a e reinicia; assim que uma iteração do ciclo não encontrar nenhuma, a cadeia terminou e sai com as mensagens acumuladas. O comentário no meio marca a localização que justifica todo este modo: é aí, e apenas aí, que o seu código se interpõe entre dois agentes.
Escolher Entre os Dois
O modo servidor cobre a produção padrão. Se o seu fluxo de trabalho for previsível, se confiar nos agentes que escreveu ou se estiver a criar protótipos e quiser ver resultados rapidamente, a automação total é a escolha certa—e escrever um ciclo de controlo seria esforço desperdiçado.
O modo cliente justifica-se assim que um requisito externo entra na cadeia. Validação humana, quando um operador deve aprovar uma transferência para um agente que desencadeia ações sensíveis. Necessidade de registo e auditoria, quando a conformidade exige rastrear cada etapa com os seus próprios identificadores e os seus próprios carimbos de tempo. Roteamento condicional, quando a decisão depende de regras de negócio que o modelo não pode conhecer—estado do cliente, hora do dia, uma quota. Um limite, ou limitação de taxa, quando quer restringir o número de agentes executados para um pedido. Uma estratégia de fallback, finalmente, quando a falha de um agente deve desencadear algo diferente de um erro apresentado ao utilizador.
Eis o aspeto da primeira destas situações, reduzida à sua estrutura essencial.
def workflow_with_validation(router_id, query):
response = client.beta.conversations.start(
agent_id=router_id,
inputs=query,
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target = entry.next_agent_id
approval = input(f"Authorize transfer to {target}? (y/n) ")
if approval.lower() == "y":
response = client.beta.conversations.start(
agent_id=target,
inputs=query,
)
else:
print("Transfer refused.")
break
O input da consola serve de demonstração; numa aplicação, será substituído por uma notificação a um operador e pela retomada do fluxo de trabalho quando a resposta chegar. O princípio permanece o mesmo: a transferência ocorre apenas se o seu código a desencadear.
A abordagem correta consiste em começar no modo servidor e mudar apenas no dia em que uma restrição específica o exigir. Mudar para o modo cliente “por precaução” fá-lo pagar imediatamente pela complexidade de um ciclo e pelas idas e voltas de rede, por um controlo que ainda não está a utilizar.
Pontos-chave
- Modo servidor = totalmente automático, simples e rápido, sem controlo intermédio
- Modo cliente = recebe eventos de transferência e decide o que fazer
- O modo cliente permite validação, registo, roteamento condicional e tratamento de erros
- Para a maioria dos casos, o modo servidor é suficiente—mude para o modo cliente quando precisar de controlo
- Ambos os modos suportam as mesmas cadeias de agentes; apenas o controlo difere