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

Opções de tool_choice

Aula 9 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Decidir Quem Decide
  2. auto — Deixe o Modelo Julgar
  3. any — Impor Saída Estruturada
  4. none — Desativar Ferramentas Sem as Remover
  5. Ajustar a Definição ao Longo da Conversa
  6. Pontos-chave

Decidir Quem Decide

Passar tools à API não significa que o modelo as deva usar, nem sequer que lhe seja permitido fazê-lo. Entre estes dois extremos, o parâmetro tool_choice atua como árbitro. Dependendo do valor que atribuir, pode deixar o modelo livre para julgar, forçá-lo a produzir uma chamada estruturada ou revogar completamente o seu acesso às ferramentas que acabou de declarar. É uma definição subtil, mas que altera radicalmente o comportamento do mesmo código perante a mesma pergunta.

ValorComportamentoCaso de Utilização
autoO modelo decide livremente se utiliza uma ferramenta ou responde em texto. Este é o modo predefinido.Assistentes conversacionais, chatbots de uso geral
anyO modelo é forçado a chamar pelo menos uma ferramenta. Não pode responder apenas com texto.Pipelines automatizados, extração de dados estruturados
noneO modelo não pode usar ferramentas, mesmo que estejam definidas. Responde apenas em texto.Resumir resultados sem novas chamadas, reformular uma resposta
requiredSinónimo de any. O modelo deve usar pelo menos uma ferramenta.Equivalente a any, para compatibilidade

auto — Deixe o Modelo Julgar

Este é o valor predefinido, aquele que utiliza sem se dar conta sempre que omite o parâmetro.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto"  # Opcional, este é o valor predefinido
)

Com auto, o modelo avalia o pedido antes de agir. Se a pergunta exigir dados externos que não possui, chama uma função; se a consulta for geral ou relacional, responde diretamente em texto. Esta alternância é o que faz um assistente parecer natural: o utilizador não precisa de saber que existem ferramentas por detrás do ecrã.

# O modelo chamará uma função
messages = [{"role": "user", "content": "Estado do pagamento T1001?"}]
# → tool_call: retrieve_payment_status(transaction_id="T1001")

# O modelo responderá diretamente
messages = [{"role": "user", "content": "Olá, como está?"}]
# → content: "Olá! Sou um assistente de pagamentos. Como posso ajudar?"

O segundo exemplo merece atenção: forçar uma chamada de função num simples cumprimento produziria um retrieve_payment_status com um ID inventado. É exatamente isso que o auto previne, razão pela qual este modo continua a ser o mais comum em produção.

any — Impor Saída Estruturada

Pelo contrário, existem contextos em que o texto de forma livre não tem qualquer valor para si. Um pipeline de ingestão que processa dez mil documentos espera JSON utilizável, não uma frase educada. Com any, o modelo deve chamar pelo menos uma função, mesmo que a pergunta não pareça exigir isso.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="any"
)

Curiosamente, o caso de utilização mais frequente reaproveita a chamada de funções para além da sua intenção original: não está a declarar uma função para a executar, mas para garantir um esquema de saída. Aqui, extract_entities nunca será chamada no lado do servidor; o que importa é o contrato JSON.

# Extração estruturada: forçar o modelo a extrair dados
tools = [{
    "type": "function",
    "function": {
        "name": "extract_entities",
        "description": "Extrai entidades nomeadas do texto",
        "parameters": {
            "type": "object",
            "properties": {
                "persons": {"type": "array", "items": {"type": "string"}},
                "organizations": {"type": "array", "items": {"type": "string"}},
                "dates": {"type": "array", "items": {"type": "string"}}
            },
            "required": ["persons", "organizations", "dates"]
        }
    }
}]

messages = [{"role": "user", "content": "Sophia Yang da Mistral apresentou "
            "chamada de funções em 15 de março de 2026."}]

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="any"  # Forçar extração
)

# → extract_entities(persons=["Sophia Yang"],
#                     organizations=["Mistral"],
#                     dates=["15 de março de 2026"])

Note de passagem o required: é um sinónimo de any, incluído para compatibilidade com código escrito para outras APIs. Ambos os valores produzem o mesmo comportamento; escolha aquele que torna o seu código mais legível e mantenha-o.

none — Desativar Ferramentas Sem as Remover

O terceiro valor responde a uma necessidade menos óbvia. Já recuperou os seus dados através de várias tool_calls e agora quer que o modelo as sintetize. Se continuar a conversa no modo auto, nada impede o modelo de voltar a chamar uma função “apenas para verificar”, o que aumenta a latência e pode desencadear um loop infinito. O none proíbe quaisquer novas chamadas, mantendo as definições das ferramentas no contexto, ajudando o modelo a falar com precisão sobre os dados que já possui.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="none"
)

Três casos de utilização surgem constantemente: solicitar um resumo após uma série de chamadas de função, reformular uma resposta sem desencadear novas chamadas e testar em desenvolvimento como o modelo se comporta quando privado das suas ferramentas, o que revela rapidamente perguntas que ele pensa poder responder de memória.

# Após recuperar dados via tool_calls...
# Solicitar um resumo sem novas chamadas
messages.append({
    "role": "user",
    "content": "Resuma a informação de todos os pagamentos que encontrou."
})

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="none"  # O modelo resume com o que já tem
)

Ajustar a Definição ao Longo da Conversa

Não tem de definir tool_choice uma única vez no arranque. Em produção, é comum calculá-lo a cada turno com base no contexto: a primeira mensagem da conversa, a intenção detetada no pedido ou o número de chamadas já consumidas. A função abaixo ilustra esta lógica na sua forma mais simples — o modelo permanece livre por predefinição, exceto quando o utilizador solicita explicitamente um resumo.

def get_tool_choice(user_input: str, turn_count: int) -> str:
    """Determina tool_choice com base no contexto."""

    # Primeiro turno: deixar o modelo decidir
    if turn_count == 0:
        return "auto"

    # Se o utilizador solicitar explicitamente um resumo
    if any(word in user_input.lower() for word in ["summarize", "recap", "synthesis"]):
        return "none"

    # Predefinição
    return "auto"

Na prática, mantenha auto como a sua definição base: é a mais natural e flexível. Reserve any para pipelines de extração de dados estruturados e none para momentos em que deve prevenir loops infinitos de tool_call. Uma restrição é absoluta: nunca altere tool_choice no meio do processamento de uma tool_call. Complete primeiro o ciclo devolvendo todas as mensagens tool esperadas e, só depois, ajuste o parâmetro no turno seguinte; caso contrário, o histórico torna-se inconsistente e a API rejeita o pedido.

Pontos-chave

  • tool_choice controla quando o modelo usa funções
  • auto = o modelo decide livremente (predefinição, recomendado para chatbots)
  • any = o modelo é forçado a chamar uma ferramenta (pipelines, extração estruturada)
  • none = ferramentas desativadas (resumos, reformulação)
  • Adapte tool_choice dinamicamente com base no contexto da conversa