The Mistral AI Agents API provides a dedicated framework for building agentic applications. It complements the Chat Completion API by enabling AI agents to handle complex tasks, maintain context across interactions, and coordinate multiple actions. Developers can create agents with specific configurations, tools, and instructions, making it suitable for enterprise-grade agentic platforms and multi-step workflow automation.
openapi: 3.1.0
info:
title: Mistral AI Agents API
description: >-
The Mistral AI Agents API provides a dedicated framework for building
agentic applications. It complements the Chat Completion API by enabling
AI agents to handle complex tasks, maintain context across interactions,
and coordinate multiple actions. Developers can create agents with
specific configurations, tools, and instructions, making it suitable for
enterprise-grade agentic platforms and multi-step workflow automation.
version: '1.0.0'
contact:
name: Mistral AI Support
url: https://docs.mistral.ai
termsOfService: https://mistral.ai/terms
externalDocs:
description: Mistral AI Agents Documentation
url: https://docs.mistral.ai/api/endpoint/agents
servers:
- url: https://api.mistral.ai/v1
description: Mistral AI Production Server
tags:
- name: Agents
description: >-
Endpoints for interacting with Mistral AI agents that can handle
complex tasks with tool use and multi-step reasoning.
security:
- bearerAuth: []
paths:
/agents/completions:
post:
operationId: createAgentCompletion
summary: Create agent completion
description: >-
Creates a completion using a pre-configured Mistral AI agent. The
agent processes the input messages using its configured tools,
instructions, and model settings. Supports streaming, function
calling, and multi-turn conversations.
tags:
- Agents
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCompletionRequest'
responses:
'200':
description: Successful agent completion response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCompletionResponse'
'400':
description: Bad request due to invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
schemas:
AgentCompletionRequest:
type: object
required:
- agent_id
- messages
properties:
agent_id:
type: string
description: >-
The ID of the agent to use. Agent IDs are created and managed
through the Mistral AI platform.
messages:
type: array
description: >-
A list of messages comprising the conversation so far.
items:
$ref: '#/components/schemas/ChatMessage'
stream:
type: boolean
description: >-
Whether to stream back partial progress as server-sent events.
default: false
max_tokens:
type: integer
description: >-
The maximum number of tokens to generate in the completion.
minimum: 1
stop:
oneOf:
- type: string
- type: array
items:
type: string
description: >-
Stop generation if this token or one of these tokens is detected.
random_seed:
type: integer
description: >-
The seed to use for random sampling for deterministic results.
response_format:
type: object
description: >-
An object specifying the format that the model must output.
properties:
type:
type: string
enum:
- text
- json_object
description: >-
The format type for the response.
tool_choice:
type: string
description: >-
Controls which tool is called by the agent.
enum:
- auto
- none
- any
- required
ChatMessage:
type: object
required:
- role
- content
properties:
role:
type: string
description: >-
The role of the message author.
enum:
- system
- user
- assistant
- tool
content:
oneOf:
- type: string
- type: array
items:
type: object
description: >-
The content of the message.
tool_calls:
type: array
description: >-
Tool calls generated by the agent.
items:
$ref: '#/components/schemas/ToolCall'
tool_call_id:
type: string
description: >-
The ID of the tool call this message is responding to.
ToolCall:
type: object
properties:
id:
type: string
description: >-
The ID of the tool call.
type:
type: string
enum:
- function
description: >-
The type of the tool call.
function:
type: object
properties:
name:
type: string
description: >-
The name of the function to call.
arguments:
type: string
description: >-
The arguments to call the function with, as a JSON string.
AgentCompletionResponse:
type: object
properties:
id:
type: string
description: >-
A unique identifier for the agent completion.
object:
type: string
description: >-
The object type.
enum:
- chat.completion
created:
type: integer
description: >-
The Unix timestamp of when the completion was created.
model:
type: string
description: >-
The model used by the agent for the completion.
choices:
type: array
description: >-
A list of completion choices.
items:
$ref: '#/components/schemas/AgentCompletionChoice'
usage:
$ref: '#/components/schemas/Usage'
AgentCompletionChoice:
type: object
properties:
index:
type: integer
description: >-
The index of the choice.
message:
$ref: '#/components/schemas/ChatMessage'
finish_reason:
type: string
description: >-
The reason the model stopped generating tokens.
enum:
- stop
- length
- tool_calls
- model_length
Usage:
type: object
properties:
prompt_tokens:
type: integer
description: >-
Number of tokens in the prompt.
completion_tokens:
type: integer
description: >-
Number of tokens in the generated completion.
total_tokens:
type: integer
description: >-
Total number of tokens used in the request.
Error:
type: object
properties:
message:
type: string
description: >-
A human-readable error message.
type:
type: string
description: >-
The type of error.
code:
type: integer
description: >-
The HTTP status code.