Mistral AI Agents API

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
servers:
- url: https://api.mistral.ai/v1
  description: Mistral AI Production Server
security:
- bearerAuth: []
tags:
- name: Agents
  description: Endpoints for interacting with Mistral AI agents that can handle complex tasks with tool use and multi-step reasoning.
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:
  schemas:
    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
    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'
    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.
    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.
    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.
    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.
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
externalDocs:
  description: Mistral AI Agents Documentation
  url: https://docs.mistral.ai/api/endpoint/agents