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

Execução no Servidor vs. no Cliente

Aula 14 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Duas Formas de Gerir Transferências
  2. Modo Servidor, o Padrão
  3. Modo Cliente, Quando Quer Controlo
  4. Escolher Entre os Dois
  5. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base no SDK mistralai 3.7.0 e na documentação Handoffs da Mistral: uma entrada agent.handoff identifica o agente de destino através de next_agent_id (e não to_agent), e conversations.append não aceita o parâmetro agent_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