Mistral Responses API: configure o Large 4 e migre da OpenAI

Use a Mistral Responses API com mistral-large-4 e envie o histórico da conversa em input a cada requisição. Remova os parâmetros de continuação no servidor, mantenha o armazenamento desativado e escolha um nível de raciocínio aceito pelo modelo. Em 2026-11-01, a Responses API da Mistral está disponível em prévia pública.

Execute uma requisição mínima ao Mistral Large 4

Use o SDK Python atual da Mistral e uma chave de API da Mistral na primeira requisição. Esse é um ponto de partida documentado antes de adaptar um cliente Responses existente.

Use Python 3.10 ou mais recente. Crie uma chave em Studio → API keys e execute estes comandos no Bash. Quando o comando aguardar a entrada, cole a chave e pressione Enter. Os caracteres não aparecerão na tela.

python3 -m pip install -U mistralai
read -rs MISTRAL_API_KEY && export MISTRAL_API_KEY

Salve o código abaixo como mistral_responses.py. A função auxiliar mantém as instruções e as configurações das requisições consistentes nos exemplos seguintes.

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
MODEL = "mistral-large-4"
INSTRUCTIONS = "Answer concisely."

def create_response(history, **options):
    result = client.responses.create(
        model=MODEL,
        input=history,
        instructions=INSTRUCTIONS,
        reasoning={"effort": "high"},
        max_output_tokens=4096,
        additional_properties={
            "store": False,
            "background": False,
            "truncation": "disabled",
        },
        **options,
    )
    if result.status != "completed":
        raise RuntimeError(
            f"{result.status}: {result.error or result.incomplete_details}"
        )
    return result

def answer_text(result):
    return "".join(
        part.text
        for item in result.output if item.type == "message"
        for part in item.content if part.type == "output_text"
    )

history = [{"role": "user", "content": "Explain a stateless API in one sentence."}]
response = create_response(history)
print(response.status)
print(answer_text(response))

Execute o arquivo na mesma sessão do Bash:

python3 mistral_responses.py

Neste exemplo, o sinal de sucesso é completed, seguido de uma explicação não vazia. O texto pode variar. O código extrai o texto da resposta porque output também pode conter raciocínio e chamadas de função.

O endpoint HTTP é https://api.mistral.ai/v1/responses. Requisições HTTP diretas usam o cabeçalho Authorization: Bearer $MISTRAL_API_KEY. Um cliente que acrescenta /responses precisa da URL base https://api.mistral.ai/v1.

Os demais exemplos em Python reutilizam as variáveis e as funções auxiliares desse arquivo. Acrescente os exemplos necessários ao final dele. Executar o arquivo novamente também executará todas as chamadas de geração incluídas.

Quais parâmetros do OpenAI Responses precisam mudar?

Ajuste os campos JSON enviados por HTTP antes de reutilizar uma requisição OpenAI Responses. A referência da Responses API define os valores aceitos em 2026-11-01.

Parâmetro da requisição Responses	Requisito da Mistral	Ação na migração
`previous_response_id`	Omita ou envie `null`.	Reenvie os itens de saída anteriores em `input`.
`conversation`	Omita ou envie `null`.	Mantenha o histórico da conversa na aplicação.
`store`	Omita ou envie `false` ou `null`.	Remova `true`; não dependa de respostas armazenadas.
`background`	Deve ser `false`; esse também é o valor padrão.	Remova a execução em segundo plano e a consulta periódica de seu status.
`truncation`	Deve ser `"disabled"`; esse também é o valor padrão.	Controle o tamanho do contexto antes de enviar a requisição.
`prompt`	Omita ou envie `null`.	Coloque o conteúdo do prompt em `input` e `instructions`.
`moderation`	Omita ou envie `null`.	Remova o valor preenchido nesse campo de compatibilidade.
`top_logprobs`	Omita ou envie `0` ou `null`.	Remova valores positivos.
`max_tool_calls`	É aceito, mas atualmente ignorado.	Imponha limites de execução na aplicação.
`reasoning.effort`	Deve ser compatível com o modelo selecionado.	Use os valores específicos de cada modelo, listados abaixo.
`tools`	Funções executadas pelo cliente, opcionalmente agrupadas em espaços de nomes.	Substitua dependências de ferramentas executadas pelo provedor.
`max_output_tokens`	Inclui os tokens de raciocínio e o texto da resposta.	Reserve tokens de saída suficientes para ambos.

Os argumentos nomeados do SDK Python não correspondem a todos os campos HTTP. Sua implementação atual de Responses aceita store, background e truncation por meio de additional_properties. O primeiro exemplo usa esse caminho.

Mantenha essas diferenças na configuração de cada provedor. Trocar o endpoint não comprova a compatibilidade de todas as ferramentas, formas de continuação ou rotinas de processamento de eventos. O guia de compatibilidade entre Messages, Chat Completions e Responses explica por que verificar o ciclo completo de uma chamada de função.

Quais modelos e recursos estão disponíveis?

Use mistral-large-4 neste passo a passo e confira as capacidades ao trocar de modelo. O anúncio de lançamento da Mistral informa suporte a todos os modelos de chat hospedados pela empresa, incluindo o Large 4.

A lista de recursos compatíveis inclui entrada e saída de texto, saída estruturada, streaming, funções e raciocínio conforme o modelo. A entrada de imagens exige um modelo com capacidade de visão e aceita URLs de imagens ou data URLs em base64. A entrada de arquivos aceita URLs HTTPS, data URLs em base64 ou IDs de arquivos enviados; o suporte depende do modelo.

A saída estruturada usa text.format para o modo JSON ou JSON Schema. As ferramentas de função são executadas na sua aplicação. A implementação publicada aceita apenas funções executadas pelo cliente; portanto, não transfira uma ferramenta web_search executada pelo provedor sem adaptá-la.

Para controlar o raciocínio, use o campo aninhado reasoning.effort do Responses. Estes valores seguem o guia de raciocínio da Mistral, consultado em 2026-11-01:

Modelo	Valores aceitos	Escolha prática
`mistral-large-4` / `mistral-large-4-0`	`low`, `medium`, `high`	Comece com `high` no exemplo. Compare níveis menores quando a latência ou o consumo de tokens forem importantes.
`mistral-small-2603`	`none`, `high`	Use `high` quando precisar do modo de raciocínio.
`mistral-medium-3-5`	`none`, `high`	Relevante para integrações existentes; o modelo está marcado como obsoleto.

O Large 4 não aceita none, minimal, xhigh ou max. Se você copiou exemplos da prévia inicial do Large 4, substitua none por low. Um valor presente no enum compartilhado do SDK não comprova que todos os modelos o aceitam.

A ficha do Large 4 também indica que ele está em prévia pública. A ficha do Medium 3.5 registra que ele foi marcado como obsoleto em 2026-10-31. Para novas integrações, a Mistral recomenda o Large 4.

Monte a entrada de vários turnos e devolva resultados de funções

Preserve o histórico completo de itens, incluindo raciocínio e chamadas de função. O texto da resposta serve para exibição, mas não representa todo o registro da conversa.

Continue uma conversa

Acrescente todos os itens do output anterior e, depois, a próxima mensagem do usuário. Adicione este trecho após o primeiro exemplo:

history.extend(response.output)
history.append({"role": "user", "content": "What must the client send next time?"})
response = create_response(history)
print(answer_text(response))
history.extend(response.output)

A segunda requisição contém a primeira mensagem do usuário, a primeira resposta completa e a pergunta seguinte. A função auxiliar também envia instructions novamente.

Essa é a substituição documentada para previous_response_id. Guardar apenas o ID de uma resposta não fornece histórico a esse endpoint sem estado. Guardar somente o texto exibido descarta os demais itens retornados.

Devolva o resultado de uma função

Execute a função localmente e devolva seu resultado com o call_id correspondente. O exemplo de chamada de função da Mistral coloca type, name, description e parameters no mesmo objeto de ferramenta. O exemplo abaixo usa essa estrutura para uma soma local, com um histórico separado.

import json

TOOLS = [{
    "type": "function",
    "name": "add",
    "description": "Add two integers.",
    "parameters": {
        "type": "object",
        "properties": {
            "a": {"type": "integer"},
            "b": {"type": "integer"},
        },
        "required": ["a", "b"],
        "additionalProperties": False,
    },
}]
tool_history = [{"role": "user", "content": "Use add to calculate 19 + 23."}]
response = create_response(
    tool_history,
    tools=TOOLS,
    tool_choice={"type": "function", "name": "add"},
    parallel_tool_calls=False,
)
tool_history.extend(response.output)

calls = [item for item in response.output if item.type == "function_call"]
if len(calls) != 1 or calls[0].name != "add":
    raise RuntimeError("Expected exactly one add call.")

call = calls[0]
args = json.loads(call.arguments)
if (
    not isinstance(args, dict)
    or set(args) != {"a", "b"}
    or any(type(args[name]) is not int for name in ("a", "b"))
):
    raise ValueError("Expected two integer arguments.")

result = args["a"] + args["b"]
print("Local result:", result)
tool_history.append({
    "type": "function_call_output",
    "call_id": call.call_id,
    "output": json.dumps({"result": result}),
})
response = create_response(
    tool_history,
    tools=TOOLS,
    tool_choice="none",
    parallel_tool_calls=False,
)
print(answer_text(response))
tool_history.extend(response.output)

Confira se aparece Local result: 42, seguido de uma resposta que use esse resultado. O texto produzido pelo modelo pode variar.

A primeira requisição força a chamada de add. A segunda usa "none" para impedir novas chamadas, conforme a referência da API. Assim, o exemplo fica limitado a duas etapas de geração e uma execução local.

Em um ciclo de agente sem quantidade fixa de etapas, imponha seus próprios limites de iterações e execuções. O campo max_tool_calls é ignorado.

Preserve toda a saída retornada antes de acrescentar os resultados das funções. Associe cada resultado pelo call_id, não pelo id do item de saída. Se permitir várias chamadas de função, valide e devolva cada resultado antes de solicitar a próxima resposta.

Conte os tokens de entrada antes que o histórico cresça

Conte a próxima requisição inteira, incluindo histórico, instruções e definições de ferramentas. Contar apenas a mensagem mais recente ignora conteúdo que sua aplicação enviará novamente.

Após o exemplo da função, use:

next_input = tool_history + [
    {"role": "user", "content": "Explain that calculation in one sentence."}
]
count = client.responses.count_input_tokens(
    model=MODEL,
    input=next_input,
    instructions=INSTRUCTIONS,
    tools=TOOLS,
    reasoning={"effort": "high"},
    parallel_tool_calls=False,
    tool_choice="auto",
)
print(count.input_tokens)

Esse código chama POST /v1/responses/input_tokens e exibe input_tokens. Ele conta a entrada sem gerar uma resposta. Na geração seguinte, use o mesmo modelo, a mesma entrada, as mesmas instruções e as mesmas ferramentas.

Compare essa contagem com a janela de contexto do modelo escolhido e reserve espaço para a saída. Como truncation deve permanecer "disabled", cabe à aplicação decidir quando reduzir o histórico.

Ao gerenciar o histórico, mantenha as chamadas de função junto dos respectivos resultados. Evite remover itens arbitrários do meio de uma troca com ferramentas.

A contagem de tokens não é uma estimativa de custo. Consulte os preços atuais da API Mistral ao estimar o custo de turnos repetidos e os efeitos do cache.

Diagnostique falhas na migração

Verifique primeiro a configuração da requisição e, depois, o status e os itens de saída. Use a verificação correspondente ao sintoma.

O SDK rejeita um argumento antes de enviar a requisição. Confira o SDK instalado e a assinatura do método. Na implementação usada aqui, coloque store, background e truncation dentro de additional_properties.
A API rejeita a requisição. Volte ao primeiro exemplo de texto. Confira o ID do modelo, o nível de raciocínio aceito e a tabela de compatibilidade. Quando essa requisição funcionar, recoloque os campos opcionais um por vez.
O modelo perde o contexto anterior. Inspecione o próximo array input. Ele precisa conter as mensagens anteriores e os itens de saída completos, não apenas o ID de uma resposta.
A resposta não contém texto. Inspecione status, error e incomplete_details. Confira se existe uma chamada de função aguardando execução. Se a geração atingiu o limite de saída, aumente esse limite ou reduza o nível de raciocínio para outro valor aceito pelo modelo.
A requisição chega ao caminho errado. Compare a URL final com https://api.mistral.ai/v1/responses. O guia de URL base, endpoints e diagnóstico de erros explica erros comuns na construção do caminho.

Para streaming, defina stream=True e processe os eventos Responses. O exemplo oficial de streaming em Python lê cada evento por meio de frame.data. O texto chega em response.output_text.delta; response.completed sinaliza a conclusão.

Trate também os eventos response.failed, response.incomplete e error. Receber um fragmento de texto não comprova que a geração terminou com sucesso. A geração em segundo plano está desativada, portanto essa configuração não precisa de um ciclo de consulta periódica de status.

Escolha entre Responses, Chat Completions e Conversations

Escolha Responses quando o formato de itens atender à aplicação e você quiser controlar o histórico da conversa e a execução das funções.

Necessidade da aplicação	Comece por	Motivo
Itens de entrada e saída Responses e eventos de streaming Responses	Responses API	Mantém esse formato enquanto a aplicação gerencia o estado e as funções.
Uma integração existente baseada em mensagens	Chat Completions	Permite manter o processamento de requisições e respostas orientado a mensagens.
Continuação de conversas armazenadas ou ferramentas executadas pela Mistral	Conversations API	Fornece IDs de conversa e uma interface separada para ferramentas executadas no servidor.

O guia de Chat Completions da Mistral descreve o formato baseado em mensagens. A referência de Conversations documenta a continuação por conversation_id.

Para busca executada pela Mistral, a documentação apresenta web_search e web_search_premium em Conversations e Agents. Esse recurso é separado das ferramentas de função executadas pelo cliente em Responses.

Se a aplicação depende de continuação armazenada ou de ferramentas executadas pelo provedor, avalie Conversations antes de migrar o corpo das requisições. Se a aplicação já assume essas responsabilidades, valide a requisição de texto, o turno seguinte e o ciclo completo de função acima. Depois, conecte o agente completo.