Beta Agents Endpoints

(beta) Agents API

List agent entities.

GET /v1/agents

Retrieve a list of agent entities sorted by creation time.

200

Response Type

array<Agent>

Successful Response

Agent

{object}

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.beta.agents.list({});

  console.log(result);
}

run();

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  const result = await mistral.beta.agents.list({});

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.list(page=0, page_size=20)

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.list(page=0, page_size=20)

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/agents \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

[
  {
    "created_at": "2025-10-07T20:56:01.974Z",
    "id": "ipsum eiusmod",
    "model": "consequat do",
    "name": "reprehenderit ut dolore",
    "updated_at": "2025-10-07T20:56:01.974Z",
    "version": 87
  }
]

[
  {
    "created_at": "2025-10-07T20:56:01.974Z",
    "id": "ipsum eiusmod",
    "model": "consequat do",
    "name": "reprehenderit ut dolore",
    "updated_at": "2025-10-07T20:56:01.974Z",
    "version": 87
  }
]

Create a agent that can be used within a conversation.

POST /v1/agents

Create a new agent giving it instructions, tools, description. The agent is then available to be used as a regular assistant in a conversation or as part of an agent pool from which it can be used.

200

Successful Response

completion_args

CompletionArgs

White-listed arguments from the completion API

created_at

*date-time

description

string|null

handoffs

array<string>|null

id

*string

instructions

string|null

Instruction prompt the model will follow during the conversation.

model

*string

name

*string

object

"agent"

Default Value: "agent"

tools

List of tools which are available to the model during the conversation.

updated_at

*date-time

version

*integer

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.beta.agents.create({
    model: "LeBaron",
    name: "<value>",
  });

  console.log(result);
}

run();

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  const result = await mistral.beta.agents.create({
    model: "LeBaron",
    name: "<value>",
  });

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.create(model="LeBaron", name="<value>")

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.create(model="LeBaron", name="<value>")

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents \
 -X POST \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -d '{
  "model": "ipsum eiusmod",
  "name": "consequat do"
}'

curl https://api.mistral.ai/v1/agents \
 -X POST \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -d '{
  "model": "ipsum eiusmod",
  "name": "consequat do"
}'

200

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

Retrieve an agent entity.

GET /v1/agents/{agent_id}

Given an agent retrieve an agent entity with its attributes.

200

Successful Response

completion_args

CompletionArgs

White-listed arguments from the completion API

created_at

*date-time

description

string|null

handoffs

array<string>|null

id

*string

instructions

string|null

Instruction prompt the model will follow during the conversation.

model

*string

name

*string

object

"agent"

Default Value: "agent"

tools

List of tools which are available to the model during the conversation.

updated_at

*date-time

version

*integer

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.beta.agents.get({
    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.beta.agents.get({
    agentId: "<id>",
  });

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.get(agent_id="<id>")

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.get(agent_id="<id>")

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X GET \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

Delete an agent entity.

DELETE /v1/agents/{agent_id}

Playground

Test the endpoints live

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X DELETE \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X DELETE \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

Update an agent entity.

PATCH /v1/agents/{agent_id}

Update an agent attributes and create a new version.

200

Successful Response

completion_args

CompletionArgs

White-listed arguments from the completion API

created_at

*date-time

description

string|null

handoffs

array<string>|null

id

*string

instructions

string|null

Instruction prompt the model will follow during the conversation.

model

*string

name

*string

object

"agent"

Default Value: "agent"

tools

List of tools which are available to the model during the conversation.

updated_at

*date-time

version

*integer

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.beta.agents.update({
    agentId: "<id>",
    agentUpdateRequest: {},
  });

  console.log(result);
}

run();

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  const result = await mistral.beta.agents.update({
    agentId: "<id>",
    agentUpdateRequest: {},
  });

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.update(agent_id="<id>")

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.update(agent_id="<id>")

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -d '{}'

curl https://api.mistral.ai/v1/agents/{agent_id} \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE' \
 -d '{}'

200

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

Update an agent version.

PATCH /v1/agents/{agent_id}/version

Switch the version of an agent.

200

Successful Response

completion_args

CompletionArgs

White-listed arguments from the completion API

created_at

*date-time

description

string|null

handoffs

array<string>|null

id

*string

instructions

string|null

Instruction prompt the model will follow during the conversation.

model

*string

name

*string

object

"agent"

Default Value: "agent"

tools

List of tools which are available to the model during the conversation.

updated_at

*date-time

version

*integer

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.beta.agents.updateVersion({
    agentId: "<id>",
    version: 157995,
  });

  console.log(result);
}

run();

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: "MISTRAL_API_KEY",
});

async function run() {
  const result = await mistral.beta.agents.updateVersion({
    agentId: "<id>",
    version: 157995,
  });

  console.log(result);
}

run();

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.update_version(agent_id="<id>", version=157995)

    # Handle response
    print(res)

from mistralai import Mistral
import os


with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.agents.update_version(agent_id="<id>", version=157995)

    # Handle response
    print(res)

curl https://api.mistral.ai/v1/agents/{agent_id}/version \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

curl https://api.mistral.ai/v1/agents/{agent_id}/version \
 -X PATCH \
 -H 'Authorization: Bearer YOUR_APIKEY_HERE'

200

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

{
  "created_at": "2025-10-07T20:56:01.974Z",
  "id": "ipsum eiusmod",
  "model": "consequat do",
  "name": "reprehenderit ut dolore",
  "updated_at": "2025-10-07T20:56:01.974Z",
  "version": 87
}

Beta Agents Endpoints

Examples

GET /v1/agents

Parameters

page

page_size

Agent

Playground

POST /v1/agents

Request Body

completion_args

description

handoffs

instructions

model

name

tools

completion_args

created_at

description

handoffs

id

instructions

model

name

object

tools

updated_at

version

Playground

GET /v1/agents/{agent_id}

Parameters

agent_id

completion_args

created_at

description

handoffs

id

instructions

model

name

object

tools

updated_at

version

Playground

DELETE /v1/agents/{agent_id}

Parameters

agent_id

Playground

PATCH /v1/agents/{agent_id}

Parameters

agent_id

Request Body

completion_args

description

handoffs

instructions

model

name

tools

completion_args

created_at

description

handoffs

id

instructions

model

name

object

tools

updated_at

version

Playground

PATCH /v1/agents/{agent_id}/version

Parameters

agent_id

version

completion_args

created_at