openapi: 3.1.0
info:
  title: Mistral AI Agents API
  description: >-
    Agent completions API for building AI agents that can handle complex tasks,
    maintain context, coordinate multiple actions, and use tools including
    function calling. Agents are created and configured via the Mistral
    platform and invoked through this API.
  version: '1.0'
  contact:
    name: Mistral AI Support
    url: https://docs.mistral.ai/
    email: support@mistral.ai
  termsOfService: https://mistral.ai/terms/
externalDocs:
  description: Mistral AI Agents API Documentation
  url: https://docs.mistral.ai/api/endpoint/agents
servers:
  - url: https://api.mistral.ai/v1
    description: Mistral AI Production
tags:
  - name: Agents
    description: Agent completion operations
security:
  - bearerAuth: []
paths:
  /agents/completions:
    post:
      operationId: createAgentCompletion
      summary: Mistral AI Create an agent completion
      description: >-
        Generate a response from a configured agent. The agent is identified
        by its agent_id and can use tools, maintain conversation context,
        and follow custom instructions defined in the platform.
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCompletionRequest'
      responses:
        '200':
          description: Agent completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCompletionResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentCompletionStreamResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Agent not found
        '429':
          description: Rate limit exceeded
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Mistral AI API key passed as a Bearer token
  schemas:
    AgentCompletionRequest:
      type: object
      required:
        - agent_id
        - messages
      properties:
        agent_id:
          type: string
          description: The ID of the agent to use, created on the Mistral platform
        messages:
          type: array
          description: List of messages comprising the conversation
          items:
            $ref: '#/components/schemas/Message'
        max_tokens:
          type: integer
          minimum: 1
          description: Maximum number of tokens to generate
        stream:
          type: boolean
          default: false
          description: Whether to stream partial message deltas
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: Stop sequences
        random_seed:
          type: integer
          description: Random seed for deterministic generation
        response_format:
          type: object
          properties:
            type:
              type: string
              enum:
                - text
                - json_object
        tool_choice:
          type: string
          enum:
            - auto
            - none
            - any
          default: auto
          description: Controls how the agent uses tools
    Message:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
            - tool
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
        tool_call_id:
          type: string
    ToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
    AgentCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
            - chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        usage:
          $ref: '#/components/schemas/Usage'
    AgentCompletionStreamResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
            - chat.completion.chunk
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              delta:
                $ref: '#/components/schemas/Message'
              finish_reason:
                type:
                  - string
                  - 'null'
    Choice:
      type: object
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/Message'
        finish_reason:
          type: string
          enum:
            - stop
            - length
            - tool_calls
            - model_length
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer