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

Arquitetura da API de Agentes Mistral

Aula 3 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Os Três Objetos Fundamentais
  2. O Objeto Agent
  3. O Objeto Conversation
  4. O Objeto Entry
  5. Relações Entre Objetos
  6. Opções de Conversação
  7. Pontos-chave

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ções moderation_llm_v2. A entrada tool.execution expõe o nome da ferramenta em entry.name, e não em entry.tool_name, o que anteriormente gerava um AttributeError. Fontes: Agents & Conversations · Moderation & Guardrailing · SDK mistralai 3.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_library ou funções personalizadas
  • completion_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 categoria financial está desativada (limiar 1), 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=False impede o armazenamento no lado da Mistral