Mistral API 가이드: Agents·Conversations와 상태 기반 handoff

InYourLeague 리서치 · 2026-09-05

핵심 답변

Mistral은 어시스턴트 구성, 도구 통합, 지속적인 멀티턴 대화 상태 관리를 위해 Agents 및 Conversations 베타 API를 제공합니다. 개발자는 재사용 가능한 Agent를 사전에 정의하거나 개별 모델을 직접 지정하여 독립적인 대화를 시작할 수 있으며 클라우드 저장 비활성화 옵션을 지원합니다. 또한 세션 전반에서 가드레일 자동 적용 및 재정의와 서버 또는 클라이언트 기반 handoff 실행 모드를 유연하게 제공합니다.

핵심 정보 한눈에 보기

오류 유형과 검증

자주 묻는 질문

Agent를 사전에 생성하지 않고도 Conversations API를 사용할 수 있습니까?

네, Agents API와 Conversations API는 완전히 독립적으로 동작합니다. 사전 정의된 Agent 없이도 대화 시작 요청에 model 매개변수를 직접 지정하여 지속적인 대화를 생성하고 관리할 수 있습니다.

handoff_execution 파라미터의 server 모드와 client 모드의 차이는 무엇입니까?

기본값인 server 모드는 handoff 전환을 Mistral 클라우드 서버 내부에서 직접 실행합니다. 반면 client 모드는 handoff가 트리거될 때 제어 응답을 사용자 측에 즉시 반환하여 애플리케이션 로직이 전환을 직접 제어할 수 있도록 합니다.

대화 이력이 클라우드 서버에 저장되지 않도록 옵트아웃하려면 어떻게 설정합니까?

대화를 시작하거나 추가(append)할 때 store=False 파라미터를 전달하면 클라우드 자동 저장 기능이 비활성화되어 새로운 대화 이력이 Mistral 클라우드 서버에 저장되지 않습니다.

Agent에 설정된 안전 가드레일은 대화 세션에 어떻게 적용됩니까?

에이전트 수준에서 정의된 가드레일은 해당 에이전트로 시작된 모든 대화에 자동으로 상속되어 적용됩니다. 모델을 직접 호출하는 대화에서는 POST /v1/conversations의 guardrails 필드를 통해 가드레일을 직접 재정의할 수 있습니다.

Mistral Agent 정의 시 사용할 수 있는 기본 제공 도구(tools)에는 어떤 것들이 있습니까?

사용자 정의 function 호출 외에도 내장 도구인 web_search, web_search_premium, code_interpreter, image_generation, 그리고 커스텀 지식 검색을 위한 document_library 도구를 지원합니다.

출처와 확인 날짜

• 공식 출처
• 최종 확인일: 2026-09-05

상세 가이드

Mistral은 Agents, Conversations, Entries의 세 가지 핵심 객체를 중심으로 에이전트형 애플리케이션 아키텍처를 제공합니다. Agents는 시스템 지침, 모델 선택, 도구 목록 및 샘플링 매개변수와 같은 사전 정의된 구성을 캡슐화합니다. Conversations는 어시스턴트와의 상호작용 이력을 관리하며, 사전 생성된 Agent ID를 참조하거나 개별 모델을 직접 지정하여 독립적으로 시작할 수 있습니다. Entries는 사용자 또는 어시스턴트가 생성하는 개별 액션 단위로 상호작용 이벤트를 보다 유연하고 정밀하게 표현합니다.

이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았습니다. 공식 문서 예제에 등장하는 mistral-medium-latest와 같은 식별자는 고정된 필수값이나 전체 지원 모델 목록이 아니라 단순 예시 선택 항목으로 제공됩니다.

에이전트 정의 및 도구 구성

Mistral 클라이언트(예: client.beta.agents.create)를 통해 에이전트를 생성할 때 개발자는 다음 매개변수를 사전에 구성합니다:

• name: 에이전트의 고유 이름.
• description: 해결해야 할 과제나 사용 사례를 설명하는 설명문.
• model: 채팅 완료에 사용할 모델.
• instructions(선택 사항): 에이전트의 주요 작업을 규정하는 시스템 프롬프트 지침.
• completion_args(선택 사항): temperature, top_p 등 표준 채팅 샘플러 매개변수.
• tools(선택 사항): 에이전트가 호출할 수 있는 도구 목록으로, 사용자 정의 function 호출 외에도 내장 도구인 web_search, web_search_premium, code_interpreter, image_generation, document_library(자체 데이터 기반 RAG 지식 검색)를 포함합니다.

Agents API와 Conversations API는 서로 독립적이므로, 사전에 Agent를 생성하지 않고 모델을 직접 지정하여 대화를 생성하고 지속할 수도 있습니다.

대화 흐름: Append, 저장 옵트아웃, 가드레일 및 Handoff

Conversations API는 멀티턴 대화 상태를 지속적으로 유지합니다. 공개 Conversations API는 요청에 사용된 API 키 소유자가 생성한 대화만 읽고 수정할 수 있도록 접근을 엄격히 제한합니다. 대화를 시작하면 conversation ID가 발급되며, 후속 메시지를 추가(append)할 때마다 업데이트된 새 Conversation ID가 반환되어 내부 저장 이력과 매핑됩니다.

대화 관리 시 다음과 같은 핵심 제어 기능을 활용할 수 있습니다:

• store: store=False 매개변수를 지정하면 대화 이력이 클라우드 서버에 자동 저장되지 않도록 옵트아웃할 수 있습니다.
• guardrails: 에이전트에 가드레일이 설정된 경우 연관된 모든 대화에 자동으로 적용됩니다. 모델을 직접 호출하는 POST /v1/conversations 요청에서는 guardrails 필드를 직접 전달하여 재정의할 수 있습니다.
• handoff_execution: 전환 흐름을 처리하는 방식으로 server와 client 모드를 지원합니다. 기본값인 server 모드는 클라우드 서버 내부에서 handoff를 직접 실행하며, client 모드는 handoff가 트리거될 때 응답을 사용자에게 반환하여 클라이언트 측에서 제어권을 갖도록 합니다.

개념적 단계별 구현 절차

1. 대화 상태를 관리할 계정 소유의 API 키를 사용하여 Mistral 클라이언트 인스턴스를 초기화합니다.
2. 대상 모델(예: mistral-medium-latest), 이름, 설명, 시스템 프롬프트(instructions), 필요한 도구(예: web_search)를 지정하여 Agent를 생성합니다.
3. 생성된 Agent의 agent_id와 첫 사용자 메시지(inputs)를 client.beta.conversations.start에 전달하여 대화를 시작합니다.
4. 반환된 대화 응답에서 발급된 conversation ID를 확인합니다.
5. 후속 턴을 진행할 때 기존 conversation_id와 추가 inputs를 대화 추가 엔드포인트에 전달하여 대화를 이어가며, 매 추가마다 새로 발급되는 conversation ID를 추적합니다.
6. 실행 환경 요구사항에 맞춰 handoff_execution을 server 또는 client 모드로 구성합니다.
7. 대화 이력이 클라우드에 저장되는 것을 방지해야 하는 규제 환경에서는 store=False를 명시합니다.

아키텍처 비교 요약 표

구현 점검 체크리스트

• 대화를 생성하고 접근하는 API 키 소유권이 일치하는지 확인.
• Agent 기반 대화와 model 직접 지정 대화 중 적합한 방식 선택.
• 필요한 내장 도구(web_search, code_interpreter, document_library 등) 또는 function 정의 등록.
• completion_args(temperature, top_p 등)를 요구사항에 맞게 튜닝.
• handoff_execution 모드를 서버 기반 자동화 또는 클라이언트 수동 제어로 명시.
• 데이터 보존 규정에 따라 store=False 옵트아웃 적용 여부 검토.
• Agent 미사용 시 POST /v1/conversations의 guardrails 필드 재정의 확인.

자세한 명세와 엔드포인트는 Mistral Agents API Documentation에서 확인할 수 있습니다.