Mistral — Agents API

Point Chamade at a Mistral Agent — one you already built in la Plateforme, or a fresh one Chamade creates for you. Auth is a single API key: no OAuth, no infra to run.

What it is

Chamade talks to Mistral's native Agents API (stateful Conversations). A human messages your agent, Chamade calls Mistral with the message, and delivers whatever the agent replies. Conversation memory is kept natively by Mistral — Chamade never re-stuffs history.

Two shapes, both under the Mistral preset:

Create new — Chamade mints an ag_* for you and owns its persona (the system prompt) and model.
Pick existing — reference an ag_* you already built in the console (its own instructions, model, tools). Chamade invokes it as-is.

Setup

Grab a Mistral API key from console.mistral.ai → API Keys.
In your dashboard → an agent → pick the Mistral preset.
Paste the key, then either Browse your existing agents and pick one, or switch to Create new and choose a model (e.g. mistral-large-latest). Save.

Testing with your API key

The key is the only credential — paste it and Chamade validates it for you, no separate test step to run:

Browse lists your account's ag_* agents. If the key is wrong you get a clear "Mistral rejected the API key"; if it works you see your agents (an empty list just means you have none yet — use Create new).
While browsing, Chamade also probes whether the key can create connectors (its MCP read backstop — see below) and shows a banner telling you which mode you'll get. The key is sent in the request body only — never logged, never in a URL.
On save, Chamade runs a cheap healthcheck (GET /v1/models) against the key.
To confirm end-to-end, use Test DM / Ping in the dashboard, or just message the agent on a connected platform.

Editing later

Re-open the agent and leave the key field blank to keep the stored one — you only re-paste to rotate it. Changing the model or system prompt of a Chamade-created agent transparently re-creates the underlying ag_*; a picked agent is never mutated that way.

Acting & reading

Two complementary mechanisms — the same invariant as every other Chamade provider, act with XML, read with MCP:

Act via the XML convention — the agent's reply text carries inline tags (<write>, <say>, <dm>, <call_join>, <accept/>…) which Chamade parses and executes deterministically. Works for both shapes, zero setup. Each event already carries an [agent context] line with your accounts, so cross-target actions need no lookup.
Read via Chamade's MCP (optional, off by default) — tick "Enable MCP read backstop" in the picker and Chamade registers its hosted MCP at https://mcp.chamade.io/mcp/ as a Mistral Connector attached to your agent. The model can then look things up mid-reasoning (chamade_account, chamade_inbox, chamade_call_status, file upload URLs for generated files). Most DM agents don't need it — everything they act on is already in the event's [agent context] line — so it's opt-in. The suggested system prompt spells out "use the tools to look up, act with the XML tags, never both" so nothing fires twice.

Why the agent doesn't act through the MCP tools

Mistral runs Connector tools server-side, so a model that says it sent a message without actually calling the tool would silently drop the action. Acting therefore stays on the XML convention, which Chamade executes itself — the model emits a tag or it doesn't. The MCP is purely a read backstop.

The `personal_and_shared` scope (for MCP reads)

The optional MCP read backstop needs a Mistral key with the personal_and_shared primitive access scope (a standard console key without it gets a 403 on connector creation). Chamade probes this at browse time and the picker tells you whether the box is usable:

Key has the scope → the "Enable MCP read backstop" box works; tick it to attach the connector.
Key lacks it → the box is inert (ticking it does nothing); the agent still works fully — it acts and replies via XML with no MCP lookups. Paste a scoped key later if you want the backstop.

For a picked agent, attaching the connector adds one tool to your ag_* (a consented mutation) without touching its instructions; on a created agent it's wired in at creation. Either way it's removed again if you rotate the agent's internal bearer or delete the agent.

Memory & context

Mistral keeps the full conversation server-side per Conversation — Chamade maps each of your conversations to one and only ever appends the new message. There's no truncation or compaction: a very long session eventually hits Mistral's hard context limit and returns an error, which Chamade surfaces back on the originating channel. The system prompt persists across turns (re-applied every turn for a created agent; carried in the retained history for a picked one).

Good to know

The agent needs ≥1 platform account attached in Chamade, or it has nothing to talk to.
The base endpoint is https://api.mistral.ai by default; override it only if you front Mistral with a compatible proxy.
Picked-agent persona: if you give the console agent its own instructions, keep them compatible with emitting the XML tags (Chamade folds its output convention into the first message).