A Mistral AI juntou-se à corrida dos agentes autónomos com a Agents API, uma camada que gere memória, ferramentas e estado de conversa do lado do servidor. Em vez de reimplementar chamadas de funções e histórico de mensagens em cada projeto, a equipa francesa entrega um sistema pronto a ligar a pesquisa web, execução de código e ao protocolo MCP (Model Context Protocol). Este tutorial mostra, passo a passo, como sair de “chatbot que responde perguntas” para “agente que resolve tarefas” usando esta API, com código Python testável e um projeto final completo.

Vamos construir um agente de suporte técnico que combina pesquisa na web, execução de código Python num sandbox e uma ferramenta personalizada via function calling. No final, terás um projeto funcional que consegues adaptar para automatizar relatórios, triagem de bugs ou análise de dados internos. Se procuras mais cobertura sobre modelos e ferramentas de IA, a nossa secção de Inteligência Artificial reúne outros tutoriais e análises da área. Segundo a própria Mistral AI, cada agente “pode ser equipado com conectores integrados, que são ferramentas prontas a usar sob pedido, e ferramentas MCP” (Mistral AI, anúncio oficial da Agents API), o que resume bem a filosofia por trás desta API: menos código de encanamento, mais foco na lógica do agente.

O que é a Mistral Agents API e porque interessa a programadores

A Agents API é uma camada construída sobre os modelos de chat da Mistral que acrescenta três coisas que faltam numa API de completions simples: memória persistente entre pedidos, um catálogo de ferramentas nativas e suporte estruturado para ferramentas MCP. Em vez de reenviares o histórico completo da conversa a cada pedido, crias uma conversa uma vez e o servidor guarda o estado por ti. É o mesmo princípio por trás da Responses API da OpenAI, lançada em março de 2025: o cliente deixa de ser responsável por gerir threads localmente.

Do lado técnico, a arquitetura assenta em dois recursos principais: agentes (definidos uma vez, com instruções, modelo e ferramentas associadas) e conversas (sessões que referenciam um agente e acumulam mensagens). Isto separa “quem é o agente” de “o que está a acontecer agora”, o que facilita reutilizar a mesma definição de agente em múltiplas conversas simultâneas, cada uma com o seu próprio contexto isolado.

A documentação oficial explica que a chamada de funções, sob o conceito mais amplo de Tool Calling, “permite que os modelos Mistral se liguem a ferramentas locais externas” (documentação Mistral sobre function calling). Isto significa que a API não se limita a ferramentas geridas pela Mistral: também podes expor as tuas próprias funções Python, desde que descritas com um esquema JSON claro. É essa combinação de ferramentas nativas mais funções personalizadas que torna a Agents API interessante para casos de uso reais, como automação de suporte técnico, análise de dados ou agentes de pesquisa interna.

Pré-requisitos: contas, versões e ferramentas

Antes de escrever a primeira linha de código, confirma que tens tudo preparado. Esta lista evita os erros mais comuns de configuração que fazem perder tempo a meio do tutorial.

  • Conta na plataforma Mistral AI (console.mistral.ai) com uma chave de API ativa
  • Python 3.9 ou superior instalado (recomendado 3.11+)
  • SDK oficial: pacote mistralai versão 2.10.0 ou superior, disponível no PyPI
  • Um editor de código (VS Code, PyCharm ou equivalente) com suporte a variáveis de ambiente
  • Terminal com acesso a pip e curl para testes rápidos
  • Crédito de API ativo na conta Mistral (a Agents API é paga por token e por chamada de ferramenta)
  • Conhecimentos básicos de Python (funções, dicionários, chamadas assíncronas ajudam mas não são obrigatórias)

Vale a pena confirmar a versão do SDK antes de avançar, porque a Mistral atualiza o pacote com frequência e algumas assinaturas de métodos mudam entre versões menores. Corre o comando abaixo para verificar o que tens instalado.

pip show mistralai | grep -i version
# Se não estiver instalado ou estiver desatualizado:
pip install --upgrade mistralai

Passo 1: Cria a conta e gera a chave de API

Regista-te em console.mistral.ai e navega até à secção “API Keys”. Gera uma nova chave e guarda-a de imediato, porque a plataforma só a mostra uma vez. Nunca coloques a chave diretamente no código-fonte: usa uma variável de ambiente ou um ficheiro .env excluído do controlo de versões.

# No terminal (Linux/macOS)
export MISTRAL_API_KEY="a_tua_chave_aqui"

# No Windows PowerShell
$env:MISTRAL_API_KEY="a_tua_chave_aqui"

A autenticação em todos os pedidos à API usa um token Bearer no cabeçalho Authorization. O URL base da API é https://api.mistral.ai/v1 e o endpoint de agentes vive em https://api.mistral.ai/v1/agents. Podes testar a ligação com um simples pedido GET antes de escreveres qualquer código Python.

curl https://api.mistral.ai/v1/agents \
  -X GET \
  -H "Authorization: Bearer $MISTRAL_API_KEY"

Se a resposta devolver uma lista JSON (mesmo que vazia, do género {"data": [], "object": "list"}), a chave está válida e podes avançar. Um código 401 significa chave incorreta ou mal exportada na sessão do terminal; volta a verificar a variável de ambiente antes de continuar. Se preferires acompanhar em paralelo com a fonte oficial, o guia rápido de criação de agentes da Mistral segue uma estrutura semelhante à deste tutorial, embora sem o exemplo completo de function calling e MCP que vamos construir aqui.

Passo 2: Instala o SDK e organiza o projeto

Cria uma pasta dedicada para o projeto e um ambiente virtual isolado. Isto evita conflitos de dependências com outros projetos Python que já tenhas na máquina.

mkdir agente-suporte-mistral
cd agente-suporte-mistral
python3 -m venv venv
source venv/bin/activate   # No Windows: venv\Scripts\activate

pip install mistralai python-dotenv
mkdir -p src
touch src/main.py .env

No ficheiro .env, guarda a tua chave assim: MISTRAL_API_KEY=a_tua_chave_aqui. Adiciona .env ao teu .gitignore imediatamente, antes de fazeres o primeiro commit. É um dos erros mais comuns em tutoriais de IA: a chave acaba num repositório público e é apanhada por bots de scraping em minutos.

Passo 3: Cria o teu primeiro agente com o SDK Python

Com o ambiente pronto, o próximo passo é definir o agente. Um agente na Mistral Agents API é composto por um nome, uma descrição, instruções (o equivalente ao system prompt) e uma lista de ferramentas associadas. O modelo por trás do agente pode ser qualquer um dos modelos de chat e visão da Mistral disponíveis na tua conta; a cobertura da imprensa especializada destaca o Mistral Medium 3 como opção central para orquestração de agentes, mas podes escolher outro modelo conforme o caso de uso e o orçamento.

import os
from dotenv import load_dotenv
from mistralai import Mistral

load_dotenv()

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

agente = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Agente de Suporte Técnico",
    description="Responde a perguntas técnicas, pesquisa na web e executa código de diagnóstico.",
    instructions=(
        "És um assistente de suporte técnico sénior. "
        "Responde sempre em português de Portugal, de forma direta e prática. "
        "Usa a pesquisa web quando precisares de informação atual. "
        "Usa o interpretador de código para validar cálculos ou testar trechos de código."
    ),
)

print("Agente criado com ID:", agente.id)

Corre este script com python src/main.py. Se tudo estiver bem configurado, o terminal devolve um identificador único do agente, algo como ag_01j.... Guarda esse ID; vais precisar dele para iniciar conversas. Nota que este exemplo ainda não tem ferramentas associadas: vamos adicioná-las no próximo passo.

Passo 4: Liga os conectores nativos (pesquisa web e execução de código)

A grande vantagem da Agents API face a uma implementação manual de function calling é o catálogo de conectores prontos a usar. Segundo a documentação oficial, as ferramentas web_search, web_search_premium e code_interpreter funcionam tanto com a Conversations API como com a Agents API. Não precisas de escrever a lógica de pesquisa nem de gerir um sandbox de execução: só declaras o tipo de ferramenta na criação do agente.

agente = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Agente de Suporte Técnico",
    description="Responde a perguntas técnicas, pesquisa na web e executa código de diagnóstico.",
    instructions=(
        "És um assistente de suporte técnico sénior. "
        "Usa a pesquisa web para dados atuais e o interpretador de código "
        "para validar cálculos, testar scripts ou analisar ficheiros pequenos."
    ),
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"},
    ],
)

O conector de pesquisa web devolve resultados atuais da internet e o agente decide sozinho quando os usar, com base nas instruções e na pergunta do utilizador. Já o code_interpreter executa Python num ambiente isolado gerido pela Mistral, útil para validar contas, gerar gráficos simples ou testar um trecho de código antes de o sugerir ao utilizador. Nenhum destes dois conectores exige que escrevas código de execução: a orquestração é feita inteiramente do lado do servidor.

Conectores adicionais disponíveis

Além dos dois conectores usados neste tutorial, a Mistral disponibiliza geração de imagem e acesso a notícias premium como conectores integrados, cada um com o seu próprio modelo de faturação por chamada. Para um agente de suporte técnico como o que estamos a construir, pesquisa web e execução de código cobrem a maioria dos casos reais, mas vale a pena conhecer as outras opções se o teu projeto evoluir para geração de conteúdo visual ou monitorização de notícias do setor. A documentação de cada conector, incluindo os parâmetros aceites e limites de uso, está disponível na página oficial do conector de pesquisa web, que também explica a diferença prática entre o plano normal e o premium.

ConectorFunçãoPreço aproximado
web_searchPesquisa geral na web$30 por 1.000 chamadas
web_search_premiumPesquisa web e notícias premium$50 por 1.000 chamadas
code_interpreterExecução de código Python em sandbox$30 por 1.000 chamadas
Geração de imagemCriação de imagens a partir de texto$100 por 1.000 imagens

Estes valores, avançados pela cobertura da VentureBeat sobre o lançamento da Agents API, são cobrados em cima do custo normal de tokens do modelo escolhido (no caso do Mistral Medium 3, cerca de $0,4 por milhão de tokens de entrada e $2 por milhão de tokens de saída). Para um agente que faz poucas dezenas de pesquisas por dia, o custo dos conectores costuma ser residual face ao custo de tokens do modelo em si, mas convém monitorizar o consumo assim que o agente entra em produção.

Passo 5: Inicia uma conversa e envia a primeira mensagem

Com o agente criado, o passo seguinte é abrir uma conversa que referencie o ID desse agente. A Conversations API trata da persistência: não precisas de reenviar o histórico completo a cada pedido, porque o servidor guarda o estado associado ao ID da conversa.

resposta = client.beta.conversations.start(
    agent_id=agente.id,
    inputs="Qual é a diferença entre TLS 1.2 e TLS 1.3 em termos de latência de handshake?",
)

print(resposta.outputs[-1].content)
print("ID da conversa:", resposta.conversation_id)

Guarda o conversation_id devolvido. Para continuar a mesma conversa mais tarde (por exemplo, numa aplicação web onde o utilizador volta a escrever), usa esse identificador em vez de criar uma conversa nova a cada mensagem.

segunda_resposta = client.beta.conversations.append(
    conversation_id=resposta.conversation_id,
    inputs="E como é que isso afeta o tempo de carregamento de um site com muitos pedidos simultâneos?",
)

print(segunda_resposta.outputs[-1].content)

Repara que a segunda mensagem não repete contexto nenhum sobre TLS: o modelo já sabe do que se está a falar porque o servidor manteve o histórico associado ao conversation_id. Isto simplifica bastante a lógica do lado do cliente, sobretudo em aplicações com múltiplos utilizadores e conversas em paralelo.

Passo 6: Adiciona uma ferramenta personalizada com function calling

Os conectores nativos cobrem pesquisa web e execução de código, mas a maioria dos agentes reais precisa de aceder a sistemas internos: uma base de dados de tickets, um CRM ou uma API interna de monitorização. É aqui que entra o function calling clássico. Defines uma função com um esquema JSON e o modelo decide quando a chamar, devolvendo os argumentos extraídos da conversa.

ferramenta_consulta_tickets = {
    "type": "function",
    "function": {
        "name": "consultar_estado_ticket",
        "description": "Consulta o estado atual de um ticket de suporte pelo número.",
        "parameters": {
            "type": "object",
            "properties": {
                "numero_ticket": {
                    "type": "string",
                    "description": "Número do ticket, por exemplo TCK-4821",
                },
            },
            "required": ["numero_ticket"],
        },
    },
}

agente = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Agente de Suporte Técnico",
    description="Responde a perguntas técnicas e consulta o estado de tickets internos.",
    instructions="Usa a ferramenta consultar_estado_ticket sempre que o utilizador mencionar um número de ticket.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"},
        ferramenta_consulta_tickets,
    ],
)

Quando o modelo decide chamar esta função, a resposta da API não contém texto normal: contém um pedido de chamada de ferramenta com o nome da função e os argumentos extraídos da mensagem do utilizador. O teu código tem de detetar esse pedido, executar a função localmente (por exemplo, indo buscar o estado real do ticket à tua base de dados) e devolver o resultado ao modelo para que ele complete a resposta.

def consultar_estado_ticket(numero_ticket: str) -> str:
    # Substitui por uma chamada real à tua base de dados ou API interna
    estados_simulados = {"TCK-4821": "Em análise pela equipa de rede"}
    return estados_simulados.get(numero_ticket, "Ticket não encontrado")

resposta = client.beta.conversations.start(
    agent_id=agente.id,
    inputs="Qual é o estado do ticket TCK-4821?",
)

for saida in resposta.outputs:
    if saida.type == "function.call" and saida.name == "consultar_estado_ticket":
        import json
        argumentos = json.loads(saida.arguments)
        resultado = consultar_estado_ticket(**argumentos)

        resposta_final = client.beta.conversations.append(
            conversation_id=resposta.conversation_id,
            inputs=[{
                "type": "function.result",
                "tool_call_id": saida.tool_call_id,
                "result": resultado,
            }],
        )
        print(resposta_final.outputs[-1].content)

Este ciclo (o modelo pede uma chamada, o teu código executa e devolve o resultado) é o padrão central de qualquer sistema de agentes com ferramentas personalizadas, seja na Mistral, na OpenAI ou em frameworks como LangGraph. A diferença está em quem gere o estado da conversa: aqui, é o servidor da Mistral, não o teu código.

Passo 7: Integra ferramentas MCP para sistemas externos

Para além de funções personalizadas simples, a Agents API suporta nativamente o Model Context Protocol (MCP), o protocolo aberto originalmente proposto pela Anthropic para padronizar a forma como modelos de IA se ligam a aplicações e fontes de dados externas. Em vez de escreveres uma função Python para cada sistema (Slack, GitHub, uma base de dados SQL), implementas ou ligas-te a um servidor MCP que já expõe essas ferramentas de forma padronizada.

agente = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Agente de Suporte Técnico",
    description="Agente com acesso a um servidor MCP de documentação interna.",
    instructions="Consulta a documentação interna via MCP antes de responderes a perguntas sobre processos internos.",
    tools=[
        {"type": "web_search"},
        {
            "type": "mcp",
            "server_url": "https://mcp.exemplo-interno.pt/docs",
            "name": "documentacao_interna",
        },
    ],
)

A vantagem prática do MCP é a reutilização: se já tens (ou a tua equipa de plataforma já mantém) um servidor MCP para expor bases de dados internas ou APIs corporativas, podes ligá-lo à Mistral, à Claude ou a outro modelo compatível sem reescrever a camada de integração. Para casos de uso mais simples, como o exemplo de tickets do passo anterior, o function calling direto continua a ser a opção mais rápida de implementar. A especificação completa do protocolo, incluindo como estruturar um servidor MCP do zero, está disponível no site oficial do Model Context Protocol, enquanto a página de integração MCP na documentação da Mistral detalha os campos aceites na configuração da ferramenta.

Vale notar que o MCP não é exclusivo da Mistral nem foi criado por ela: é um protocolo aberto, o que significa que um servidor MCP que já construas para este projeto pode, em teoria, ser reaproveitado por outros modelos compatíveis no futuro, reduzindo o trabalho de manutenção a longo prazo.

Passo 8: Testa o agente com casos reais

Antes de colocar o agente em produção, testa-o com um conjunto de perguntas que representem o uso real: perguntas que exigem pesquisa web, perguntas que exigem cálculo, perguntas que exigem consulta a um ticket e perguntas ambíguas que não deveriam acionar nenhuma ferramenta. Isto revela rapidamente se as instruções do agente estão bem calibradas.

casos_teste = [
    "Qual é a versão mais recente do TLS disponível hoje?",  # deve usar web_search
    "Calcula quantos pedidos por segundo aguenta um servidor com 200ms de latência média por pedido, assumindo 50 ligações concorrentes.",  # deve usar code_interpreter
    "Qual é o estado do ticket TCK-4821?",  # deve usar a função personalizada
    "Bom dia, como estás?",  # não deve acionar nenhuma ferramenta
]

for pergunta in casos_teste:
    r = client.beta.conversations.start(agent_id=agente.id, inputs=pergunta)
    print(f"\nPergunta: {pergunta}")
    print(f"Resposta: {r.outputs[-1].content}")

Se o agente acionar o interpretador de código para uma saudação simples, ou ignorar a pesquisa web numa pergunta claramente dependente de dados atuais, o problema está quase sempre nas instruções: sê mais explícito sobre quando cada ferramenta deve (ou não deve) ser usada. Instruções vagas como “usa as ferramentas quando necessário” tendem a produzir comportamento inconsistente.

Passo 9: Ativa streaming para respostas em tempo real

Numa aplicação com interface de utilizador, esperar pela resposta completa antes de mostrar qualquer texto piora a perceção de velocidade. O SDK Python permite consumir a resposta em fragmentos à medida que são gerados, o que é especialmente útil quando o agente está a fazer pesquisa web ou a executar código antes de responder em texto.

with client.beta.conversations.stream(
    agent_id=agente.id,
    inputs="Explica como funciona o handshake TLS 1.3 em três frases.",
) as fluxo:
    for evento in fluxo:
        if evento.type == "message.output.delta":
            print(evento.content, end="", flush=True)

Numa aplicação web real, este ciclo alimentaria diretamente uma ligação WebSocket ou Server-Sent Events para o browser do utilizador, dando a sensação de que o agente está “a escrever” a resposta em tempo real, tal como acontece nas interfaces de chat mais conhecidas do mercado.

Passo 10: Junta tudo num projeto completo

Chegou a hora de consolidar os passos anteriores num único ficheiro funcional. Este projeto cria o agente uma vez (evitando recriar um agente novo a cada execução), mantém um pequeno ciclo de conversa no terminal e trata chamadas de função personalizadas.

import os
import json
from dotenv import load_dotenv
from mistralai import Mistral

load_dotenv()
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

FERRAMENTA_TICKETS = {
    "type": "function",
    "function": {
        "name": "consultar_estado_ticket",
        "description": "Consulta o estado atual de um ticket de suporte pelo número.",
        "parameters": {
            "type": "object",
            "properties": {
                "numero_ticket": {"type": "string", "description": "Ex: TCK-4821"},
            },
            "required": ["numero_ticket"],
        },
    },
}

ESTADOS_SIMULADOS = {"TCK-4821": "Em análise pela equipa de rede"}


def consultar_estado_ticket(numero_ticket: str) -> str:
    return ESTADOS_SIMULADOS.get(numero_ticket, "Ticket não encontrado")


def obter_ou_criar_agente() -> str:
    agentes = client.beta.agents.list()
    for a in agentes.data:
        if a.name == "Agente de Suporte Técnico PT":
            return a.id

    novo = client.beta.agents.create(
        model="mistral-medium-latest",
        name="Agente de Suporte Técnico PT",
        description="Agente de suporte com pesquisa web, código e consulta de tickets.",
        instructions=(
            "Responde sempre em português de Portugal. "
            "Usa web_search para dados atuais, code_interpreter para cálculos, "
            "e consultar_estado_ticket quando o utilizador mencionar um número de ticket."
        ),
        tools=[{"type": "web_search"}, {"type": "code_interpreter"}, FERRAMENTA_TICKETS],
    )
    return novo.id


def processar_pergunta(agent_id: str, pergunta: str, conversation_id: str = None):
    if conversation_id:
        r = client.beta.conversations.append(conversation_id=conversation_id, inputs=pergunta)
    else:
        r = client.beta.conversations.start(agent_id=agent_id, inputs=pergunta)

    for saida in r.outputs:
        if saida.type == "function.call" and saida.name == "consultar_estado_ticket":
            argumentos = json.loads(saida.arguments)
            resultado = consultar_estado_ticket(**argumentos)
            r = client.beta.conversations.append(
                conversation_id=r.conversation_id,
                inputs=[{"type": "function.result", "tool_call_id": saida.tool_call_id, "result": resultado}],
            )

    return r.outputs[-1].content, r.conversation_id


if __name__ == "__main__":
    agent_id = obter_ou_criar_agente()
    conversa_id = None
    print("Agente pronto. Escreve 'sair' para terminar.\n")

    while True:
        pergunta = input("Tu: ")
        if pergunta.strip().lower() == "sair":
            break
        resposta, conversa_id = processar_pergunta(agent_id, pergunta, conversa_id)
        print(f"Agente: {resposta}\n")

Guarda este código em src/main.py e corre python src/main.py. Vais obter um pequeno chat de terminal com memória de conversa, capaz de pesquisar na web, executar código e consultar o estado de tickets simulados. A partir daqui, o passo natural é trocar a interface de terminal por uma API REST (com FastAPI, por exemplo) e a função de tickets simulada por uma chamada real à tua base de dados.

Exemplo de saída esperada

Ao correr o projeto completo do passo anterior, uma sessão típica no terminal parece-se com isto:

Agente pronto. Escreve 'sair' para terminar.

Tu: Qual é o estado do ticket TCK-4821?
Agente: O ticket TCK-4821 está atualmente em análise pela equipa de rede.

Tu: E quanto tempo demora normalmente esse tipo de análise?
Agente: Depende da complexidade, mas para tickets de rede a equipa costuma
dar uma primeira atualização dentro de 24 a 48 horas úteis.

Tu: sair

Repara que a segunda pergunta não menciona o número do ticket outra vez, mas o agente mantém o contexto graças à persistência de conversa gerida pelo servidor. Este é o comportamento que distingue a Agents API de uma simples chamada de completions sem estado.

Erros comuns e como os evitar

Depois de testar este fluxo em vários cenários, há um conjunto de erros que se repetem com frequência em projetos novos. Reserva alguns minutos a rever esta lista antes de avançares para produção.

  • Criar um agente novo a cada execução do script. Isto gera dezenas de agentes duplicados na tua conta. Usa sempre agents.list() para verificar se o agente já existe antes de o criar.
  • Esquecer de tratar o resultado de function calling. Se o teu código não detetar o tipo function.call na resposta, a conversa fica presa sem nunca devolver texto ao utilizador.
  • Instruções demasiado vagas sobre quando usar cada ferramenta. Sem orientação explícita, o modelo tanto pode ignorar uma ferramenta útil como abusar dela em perguntas simples, aumentando custos.
  • Não limitar o esquema JSON das funções personalizadas. Campos sem tipo definido ou sem required levam o modelo a inventar valores ou a omitir parâmetros obrigatórios.
  • Ignorar o custo dos conectores. Pesquisa web e execução de código são faturadas por chamada, à parte dos tokens do modelo; um agente muito “pesquisador” pode sair caro à escala.
  • Guardar a chave de API em código versionado. Basta um commit acidental para a chave acabar exposta publicamente.
  • Não validar o resultado das funções antes de o devolver ao modelo. Se a tua função devolver um erro de base de dados em bruto, o agente pode repeti-lo ao utilizador final de forma confusa.

Resolução de problemas (troubleshooting)

Mesmo seguindo o tutorial ao pormenor, é normal esbarrar em erros específicos ao ligar tudo pela primeira vez. Esta secção cobre os problemas mais reportados por programadores a usar a Agents API.

SintomaCausa provávelSolução
Erro 401 UnauthorizedChave de API inválida ou não exportada na sessãoConfirma com echo $MISTRAL_API_KEY e regenera a chave se necessário
Erro 429 Too Many RequestsExcedeste o limite de pedidos por minuto da tua contaImplementa espera exponencial entre tentativas (retry com backoff)
O agente nunca usa a pesquisa webInstruções não mencionam explicitamente quando pesquisarAcrescenta uma frase direta nas instruções, ex: “usa web_search para qualquer dado que possa ter mudado recentemente”
ImportError ao importar Mistral do SDKVersão desatualizada do pacote mistralaiCorre pip install --upgrade mistralai
A função personalizada nunca é chamadaDescrição da função pouco clara ou nome ambíguoTorna o campo description explícito sobre quando usar a função
Resposta demora vários segundos sem streamingNormal quando o agente encadeia pesquisa web + código + resposta finalAtiva o modo stream para mostrar progresso ao utilizador
Erro ao fazer parse dos argumentos da funçãoO JSON devolvido em saida.arguments não corresponde ao esquema esperadoValida sempre com try/except antes de chamar json.loads
Conversa “esquece” contexto de mensagens anterioresEstás a criar uma conversa nova em vez de usar append com o mesmo conversation_idGuarda e reutiliza o conversation_id entre pedidos
Custo mensal mais alto do que esperadoUso excessivo de conectores pagos como code_interpreterMonitoriza consumo no painel da Mistral e restringe ferramentas por caso de uso

Dicas avançadas para produção

Depois de teres o fluxo básico a funcionar, há um conjunto de ajustes que fazem diferença real quando o agente passa de protótipo a serviço em produção. Primeiro, separa agentes por função em vez de teres um único agente genérico com dezenas de ferramentas: um agente de suporte técnico e um agente de faturação, por exemplo, têm instruções e ferramentas diferentes, e misturar tudo num só aumenta a probabilidade de confusão do modelo sobre qual ferramenta usar.

Segundo, regista (log) cada chamada de ferramenta com o respetivo tempo de resposta e custo estimado. Isto dá-te visibilidade real sobre onde o orçamento de API está a ser gasto e ajuda a identificar perguntas que acionam ferramentas desnecessariamente. Terceiro, define limites de segurança nas funções personalizadas: nunca exponhas uma função que execute comandos arbitrários no sistema operativo ou que aceda a dados sensíveis sem validação adicional, porque o modelo decide autonomamente quando chamar a função, e um esquema demasiado permissivo pode ser explorado através de injeção de prompt.

Por fim, considera usar o MCP em vez de dezenas de funções personalizadas isoladas assim que tiveres mais do que três ou quatro integrações internas. A manutenção de um único servidor MCP bem documentado tende a escalar melhor do que espalhar esquemas JSON por vários agentes diferentes, sobretudo se a mesma integração (por exemplo, acesso à base de dados de clientes) for reutilizada por múltiplos agentes na tua organização.

Mistral Agents API vs alternativas do mercado

Antes de comprometeres um projeto inteiro com esta API, vale a pena situá-la face às alternativas mais conhecidas. A Responses API da OpenAI segue uma filosofia semelhante de estado gerido no servidor, enquanto frameworks como o LangGraph (já coberto no nosso tutorial de agentes com LangGraph) ou o CrewAI (ver o nosso guia de agentes multiagente com CrewAI) dão-te controlo total sobre a orquestração, ao custo de teres de gerir tu próprio o estado e a lógica de encadeamento.

CaracterísticaMistral Agents APIFrameworks de orquestração (LangGraph/CrewAI)
Gestão de estadoFeita pelo servidor da MistralGerida pela tua aplicação
Ferramentas nativasweb_search, code_interpreter, geração de imagemNenhuma nativa; integras tudo manualmente
Suporte MCPIntegrado diretamente na APIRequer configuração adicional por framework
Flexibilidade de orquestração multiagenteLimitada a um agente por conversaAlta, com grafos e equipas de agentes
Curva de aprendizagemBaixa para casos simplesMais elevada, mas mais controlo

Na prática, a escolha depende da complexidade do teu caso de uso. Para um único agente com ferramentas bem definidas, a Agents API poupa-te bastante código de encanamento. Para sistemas com vários agentes especializados a colaborar entre si, um framework de orquestração como os que já analisámos continua a fazer mais sentido. Se já usas a API Mistral para RAG ou correste modelos Mistral localmente com o nosso tutorial de Mistral com Ollama, a Agents API é o passo natural seguinte quando precisas de comportamento agêntico em vez de respostas isoladas.

Segurança: cuidados a ter com agentes autónomos

Dar a um modelo a capacidade de executar código e chamar funções internas levanta questões de segurança que não existem numa API de chat simples. O código executado pelo code_interpreter corre num sandbox gerido pela Mistral, isolado do teu ambiente, o que limita o risco direto ao teu sistema. O risco maior está nas tuas próprias funções personalizadas: se uma função tiver acesso de escrita a uma base de dados, um utilizador malicioso pode tentar manipular a conversa (via injeção de prompt) para levar o agente a chamar essa função com parâmetros indevidos.

Como boas práticas mínimas, restringe cada função personalizada ao mínimo de permissões necessárias (evita funções genéricas de “executar query SQL”), valida sempre os parâmetros recebidos antes de os usares numa chamada real, e regista todas as chamadas de função com o respetivo utilizador de origem para auditoria posterior. Para agentes expostos publicamente, considera também limitar o número de chamadas de ferramenta por conversa, evitando que um utilizador force o agente a um ciclo caro de pesquisas ou execuções repetidas. A comunidade que já analisou este agente (via o tutorial de tool-calling com Qwen no caso de outro fornecedor) nota que este tipo de risco não é exclusivo da Mistral: qualquer sistema de function calling exige as mesmas cautelas de validação de entradas.

Perguntas frequentes sobre a Mistral Agents API

A Mistral Agents API é gratuita?
Não. É faturada por tokens de entrada e saída do modelo escolhido, mais um custo adicional por chamada de conector (pesquisa web, execução de código ou geração de imagem). É preciso crédito ativo na conta da plataforma Mistral para a usar.

Que modelos Mistral suportam a Agents API?
A API funciona com os modelos de chat e visão disponíveis na tua conta Mistral; a cobertura do lançamento destacou o Mistral Medium 3 como opção central para orquestração de agentes, mas o modelo é configurável por agente conforme a tua necessidade e orçamento.

Qual é a diferença entre a Agents API e a API de chat completions normal?
A API de completions é sem estado: tens de reenviar todo o histórico a cada pedido. A Agents API guarda o estado da conversa no servidor, suporta ferramentas nativas como pesquisa web e execução de código, e integra o protocolo MCP diretamente.

Posso usar a Agents API com JavaScript ou apenas Python?
A Mistral disponibiliza um SDK oficial para Node.js e browser através do pacote npm @mistralai/mistralai, além do SDK Python usado neste tutorial, pelo que dá para construir agentes em ambos os ecossistemas.

Como funciona o MCP na prática com a Mistral?
Ligas o teu agente a um servidor MCP através do URL desse servidor na definição de ferramentas do agente. O servidor MCP expõe as suas próprias ferramentas de forma padronizada, e o agente Mistral pode chamá-las tal como chamaria uma função personalizada normal.

O código executado pelo interpretador de código é seguro?
Corre num sandbox isolado gerido pela Mistral, separado do teu ambiente local ou de produção. Ainda assim, evita passar dados sensíveis para dentro do código executado por essa ferramenta, já que a execução acontece num ambiente de terceiros.

Consigo migrar um agente construído noutro framework para a Mistral Agents API?
Sim, mas não automaticamente. Tens de recriar a definição de ferramentas e instruções no formato específico da Agents API. A lógica de negócio das tuas funções personalizadas (a parte que efetivamente consulta bases de dados ou sistemas internos) pode normalmente ser reaproveitada quase sem alterações.

A Agents API substitui a necessidade de um framework como LangGraph ou CrewAI?
Para um único agente com ferramentas bem definidas, sim, substitui grande parte do código de encanamento que esses frameworks resolvem. Para sistemas com múltiplos agentes especializados a colaborar numa tarefa complexa, um framework de orquestração dedicado continua a oferecer mais controlo sobre o fluxo entre agentes.