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

Raciocínio em agentes e conversas

Aula 4 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Três formas de invocar um modelo de raciocínio
  2. Um agente que raciocina
  3. Ler os resultados de uma conversa
  4. Uma conversa sem agente
  5. Raciocínio e ferramentas
  6. Comparação das três abordagens
  7. Boas práticas de integração
  8. Pontos-chave

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_effort está disponível nos endpoints Agents e Conversations, dentro do campo completion_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érioChat CompletionsAgentsConversations
Onde definir o raciocínioreasoning_effort no pedidocompletion_args no agentecompletion_args em start ou append
HistóricoReenviar em cada chamada, incluindo a reflexãoTransportado pela conversaMantido no servidor
Ferramentas integradas (web_search…)NãoSimSim
Utilização típicaChamadas pontuais, controlo totalConfiguração partilhada e reutilizávelTrocas 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_effort dentro de completion_args
  • As respostas chegam em outputs; o texto reside nas entradas message.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