베타 대화 엔드포인트

베타 대화 엔드포인트 (Beta Conversations Endpoints)

(beta) Conversations API입니다. 대화(conversation)를 만들고, 이어가고, 이력·메시지를 조회하며, 특정 지점부터 다시 시작하는 멀티턴 대화 엔드포인트예요.

출처: 문서

본문

기본 모델이나 에이전트로 이어지는 대화를 관리하는 베타 API예요. 대화를 시작하면 conversation_id가 반환되고, 그 ID로 계속 메시지를 붙여가며 이력과 메시지를 확인할 수 있답니다. 스트리밍 변형도 지원해요.

GET /v1/conversations — List all created conversations (대화 목록)

생성 시각순으로 정렬된 대화 엔티티 목록을 가져옵니다.

쿼리 파라미터:

page#integer
page_size#integer
metadata#map<any>|null

응답 (200): 타입 array<ModelConversation|AgentConversation>.

ModelConversation — {object}
AgentConversation — {object}

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

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

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.list(page=0, page_size=100)

    # Handle response
    print(res)

curl:

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

응답 예시 (200):

[
  {
    "created_at": "2025-12-17T10:25:07.818693Z",
    "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
    "model": "mistral-small-latest",
    "updated_at": "2025-12-17T10:41:03.469341Z"
  }
]

POST /v1/conversations — Create a conversation and append entries to it (대화 생성)

기본 모델 또는 에이전트로 새 대화를 만들고 엔트리를 추가합니다. 완성(completion)과 도구 실행이 진행되고 그 응답이 대화에 추가돼요. 반환된 conversation_id로 대화를 계속 이어가세요.

요청 본문:

inputs#string|array<MessageInputEntry|MessageOutputEntry|FunctionResultEntry|FunctionCallEntry|ToolExecutionEntry|AgentHandoffEntry> (필수) — 대화에 넣을 입력.
model#string|null — 기본 모델.
agent_id#string|null, agent_version#`string|integer|null
instructions#string|null
name#string|null, description#string|null
completion_args#CompletionArgs — 완성 API에서 허용된 화이트리스트 인자.
tools#array<FunctionTool|WebSearchTool|WebSearchPremiumTool|CodeInterpreterTool|ImageGenerationTool|DocumentLibraryTool|CustomConnector>|null
guardrails#array<GuardrailConfig>|null
metadata#map<any>|null
handoff_execution#"client"|"server" — 핸드오프 실행 위치.
store#boolean|null — 서버에 저장할지.
stream#boolean — 기본값 false.

응답 필드 (200 Successful Response):

conversation_id#string (필수)
outputs#array<MessageOutputEntry|ToolExecutionEntry|FunctionCallEntry|AgentHandoffEntry> (필수) — 생성된 출력 엔트리.
usage#ConversationUsageInfo (필수)
guardrails#array<map<any>>|null
object#string — 기본값 "conversation.response".

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.conversations.start({
    inputs: "<value>",
    completionArgs: {
      responseFormat: {
        type: "text",
      },
    },
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.start(inputs="<value>", completion_args={
        "response_format": {
            "type": "text",
        },
    })

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/conversations \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "inputs": "Example input."
}'

응답 예시 (200):

{
  "conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "outputs": [
    {
      "content": "Example content."
    }
  ],
  "usage": {}
}

GET /v1/conversations/{conversation_id} — Retrieve a conversation information (대화 조회)

conversation_id로 대화 엔티티와 그 속성을 가져옵니다.

경로 파라미터:

conversation_id#string (필수) — 메타데이터를 가져올 대화의 ID.

응답 (200): 타입 ModelConversation|AgentConversation.

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.conversations.get({
    conversationId: "<id>",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.get(conversation_id="<id>")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/conversations/{conversation_id} \
 -X GET \
 -H 'Authorization: Bearer ***'

POST /v1/conversations/{conversation_id} — Append new entries to an existing conversation (엔트리 추가)

대화 이력과 사용자 엔트리로 완성을 실행하고, 새로 생성된 엔트리를 반환합니다.

경로 파라미터:

conversation_id#string (필수) — 엔트리를 추가할 대화의 ID.

요청 본문:

inputs#string|array<...> — 이어 붙일 입력.
completion_args#CompletionArgs
handoff_execution#"client"|"server" — 기본값 "server".
store#boolean — 기본값 true. 결과를 서버에 저장할지.
stream#boolean — 기본값 false.
tool_confirmations#array<ToolCallConfirmation>|null

응답 필드 (200 Successful Response): 시작 응답과 동일한 conversation_id, outputs, usage, guardrails, object 필드.

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.conversations.append({
    conversationId: "<id>",
    conversationAppendRequest: {
      completionArgs: {
        responseFormat: {
          type: "text",
        },
      },
    },
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.append(conversation_id="<id>", store=True, handoff_execution="server", completion_args={
        "response_format": {
            "type": "text",
        },
    })

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/conversations/{conversation_id} \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

DELETE /v1/conversations/{conversation_id} — Delete a conversation (대화 삭제)

conversation_id로 대화를 삭제합니다.

경로 파라미터:

conversation_id#string (필수)

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  await mistral.beta.conversations.delete({
    conversationId: "<id>",
  });

}

run();

Python:

from mistralai.client import Mistral
import os

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

    mistral.beta.conversations.delete(conversation_id="<id>")

    # Use the SDK ...

curl:

curl https://api.mistral.ai/v1/conversations/{conversation_id} \
 -X DELETE \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json'

GET /v1/conversations/{conversation_id}/history — Retrieve all entries in a conversation (대화 이력)

대화에 속한 모든 엔트리를 가져옵니다. 엔트리는 추가된 순서대로 정렬되며, 메시지·커넥터·function_call이 될 수 있어요.

경로 파라미터:

conversation_id#string (필수) — 엔트리를 가져올 대화의 ID.

응답 필드 (200 Successful Response):

conversation_id#string (필수)
entries#array<MessageInputEntry|MessageOutputEntry|FunctionResultEntry|FunctionCallEntry|ToolExecutionEntry|AgentHandoffEntry> (필수)
object#string — 기본값 "conversation.history".

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.conversations.getHistory({
    conversationId: "<id>",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.get_history(conversation_id="<id>")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/conversations/{conversation_id}/history \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "entries": [
    {
      "content": "Example content.",
      "role": "assistant"
    }
  ]
}

GET /v1/conversations/{conversation_id}/messages — Retrieve all messages in a conversation (대화 메시지)

대화에 속한 모든 메시지를 가져옵니다. 엔트리 조회와 비슷하지만 메시지만 필터링해서 보여줘요.

경로 파라미터:

conversation_id#string (필수)

응답 필드 (200 Successful Response):

conversation_id#string (필수)
messages#array<MessageInputEntry|MessageOutputEntry> (필수)
object#string — 기본값 "conversation.messages".

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.conversations.getMessages({
    conversationId: "<id>",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.get_messages(conversation_id="<id>")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/conversations/{conversation_id}/messages \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "conversation_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "messages": [
    {
      "content": "Example content.",
      "role": "assistant"
    }
  ]
}

POST /v1/conversations/{conversation_id}/restart — Restart a conversation starting from a given entry (대화 다시 시작)

conversation_id와 엔트리 id로 그 지점부터 대화를 다시 만들고 완성을 실행합니다. 새 대화와 새 엔트리가 반환돼요.

경로 파라미터:

conversation_id#string (필수) — 다시 시작할 원래 대화의 ID.

요청 본문:

from_entry_id#string (필수) — 시작 지점 엔트리.
agent_version#string|integer|null — 재시작 시 사용할 에이전트 버전. 없으면 현재 버전 사용.
completion_args#CompletionArgs
inputs#string|array<...>
guardrails#array<GuardrailConfig>|null
metadata#map<any>|null — 대화용 커스텀 메타데이터.
handoff_execution#"client"|"server" — 기본값 "server".
store#boolean — 기본값 true.
stream#boolean — 기본값 false.

응답 필드 (200 Successful Response): 시작 응답과 동일한 conversation_id, outputs, usage, guardrails, object 필드.

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.conversations.restart({
    conversationId: "<id>",
    conversationRestartRequest: {
      completionArgs: {
        responseFormat: {
          type: "text",
        },
      },
      fromEntryId: "<id>",
    },
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.restart(conversation_id="<id>", from_entry_id="<id>", store=True, handoff_execution="server", completion_args={
        "response_format": {
            "type": "text",
        },
    })

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/conversations/{conversation_id}/restart \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "from_entry_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'

POST /v1/conversations#stream — Create a conversation and append entries to it (stream)

스트리밍 방식으로 대화를 만들고 엔트리를 추가합니다. 요청 필드는 일반 생성과 동일하며 stream의 기본값이 true예요.

응답 (200): 타입 event-stream<ConversationEvents>.

ConversationEvents — {object}

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.conversations.startStream({
    inputs: [
      {
        object: "entry",
        type: "agent.handoff",
        previousAgentId: "<id>",
        previousAgentName: "<value>",
        nextAgentId: "<id>",
        nextAgentName: "<value>",
      },
    ],
    completionArgs: {
      responseFormat: {
        type: "text",
      },
    },
  });

  for await (const event of result) {
    console.log(event);
  }
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.start_stream(inputs=[
        {
            "object": "entry",
            "type": "function.result",
            "tool_call_id": "<id>",
            "result": "<value>",
        },
    ], completion_args={
        "response_format": {
            "type": "text",
        },
    })

    with res as event_stream:
        for event in event_stream:
            # handle event
            print(event, flush=True)

curl:

curl https://api.mistral.ai/v1/conversations#stream \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "inputs": "Example input."
}'

POST /v1/conversations/{conversation_id}#stream — Append new entries (stream)

스트리밍 방식으로 기존 대화에 엔트리를 추가합니다. append와 동일한 필드이며 stream 기본값이 true예요.

응답 (200): 타입 event-stream<ConversationEvents>.

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.conversations.appendStream({
    conversationId: "<id>",
    conversationAppendStreamRequest: {
      completionArgs: {
        responseFormat: {
          type: "text",
        },
      },
    },
  });

  for await (const event of result) {
    console.log(event);
  }
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.append_stream(conversation_id="<id>", store=True, handoff_execution="server", completion_args={
        "response_format": {
            "type": "text",
        },
    })

    with res as event_stream:
        for event in event_stream:
            # handle event
            print(event, flush=True)

curl:

curl https://api.mistral.ai/v1/conversations/{conversation_id}#stream \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

POST /v1/conversations/{conversation_id}/restart#stream — Restart a conversation (stream)

스트리밍 방식으로 특정 지점부터 대화를 다시 시작합니다. restart와 동일한 필드이며 stream 기본값이 true예요.

응답 (200): 타입 event-stream<ConversationEvents>.

TypeScript:

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

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.conversations.restartStream({
    conversationId: "<id>",
    conversationRestartStreamRequest: {
      completionArgs: {
        responseFormat: {
          type: "text",
        },
      },
      fromEntryId: "<id>",
    },
  });

  for await (const event of result) {
    console.log(event);
  }
}

run();

Python:

from mistralai.client import Mistral
import os

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

    res = mistral.beta.conversations.restart_stream(conversation_id="<id>", from_entry_id="<id>", store=True, handoff_execution="server", completion_args={
        "response_format": {
            "type": "text",
        },
    })

    with res as event_stream:
        for event in event_stream:
            # handle event
            print(event, flush=True)

curl:

curl https://api.mistral.ai/v1/conversations/{conversation_id}/restart#stream \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "from_entry_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'

더 알아보기 (Learn more)

Beta Conversations Endpoints — 공식 API 문서
Agents — 에이전트 안내