The ID of the agent to use for this completion.
Deprecated Agents Endpoints
Agents API.
Examples
Real world code examples
Agents Completion
POST /v1/agents/completions#
Agents Completion
frequency_penalty#
The frequency_penalty penalizes the repetition of words based on their frequency in the generated text. A higher frequency penalty discourages the model from repeating words that have already appeared frequently in the output, promoting diversity and reducing repetition.
guardrails#
max_tokens#
The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens cannot exceed the model's context length.
The prompt(s) to generate completions for, encoded as a list of dict with role and content.
metadata#
n#
Number of completions to return for each request, input tokens are only billed once.
parallel_tool_calls#
Default Value: true
prediction#
Enable users to specify an expected completion, optimizing response times by leveraging known or predictable content.
presence_penalty#
The presence_penalty determines how much the model penalizes the repetition of words or phrases. A higher presence penalty encourages the model to use a wider variety of words and phrases, making the output more diverse and creative.
prompt_cache_key#
A cache key for prompt caching. Use the same key for requests with shared prompt prefixes, such as multi-turn conversations or repeated system prompts, to increase cache hits. Cached tokens are billed at 10% of the standard input token price.
prompt_mode#
Available options to the prompt_mode argument on the chat completion endpoint. Values represent high-level intent. Assignment to actual SPs is handled internally. System prompt may include knowledge cutoff date, model capabilities, tone to use, safety guidelines, etc.
random_seed#
The seed to use for random sampling. If set, different calls will generate deterministic results.
reasoning_effort#
response_format#
Specify the format that the model must output. By default it will use { "type": "text" }. Setting to { "type": "json_object" } enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to { "type": "json_schema" } enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide.
stop#
Stop generation if this token is detected. Or if one of these tokens is detected when providing an array
stream#
Default Value: false
Whether to stream back partial progress. If set, tokens will be sent as data-only server-side events as they become available, with the stream terminated by a data: [DONE] message. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.
tool_choice#
Playground
Test the endpoints live
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.agents.complete({
messages: [
{
role: "user",
content: "Who is the best French painter? Answer in one short sentence.",
},
],
responseFormat: {
type: "text",
},
agentId: "<id>",
});
console.log(result);
}
run();
import { Mistral } from "@mistralai/mistralai";
const mistral = new Mistral({
apiKey: "MISTRAL_API_KEY",
});
async function run() {
const result = await mistral.agents.complete({
messages: [
{
role: "user",
content: "Who is the best French painter? Answer in one short sentence.",
},
],
responseFormat: {
type: "text",
},
agentId: "<id>",
});
console.log(result);
}
run();
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.agents.complete(messages=[
{
"role": "user",
"content": "Who is the best French painter? Answer in one short sentence.",
},
], agent_id="<id>", stream=False, response_format={
"type": "text",
})
# Handle response
print(res)
from mistralai.client import Mistral
import os
with Mistral(
api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:
res = mistral.agents.complete(messages=[
{
"role": "user",
"content": "Who is the best French painter? Answer in one short sentence.",
},
], agent_id="<id>", stream=False, response_format={
"type": "text",
})
# Handle response
print(res)
curl https://api.mistral.ai/v1/agents/completions \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"agent_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"messages": [
{
"content": "Example content."
}
]
}'curl https://api.mistral.ai/v1/agents/completions \
-X POST \
-H 'Authorization: Bearer YOUR_APIKEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"agent_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
"messages": [
{
"content": "Example content."
}
]
}'200
{
"id": "cf79f7daaee244b1a0ae5c7b1444424a",
"object": "chat.completion",
"model": "mistral-medium-latest",
"usage": {
"prompt_tokens": 24,
"completion_tokens": 27,
"total_tokens": 51,
"prompt_audio_seconds": {}
},
"created": 1759500534,
"choices": [
{
"index": 0,
"message": {
"content": "Arrr, the scallywag Claude Monet be the finest French painter to ever splash colors on a canvas, savvy?",
"tool_calls": null,
"prefix": false,
"role": "assistant"
},
"finish_reason": "stop"
}
]
}{
"id": "cf79f7daaee244b1a0ae5c7b1444424a",
"object": "chat.completion",
"model": "mistral-medium-latest",
"usage": {
"prompt_tokens": 24,
"completion_tokens": 27,
"total_tokens": 51,
"prompt_audio_seconds": {}
},
"created": 1759500534,
"choices": [
{
"index": 0,
"message": {
"content": "Arrr, the scallywag Claude Monet be the finest French painter to ever splash colors on a canvas, savvy?",
"tool_calls": null,
"prefix": false,
"role": "assistant"
},
"finish_reason": "stop"
}
]
}