Raciocínio em agentes e conversas
Nesta página
Lição reescrita em 2 de novembro de 2026 para o Mistral Small 4 e Large 4. A documentação da Mistral indica que o parâmetro
reasoning_effortestá disponível nos endpoints Agents e Conversations, dentro do campocompletion_args. Fontes: Reasoning · Python SDK — Conversations.
Três formas de invocar um modelo de raciocínio
As lições anteriores utilizaram a API Chat Completions: enviava o histórico completo em cada chamada e o parâmetro reasoning_effort era inserido diretamente no pedido. A Mistral oferece duas outras interfaces: a API Agents, que guarda uma configuração reutilizável (modelo, instruções, ferramentas, parâmetros), e a API Conversations, que mantém o histórico no servidor. Nestas duas APIs, não define o raciocínio ao nível superior; deve aninhá-lo dentro de completion_args, juntamente com outros parâmetros de geração.
Um agente que raciocina
Definir o nível de raciocínio na definição do agente evita repeti-lo em cada chamada e garante que toda a sua equipa utiliza a mesma configuração:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
agent = client.beta.agents.create(
model="mistral-small-2603",
name="Financial Analyst",
instructions=(
"You analyze financial situations for SMEs. "
"End every response with a quantified recommendation and its assumptions."
),
completion_args={"reasoning_effort": "high"},
)
reponse = client.beta.conversations.start(
agent_id=agent.id,
inputs="Our working capital requirement has doubled in a year while revenue grew by 15%. What should we look at first?",
)
Ler os resultados de uma conversa
Uma conversa não devolve choices; devolve uma lista de entradas (outputs). A resposta do modelo encontra-se nas entradas do tipo message.output. Tal como nas Chat Completions, o conteúdo é uma cadeia de caracteres ou uma lista de fragmentos que podem incluir um ThinkChunk. A função separer da Lição 3 funciona exatamente da mesma forma:
for entry in reponse.outputs:
if entry.type == "message.output":
reflexion, texte = separer(entry.content)
print(texte)
Outras entradas descrevem o que ocorreu durante o turno, como a execução de ferramentas (tool.execution) ou uma chamada de função. Ignore-as se apenas lhe interessar a resposta final.
Uma conversa sem agente
Para tarefas pontuais, a API Conversations aceita um modelo diretamente, sem configuração prévia de agente. O servidor mantém o histórico e pode continuar a troca com conversations.append, ajustando o nível de raciocínio para um turno específico, se necessário:
conv = client.beta.conversations.start(
model="mistral-large-4-0",
inputs="Propose a migration plan for a 2 TB PostgreSQL database with zero downtime.",
completion_args={"reasoning_effort": "high"},
)
suite = client.beta.conversations.append(
conversation_id=conv.conversation_id,
inputs="Summarize this plan in five steps for executive leadership.",
completion_args={"reasoning_effort": "low"}, # a summary doesn't need deep reflection
)
Esta é uma vantagem concreta face às Chat Completions, onde a documentação exige que reenvie a mensagem completa do assistente, incluindo a reflexão, em cada novo turno (Lição 7). Com a API Conversations, o servidor guarda o histórico; não precisa de o reenviar em cada chamada.
Raciocínio e ferramentas
Um agente pode combinar raciocínio e ferramentas: tools e completion_args são campos independentes aquando da criação de um agente. Um agente de análise pode, assim, dispor de pesquisa na web e de raciocínio profundo:
agent_veille = client.beta.agents.create(
model="mistral-small-2603",
name="Competitive Intelligence",
instructions="You compare competitor offers using cited public sources.",
tools=[{"type": "web_search"}],
completion_args={"reasoning_effort": "high"},
)
Contudo, esteja atento aos custos: a reflexão e as chamadas de ferramentas acumulam-se na fatura de um único turno.
Comparação das três abordagens
| Critério | Chat Completions | Agents | Conversations |
|---|---|---|---|
| Onde definir o raciocínio | reasoning_effort no pedido | completion_args no agente | completion_args em start ou append |
| Histórico | Reenviar em cada chamada, incluindo a reflexão | Transportado pela conversa | Mantido no servidor |
Ferramentas integradas (web_search…) | Não | Sim | Sim |
| Utilização típica | Chamadas pontuais, controlo total | Configuração partilhada e reutilizável | Trocas multi-turno |
Boas práticas de integração
Defina o nível de raciocínio no agente quando a tarefa for uniforme e por turno quando variar: um turno de análise inicial com high, seguido de turnos de reformulação com low ou none, dependendo do modelo. Verifique se o valor é adequado ao modelo do agente: o Small 4 aceita high e none; o Large 4 aceita low, medium e high. Por fim, registe a utilização de tokens por turno; é a única forma de saber se o raciocínio compensa para o seu caso de uso.
Pontos-chave
- Nas APIs Agents e Conversations, passe
reasoning_effortdentro decompletion_args - As respostas chegam em
outputs; o texto reside nas entradasmessage.output, incluindo a reflexão - A API Conversations mantém o histórico no servidor: não é necessário reenviá-lo a cada turno
- Pode alterar o nível em cada turno com
conversations.append - Um agente pode combinar ferramentas integradas e raciocínio, ao custo de um uso cumulativo