Opções de tool_choice
Nesta página
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.
| Valor | Comportamento | Caso de Utilização |
|---|---|---|
auto | O modelo decide livremente se utiliza uma ferramenta ou responde em texto. Este é o modo predefinido. | Assistentes conversacionais, chatbots de uso geral |
any | O modelo é forçado a chamar pelo menos uma ferramenta. Não pode responder apenas com texto. | Pipelines automatizados, extração de dados estruturados |
none | O modelo não pode usar ferramentas, mesmo que estejam definidas. Responde apenas em texto. | Resumir resultados sem novas chamadas, reformular uma resposta |
required | Sinó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_choicecontrola quando o modelo usa funçõesauto= 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_choicedinamicamente com base no contexto da conversa