# Agents ## Overview Agents API. ### Available Operations * [complete](#complete) - Agents Completion * [stream](#stream) - Stream Agents completion ## complete Agents Completion ### Example Usage ```python 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="", stream=False, response_format={ "type": "text", }) # Handle response print(res) ``` ### Parameters | Parameter | Type | Required | Description | Example | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `messages` | List[[models.AgentsCompletionRequestMessage](../../models/agentscompletionrequestmessage.md)] | :heavy_check_mark: | The prompt(s) to generate completions for, encoded as a list of dict with role and content. | [
{
"role": "user",
"content": "Who is the best French painter? Answer in one short sentence."
}
] | | `agent_id` | *str* | :heavy_check_mark: | The ID of the agent to use for this completion. | | | `max_tokens` | *OptionalNullable[int]* | :heavy_minus_sign: | 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. | | | `stream` | *Optional[bool]* | :heavy_minus_sign: | 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. | | | `stop` | [OptionalNullable[models.AgentsCompletionRequestStop]](../../models/agentscompletionrequeststop.md) | :heavy_minus_sign: | Stop generation if this token is detected. Or if one of these tokens is detected when providing an array | | | `random_seed` | *OptionalNullable[int]* | :heavy_minus_sign: | The seed to use for random sampling. If set, different calls will generate deterministic results. | | | `metadata` | Dict[str, *Any*] | :heavy_minus_sign: | N/A | | | `response_format` | [Optional[models.ResponseFormat]](../../models/responseformat.md) | :heavy_minus_sign: | 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. | **Example 1:** {
"type": "text"
}
**Example 2:** {
"type": "json_object"
}
**Example 3:** {
"type": "json_schema",
"json_schema": {
"schema": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"authors": {
"items": {
"type": "string"
},
"title": "Authors",
"type": "array"
}
},
"required": [
"name",
"authors"
],
"title": "Book",
"type": "object",
"additionalProperties": false
},
"name": "book",
"strict": true
}
} | | `tools` | List[[models.AgentsCompletionRequestTool](../../models/agentscompletionrequesttool.md)] | :heavy_minus_sign: | N/A | | | `tool_choice` | [Optional[models.AgentsCompletionRequestToolChoice]](../../models/agentscompletionrequesttoolchoice.md) | :heavy_minus_sign: | N/A | | | `presence_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | 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. | | | `frequency_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | 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. | | | `min_tokens` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | | `repetition_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | N/A | | | `top_k` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | | `logprobs` | *OptionalNullable[bool]* | :heavy_minus_sign: | N/A | | | `top_logprobs` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | | `prompt_logprobs` | *OptionalNullable[bool]* | :heavy_minus_sign: | N/A | | | `top_prompt_logprobs` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | | `n` | *OptionalNullable[int]* | :heavy_minus_sign: | Number of completions to return for each request, input tokens are only billed once. | | | `prediction` | [Optional[models.Prediction]](../../models/prediction.md) | :heavy_minus_sign: | Enable users to specify an expected completion, optimizing response times by leveraging known or predictable content. | | | `parallel_tool_calls` | *Optional[bool]* | :heavy_minus_sign: | N/A | | | `reasoning_effort` | [OptionalNullable[models.ReasoningEffort]](../../models/reasoningeffort.md) | :heavy_minus_sign: | N/A | | | `prompt_mode` | [OptionalNullable[models.MistralPromptMode]](../../models/mistralpromptmode.md) | :heavy_minus_sign: | Allows toggling between the reasoning mode and no system prompt. When set to `reasoning` the system prompt for reasoning models will be used. | | | `guardrails` | List[[models.GuardrailConfig](../../models/guardrailconfig.md)] | :heavy_minus_sign: | N/A | | | `prompt_cache_key` | *OptionalNullable[str]* | :heavy_minus_sign: | N/A | | | `service_tier` | [OptionalNullable[models.RequestedServiceTier]](../../models/requestedservicetier.md) | :heavy_minus_sign: | Determines whether to serve the request using priority or standard capacity. | | | `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[models.ChatCompletionResponse](../../models/chatcompletionresponse.md)** ### Errors | Error Type | Status Code | Content Type | | -------------------------- | -------------------------- | -------------------------- | | errors.HTTPValidationError | 422 | application/json | | errors.SDKError | 4XX, 5XX | \*/\* | ## stream Mistral AI provides the ability to stream responses back to a client in order to allow partial results for certain requests. Tokens will be sent as data-only server-sent 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. ### Example Usage ```python from mistralai.client import Mistral import os with Mistral( api_key=os.getenv("MISTRAL_API_KEY", ""), ) as mistral: res = mistral.agents.stream(messages=[ { "role": "user", "content": "Who is the best French painter? Answer in one short sentence.", }, ], agent_id="", stream=True, response_format={ "type": "text", }) with res as event_stream: for event in event_stream: # handle event print(event, flush=True) ``` ### Parameters | Parameter | Type | Required | Description | Example | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `messages` | List[[models.AgentsCompletionStreamRequestMessage](../../models/agentscompletionstreamrequestmessage.md)] | :heavy_check_mark: | The prompt(s) to generate completions for, encoded as a list of dict with role and content. | [
{
"role": "user",
"content": "Who is the best French painter? Answer in one short sentence."
}
] | | `agent_id` | *str* | :heavy_check_mark: | The ID of the agent to use for this completion. | | | `max_tokens` | *OptionalNullable[int]* | :heavy_minus_sign: | 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. | | | `stream` | *Optional[bool]* | :heavy_minus_sign: | N/A | | | `stop` | [OptionalNullable[models.AgentsCompletionStreamRequestStop]](../../models/agentscompletionstreamrequeststop.md) | :heavy_minus_sign: | Stop generation if this token is detected. Or if one of these tokens is detected when providing an array | | | `random_seed` | *OptionalNullable[int]* | :heavy_minus_sign: | The seed to use for random sampling. If set, different calls will generate deterministic results. | | | `metadata` | Dict[str, *Any*] | :heavy_minus_sign: | N/A | | | `response_format` | [Optional[models.ResponseFormat]](../../models/responseformat.md) | :heavy_minus_sign: | 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. | **Example 1:** {
"type": "text"
}
**Example 2:** {
"type": "json_object"
}
**Example 3:** {
"type": "json_schema",
"json_schema": {
"schema": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"authors": {
"items": {
"type": "string"
},
"title": "Authors",
"type": "array"
}
},
"required": [
"name",
"authors"
],
"title": "Book",
"type": "object",
"additionalProperties": false
},
"name": "book",
"strict": true
}
} | | `tools` | List[[models.AgentsCompletionStreamRequestTool](../../models/agentscompletionstreamrequesttool.md)] | :heavy_minus_sign: | N/A | | | `tool_choice` | [Optional[models.AgentsCompletionStreamRequestToolChoice]](../../models/agentscompletionstreamrequesttoolchoice.md) | :heavy_minus_sign: | N/A | | | `presence_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | 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. | | | `frequency_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | 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. | | | `min_tokens` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | | `repetition_penalty` | *OptionalNullable[float]* | :heavy_minus_sign: | N/A | | | `top_k` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | | `logprobs` | *OptionalNullable[bool]* | :heavy_minus_sign: | N/A | | | `top_logprobs` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | | `prompt_logprobs` | *OptionalNullable[bool]* | :heavy_minus_sign: | N/A | | | `top_prompt_logprobs` | *OptionalNullable[int]* | :heavy_minus_sign: | N/A | | | `n` | *OptionalNullable[int]* | :heavy_minus_sign: | Number of completions to return for each request, input tokens are only billed once. | | | `prediction` | [Optional[models.Prediction]](../../models/prediction.md) | :heavy_minus_sign: | Enable users to specify an expected completion, optimizing response times by leveraging known or predictable content. | | | `parallel_tool_calls` | *Optional[bool]* | :heavy_minus_sign: | N/A | | | `reasoning_effort` | [OptionalNullable[models.ReasoningEffort]](../../models/reasoningeffort.md) | :heavy_minus_sign: | N/A | | | `prompt_mode` | [OptionalNullable[models.MistralPromptMode]](../../models/mistralpromptmode.md) | :heavy_minus_sign: | Allows toggling between the reasoning mode and no system prompt. When set to `reasoning` the system prompt for reasoning models will be used. | | | `guardrails` | List[[models.GuardrailConfig](../../models/guardrailconfig.md)] | :heavy_minus_sign: | N/A | | | `prompt_cache_key` | *OptionalNullable[str]* | :heavy_minus_sign: | N/A | | | `service_tier` | [OptionalNullable[models.RequestedServiceTier]](../../models/requestedservicetier.md) | :heavy_minus_sign: | Determines whether to serve the request using priority or standard capacity. | | | `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[Union[eventstreaming.EventStream[models.CompletionEvent], eventstreaming.EventStreamAsync[models.CompletionEvent]]](../../models/.md)** ### Errors | Error Type | Status Code | Content Type | | -------------------------- | -------------------------- | -------------------------- | | errors.HTTPValidationError | 422 | application/json | | errors.SDKError | 4XX, 5XX | \*/\* |