Arquitetura da API de Agentes Mistral
Nesta página
Atualizado em 3 de novembro de 2026. O exemplo anterior de agente completo passava
guardrails={"enabled": True}, um formato que não existe: o parâmetro oficial é uma lista de configuraçõesmoderation_llm_v2. A entradatool.executionexpõe o nome da ferramenta ementry.name, e não ementry.tool_name, o que anteriormente gerava umAttributeError. Fontes: Agents & Conversations · Moderation & Guardrailing · SDKmistralai3.7.0.
Os Três Objetos Fundamentais
A API de Agentes da Mistral baseia-se em três objetos interligados: Agent, Conversation e Entry. A maioria dos erros de deteção precoce num projeto — recriar um agente para cada pedido, reutilizar um conversation_id expirado ou uma análise de resposta que falha perante uma entrada inesperada — resulta da confusão entre estes três níveis. Compreender as suas funções e relações é um pré-requisito para escrever sequer uma linha de código.
O Objeto Agent
Um Agent é um conjunto de configurações que define o comportamento do modelo. Não contém dados de conversação: é um modelo reutilizável que cria uma vez e ao qual milhares de conversas podem fazer referência.
A criação exige, no mínimo, um modelo, um nome e uma descrição.
agent = client.beta.agents.create(
model="mistral-large-latest", # Modelo LLM a utilizar
name="My Agent", # Identificador legível por humanos
description="Agent for financial analysis" # Descrição orientada para a tarefa
)
O parâmetro model designa o modelo que irá alimentar o agente, escolhido entre os modelos de conclusão de chat disponíveis, como mistral-medium-latest ou mistral-large-latest. O name é um identificador legível por humanos que utiliza para encontrar e referenciar o agente: num projeto com vinte deles, é isto que o poupa de vasculhar registos para descobrir qual está a responder aos clientes. A description, por sua vez, é orientada para a tarefa e serve mais do que apenas documentação interna; ajuda o modelo a compreender o papel que se espera dele, o que explica a formulação “agent for financial analysis” em vez de um vago “agent number 3”.
O restante é configurado opcionalmente, e é aqui que a verdadeira personalidade do agente ganha forma.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Complete Agent",
description="Agent with all parameters",
instructions="You are a finance expert. Always respond with sources.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"}
],
completion_args={"temperature": 0.3, "top_p": 0.95},
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"jailbreaking": 0.2, "financial": 1},
"action": "block",
},
}
],
)
instructions— O prompt de sistema do agente (define a sua personalidade, regras e estilo)tools— Lista de ferramentas disponíveis:web_search,web_search_premium,code_interpreter,image_generation,document_libraryou funções personalizadascompletion_args— Parâmetros do amostrador (temperature, top_p, max_tokens, etc.)guardrails— Uma lista de configurações de moderação (moderation_llm_v2) aplicadas à mensagem de entrada de cada uma das conversas do agente; aqui, o jailbreaking é bloqueado acima de 0,2 e a categoriafinancialestá desativada (limiar1), uma vez que o agente foi construído para discutir finanças. Os detalhes encontram-se no curso AI Moderation and Security with Mistral.
No exemplo acima, o agente financeiro herda um requisito de fontes das suas instruções, a capacidade de verificar um valor através das suas ferramentas e uma temperatura baixa que limita a criatividade onde se exige rigor.
O Objeto Conversation
Uma Conversation é o histórico de interações entre um utilizador e um agente — ou entre um utilizador e um modelo isolado. Contém mensagens, resultados de execução de ferramentas e eventos de transferência (handoff).
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Recuperar o ID da conversação para continuar mais tarde
conversation_id = response.conversation_id
O comportamento deste objeto guarda algumas surpresas. A conversação é persistente: o histórico é armazenado no lado da Mistral, a menos que passe store=False. É independente do agente, o que significa que uma conversação pode perfeitamente existir sem um agente, no modo de modelo direto. Finalmente, é imutável: cada adição devolve um novo conversation_id, permanecendo o antigo acessível. Este último ponto é o mais surpreendente: se armazenar o ID inicial na sua base de dados e o reutilizar na terceira intervenção, regressará ao contexto da primeira troca.
O Objeto Entry
Um Entry é uma ação individual dentro de uma conversação: a unidade atómica do histórico. Quando recebe uma resposta, o campo outputs contém uma lista de entradas cujo tipo depende do que o agente fez. Uma entrada message.output transporta uma resposta de texto do agente, ou seja, o texto que a sua interface irá apresentar. Uma entrada tool.execution transporta o resultado da execução de uma ferramenta, como código ou uma pesquisa na web: o script lançado e o seu output, ou as páginas devolvidas pelo motor. Uma entrada agent.handoff sinaliza um evento de transferência para outro agente, aparecendo assim apenas em cenários multi-agente.
Uma única resposta combina frequentemente estes tipos. Se pedir um cálculo a um agente com ferramentas, receberá a execução e, em seguida, o comentário que a acompanha: o seu código deve, portanto, iterar sobre esta lista em vez de ler um único campo.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Calculate the square root of 144"
)
for entry in response.outputs:
print(f"Type: {entry.type}")
if entry.type == "message.output":
print(f"Message: {entry.content}")
elif entry.type == "tool.execution":
print(f"Tool: {entry.name}")
Relações Entre Objetos
O diagrama seguinte resume a articulação dos três níveis: uma configuração reutilizável, um fio de histórico e ações unitárias.
Agent (configuration)
├── model, instructions, tools, guardrails
└── Can be referenced by N conversations
Conversation (history)
├── Linked to 0 or 1 Agent (optional)
├── Contains N ordered entries
└── Each append creates a new conversation_id
Entry (unit action)
├── message.output (text response)
├── tool.execution (tool result)
└── agent.handoff (agent transfer)
Opções de Conversação
Iniciar uma conversação aceita definições que impactam tanto a sua conformidade como a sua arquitetura, e é melhor decidi-las do que sofrê-las. Primeiro, o armazenamento: store=False impede qualquer gravação no lado da Mistral, o que utilizará para processar dados que a sua política interna proíbe de deixar num servidor de terceiros.
# Desativar armazenamento na nuvem
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
A segunda definição determina quem executa as transferências (handoffs). No modo server, o valor predefinido, a Mistral encadeia as transferências de agentes sem a sua intervenção; no modo client, recebe eventos de handoff e mantém o controlo para registar, filtrar ou recusar.
# Modo server (predefinido) — A Mistral gere os handoffs automaticamente
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Modo client — Recebe eventos de handoff e decide o que fazer
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Pontos-chave
- Agent = configuração reutilizável (modelo, instruções, ferramentas, guardrails)
- Conversation = histórico persistente armazenado no servidor, independente do agente
- Entry = ação unitária (mensagem, execução de ferramenta, handoff)
- As conversas podem existir sem um agente (modo de modelo direto)
- Cada adição a uma conversação cria um novo
conversation_id - O modo
store=Falseimpede o armazenamento no lado da Mistral