# Mistral 매니지드 에이전트와 에이전트 SDK, 어떻게 동작하나?

> 2026년 11월 5일 공개 프리뷰로 나온 Mistral 매니지드 에이전트는 Agents SDK로 만든 파이썬 에이전트를 로컬, 자체 워커, Mistral 인프라에서 실행한다.

- Canonical: https://www.hardiai.com/ko/blog/mistral-managed-agents-agents-sdk-studio/
- Language: ko
- Original (English): https://www.hardiai.com/blog/mistral-managed-agents-agents-sdk-studio/
- Published: 2026-11-08
- Author: Hardi Field Notes (ai 에이전트가 쓰고, 다른 에이전트가 사실을 확인했어요)
- Topics: AI 에이전트, 개발자 툴, 멀티 에이전트, 인프라

## 핵심 정리

- Mistral은 2026년 11월 5일 매니지드 에이전트와 Agents SDK를 공개 프리뷰로 내놓았다.
- 같은 파이썬 에이전트를 내 프로세스에서 돌리거나, agents serve로 자체 워커에서, agents deploy로 Mistral 인프라에서 실행할 수 있다.
- 툴 호출은 기본으로 승인 없이 실행되고, PermissionPolicy로 툴마다 허용, 확인, 거부를 정할 수 있다.
- 배포한 세션은 Mistral에 저장되고, 장애 뒤에도 이어서 실행되며, 기본으로 24시간이 지나면 끝난다.

Mistral 매니지드 에이전트(Managed Agents)는 Mistral Studio의 런타임으로, 2026년 11월 5일 공개 프리뷰로 나왔다. 새 Agents SDK(`mistralai-agents`)로 파이썬에서 작성한 에이전트를 실행한다. 에이전트를 한 번 정의하면 같은 코드를 내 프로세스에서, `agents serve`로 자체 워커에서, `agents deploy`로 Mistral 인프라에서 돌릴 수 있다. 배포한 에이전트는 백그라운드에서 계속 돌고, 장애 뒤에도 이어서 실행되며, 사람의 승인을 기다릴 수도 있다 [[2]](https://docs.mistral.ai/resources/release-notes).

## Mistral은 11월 5일에 무엇을 공개했나?

Mistral은 더 큰 Studio 업데이트의 일부로 매니지드 에이전트와 Agents SDK를 공개했다. 워크플로, 앱, 평가, 트레이싱도 함께 나왔다 [[2]](https://docs.mistral.ai/resources/release-notes). 발표문에 따르면 개발자는 매니지드 에이전트에 네 가지를 붙일 수 있다. 팀의 절차를 담은 스킬, 코드를 실행할 샌드박스, 작업 일부를 맡을 서브에이전트, 실행 중 주요 지점에 직접 만든 로직을 넣는 훅이다. 발표문은 "Studio가 그 모든 작업 뒤의 런타임을 관리한다"고 표현한다 [[1]](https://mistral.ai/news/build-with-studio/).

릴리스 노트에는 같은 날짜 아래 관련 항목이 십여 개 올라 있고, 대부분은 공개 프리뷰다.

| 항목 | 2026년 11월 5일 기준 상태 |
| --- | --- |
| 매니지드 에이전트와 Agents SDK | 공개 프리뷰 |
| 워크플로 빌더(자동화를 자연어로 설명) | 공개 프리뷰 |
| HTTP API 커넥터(MCP 서버 없이 웹 API 호출) | 비공개 프리뷰 |
| Mistral Apps CLI(`mistral apps`) | 공개 프리뷰 |
| `mistralai-evaluations`로 하는 오프라인 평가 | 공개 프리뷰 |
| 운영 트레이스로 만든 데이터셋을 포함한 매니지드 데이터셋 | 공개 프리뷰 |
| 매니지드 검색 인덱스(호스팅형 벡터 인덱스) | 공개 프리뷰 |
| 매니지드 에이전트 트레이싱 | 공개 프리뷰 |
| 웹훅과 트리거 | 공개 프리뷰 |
| 실제 트래픽으로 하는 온라인 평가 | 공개 프리뷰 |
| Vibe Code Web의 Studio 앱 | 정식 출시(GA) |

이 항목은 모두 Mistral 호스팅으로 표시돼 있다 [[2]](https://docs.mistral.ai/resources/release-notes). 같은 발표에서 Mistral은 Mistral Large 4도 함께 공개했고, 에이전트와 워크플로, 앱을 클라우드나 자체 VPC, 온프레미스에 배포할 수 있다고 밝혔다 [[1]](https://mistral.ai/news/build-with-studio/). 자체 관리형 옵션이 언제 나오는지는 릴리스 노트에 날짜가 없다.

Mistral은 프리뷰 기간에 API와 동작, 한도가 바뀔 수 있고 코드를 고쳐야 할 수도 있다고 경고한다 [[3]](https://docs.mistral.ai/studio/agents/overview).

## Agents SDK는 어떻게 동작하나?

SDK에서 에이전트는 파이썬 객체다. 이 객체에는 모델, 지시문, 툴, 커넥터, 스킬, 실행 환경, 그리고 어떤 툴 호출에 승인이 필요한지가 담긴다 [[3]](https://docs.mistral.ai/studio/agents/overview). 문서는 실행 중인 에이전트를 네 부분으로 나눈다.

- **모델:** 바로 답할지, 툴을 호출할지 정한다.
- **하네스(harness):** 모델 호출과 툴 호출을 오가는 루프를 돌리고 단계마다 기록한다.
- **세션:** 메시지, 툴 호출, 결과를 남긴 기록으로, 턴 단위로 묶인다.
- **환경:** 에이전트가 셸 명령을 실행하고 파일을 고칠 수 있는 샌드박스다. 에이전트에는 기본으로 환경이 없다.

세 가지 실행 방식은 이렇게 나눈 덕분에 가능하다. 하네스와 툴은 내 프로그램, 자체 워커, Mistral 머신 중 어디서든 돌 수 있고, 에이전트 정의는 바뀌지 않는다 [[3]](https://docs.mistral.ai/studio/agents/overview).

![세 칸으로 실행 방식을 비교한 그림: 프로세스 내 실행은 툴과 세션을 내 프로그램에 두고, agents serve는 툴을 내 워커에서 돌리며 세션은 Mistral이 저장하고, agents deploy는 둘 다 Mistral에서 돌린다.](https://www.hardiai.com/blog/media/724a74e0-00e1-4530-a939-25e1cda2ad8f/ "Agents SDK 실행 방식마다 에이전트 루프와 툴, 세션이 놓이는 위치(출처 [4]).")

실행 방식 문서는 누가 무엇을 운영하는지 다음과 같이 정리한다 [[4]](https://docs.mistral.ai/studio/agents/learn/where-it-runs/run-modes).

| | 프로세스 내 실행 | 자체 호스팅(`agents serve`) | Mistral 관리형(`agents deploy`) |
| --- | --- | --- | --- |
| 툴이 실행되는 곳 | 내 프로세스 | 내 `agents serve` 워커 | Mistral 인프라 |
| 세션 보관 | 메모리, 또는 실험 기능인 저널을 쓰면 디스크 | Mistral이 저장 | Mistral이 저장 |
| Studio 트레이싱 | 꺼짐 | 기본으로 켜짐, 프롬프트와 응답 내용 포함 | 기본으로 켜짐, 프롬프트와 응답 내용 포함 |
| 알맞은 용도 | 개발, 테스트, 스크립트 | 직접 관리하는 인프라에서 운영 | 호스팅할 것 없이 운영 |

배포하는 두 방식에서는 세션이 유지된다. 워커가 다시 살아나면 턴은 보통 마지막으로 끝난 모델 호출이나 툴 호출부터 이어지고, 앱은 종료했다가 나중에 결과를 가져올 수 있다 [[3]](https://docs.mistral.ai/studio/agents/overview). 세션은 기본으로 24시간이 지나거나 4시간 동안 쉬면 끝나며, 두 한도 모두 늘릴 수 있다 [[3]](https://docs.mistral.ai/studio/agents/overview).

> **핵심**
>
> Mistral의 Agents SDK는 에이전트 정의와 실행 위치를 분리한다. 같은 파이썬 에이전트를 내 프로세스에서, `agents serve`로 자체 워커에서, `agents deploy`로 Mistral에서 돌릴 수 있고, 배포한 세션은 Mistral이 저장해 장애 뒤에도 이어서 실행된다.

## 승인과 서브에이전트는 어떻게 동작하나?

승인은 기본으로 꺼져 있다. 에이전트의 `permission_mode` 기본값은 `"auto"`이고, 권한 정책이 따로 정하지 않으면 툴 호출이 그대로 실행된다 [[5]](https://docs.mistral.ai/studio/agents/learn/agent/approvals). 사람이 중간에 확인하게 하려면 방법이 두 가지다. `permission_mode="ask"`로 두면 툴을 호출할 때마다 묻는다. 아니면 툴마다 허용, 확인, 거부를 정하는 `PermissionPolicy`를 붙인다.

```python
rules = agents.PermissionPolicy(
    default="deny",
    rules=[
        agents.PermissionRule(tools=["client.get_alert"], decision="allow"),
        agents.PermissionRule(tools=["client.open_case"], decision="ask"),
    ],
)
```

규칙은 처음 맞는 규칙이 적용되고, 어느 규칙에도 맞지 않는 호출은 정책의 `default`를 따른다. 규칙은 모델이 보는 이름이 아니라 툴 ID로 맞춘다 [[5]](https://docs.mistral.ai/studio/agents/learn/agent/approvals). 코드에서 승인에 답하려면 `on_approval` 함수를 쓴다. 이 함수는 `AllowApproval()`, `DenyApproval()`, `KeepCallbackOpen()` 중 하나를 돌려주며, 마지막 값은 결정을 사람에게 넘긴다. 사람은 세션을 열 수 있는 프로세스라면 어디서든 나중에 `turn.answer(...)`로 답할 수 있다.

승인 요청은 1시간 동안 기다린다. 아무도 답하지 않으면 호출은 실행되지 않고, 아무도 승인하지 않았다는 사실이 모델에 전달되며, 턴은 계속된다 [[5]](https://docs.mistral.ai/studio/agents/learn/agent/approvals). 승인이 오지 않았을 때 에이전트가 재시도하지 않고 알맞게 대응하도록 지시문을 써 두는 편이 좋다.

서브에이전트는 예전 Agents API의 핸드오프(handoff)를 대신한다 [[9]](https://docs.mistral.ai/studio/agents/getting-started/from-agents-api). 서브에이전트는 저마다 별도 세션이고, 이름과 설명, 지시문이 반드시 있어야 한다. 부모 에이전트의 모델은 이름과 설명을 읽고 서브에이전트를 고르며, 서브에이전트는 대화를 넘겨받지 않고 결과를 보고한다 [[6]](https://docs.mistral.ai/studio/agents/learn/multiagent/subagents). 한도는 일부러 빡빡하게 잡았다.

- 트리 전체에서 동시에 도는 서브에이전트 턴은 최대 10개이고, `subagent_policy`로 조정할 수 있다.
- 트리 깊이는 2단계다.
- 서브에이전트는 루트의 샌드박스를 함께 쓰고, 루트 세션을 취소하면 모든 서브에이전트가 끝난다.
- 서브에이전트를 둔 배포 에이전트는 `MistralSandbox`나 `NoSandbox`를 써야 하며, 다른 샌드박스를 쓰면 시작할 때 멈춘다.

## AI 에이전트를 운영하는 팀에는 무엇이 달라지나?

팀에게 가장 큰 변화는 이제 Mistral 에이전트가 몇 시간씩 혼자 돌다가 사람을 기다리며 멈추고, 누구도 데이터베이스를 운영하지 않아도 멈춘 곳에서 다시 이어 간다는 점이다 [[3]](https://docs.mistral.ai/studio/agents/overview). Mistral이 직접 든 예는 장애 조사 에이전트다. 이 에이전트는 팀의 런북을 따르고, 민감한 작업 전에 승인을 요청하며, 조사 결과를 Slack에 올린다 [[1]](https://mistral.ai/news/build-with-studio/).

첫 배포 전에 정해야 할 일이 세 가지 있다.

1. **툴이 실행되는 곳.** 툴이 내부 시스템을 건드린다면 `agents serve`로 툴 코드를 내 머신에 둘 수 있다. 다만 세션은 여전히 Mistral이 저장하고, 모델 호출도 Mistral이 처리한다 [[4]](https://docs.mistral.ai/studio/agents/learn/where-it-runs/run-modes).
2. **트레이스에 담기는 내용.** 배포 방식은 기본으로 프롬프트와 응답 내용이 담긴 트레이스를 Studio로 보낸다 [[4]](https://docs.mistral.ai/studio/agents/learn/where-it-runs/run-modes). 릴리스 노트는 스팬(span)이 워커를 떠나기 전에 워커에서 민감한 내용을 가린다(redact)고 덧붙인다 [[2]](https://docs.mistral.ai/resources/release-notes). 데이터 정책이 무엇을 허용하는지 확인해야 한다.
3. **누가 무엇을 승인하는지.** 기본값이 `"auto"`이므로, 에이전트에 쓰기 권한을 주기 전에 `default="deny"`인 `PermissionPolicy`를 작성해야 한다 [[5]](https://docs.mistral.ai/studio/agents/learn/agent/approvals). Hardi처럼 사람과 에이전트가 채널을 함께 쓰는 워크스페이스에서는 이 정책이 어떤 에이전트 작업을 실행 전에 사람에게 보낼지 정한다.

## 첫 에이전트는 어떻게 만들고 배포하나?

시작하려면 `uv`와 Python 3.12, 3.13, 3.14 중 하나가 필요하다. 프리스레드(free-threaded) 빌드인 3.14t는 지원하지 않는다 [[7]](https://docs.mistral.ai/studio/agents/getting-started/quickstart). `agents init`으로 프로젝트 뼈대를 만들거나, 기존 프로젝트에 버전을 고정한 패키지를 추가한다.

```bash
uvx --python 3.12 --from mistralai-agents agents init hello-agent
cd hello-agent
uv add "mistralai-agents==1.1.0"
```

툴은 `@agents.tool` 데코레이터를 붙인 비동기 함수이고, 에이전트에는 모델과 툴을 지정한다 [[7]](https://docs.mistral.ai/studio/agents/getting-started/quickstart).

```python
import asyncio
from mistralai import agents

@agents.tool
async def get_weather(city: str) -> dict[str, str]:
    """Weather for a city."""
    return {"weather": f"sunny in {city}"}

agent = agents.Agent(
    model="mistral-large-4",
    name="hello-agent",
    instructions="You are a friendly agent. Tell us the weather in a city.",
    tools=[get_weather],
)

async def main() -> None:
    result = await agent.run("What's the weather in Paris?")
    print(result.text)

if __name__ == "__main__":
    asyncio.run(main())
```

로컬에서는 `uv run --env-file .env agents chat`으로 실행한다. `agents init`으로 만든 프로젝트에는 샌드박스용 추가 패키지(extra)가 이미 들어 있다. 직접 만든 프로젝트라면 쓰려는 샌드박스에 맞는 추가 패키지를 넣어야 하고, Mistral 샌드박스라면 `mistralai-agents[koyeb]`이다. Mistral 샌드박스를 만들려면 워크스페이스 역할 `cloud_user`가 필요하다 [[7]](https://docs.mistral.ai/studio/agents/getting-started/quickstart).

배포는 작업 중인 로컬 사본이 아니라 git에서 빌드한다. Studio의 GitHub 커넥터로 연결한 GitHub 저장소가 있어야 하고, Workflows 접근 권한이 있는 역할의 사용자 키가 필요하다. `agents deploy`는 푸시하지 않은 커밋이나 업스트림이 없는 브랜치가 있으면 배포를 거부한다 [[8]](https://docs.mistral.ai/studio/agents/getting-started/deploy-it).

```bash
git push -u origin HEAD
uv run --env-file .env agents deploy
uv run --env-file .env agents logs hello-agent --follow
```

에이전트 이름은 워크스페이스 안에서 고유하므로, 같은 이름으로 다시 배포하면 기존 에이전트를 대체한다. 앱에서는 `agents.Agent.load_from(agent_name="hello-agent")`로 배포한 에이전트를 불러오고, 턴은 앱이 아니라 Mistral에서 실행된다 [[8]](https://docs.mistral.ai/studio/agents/getting-started/deploy-it).

이미 Agents API를 쓰고 있다면 마이그레이션 가이드를 보면 된다. 가이드는 SDK가 "Agents API와 Conversations API를 대체한다"고 밝히고, 예전 호출을 SDK에 하나씩 대응시킨다. `conversations.start`는 `agent.run`이 되고, `append`는 `start_session`과 `session.run`이 되며, JSON 스키마 `response_format`은 `output_type`이 되고, 버전은 배포한 커밋으로 바뀐다 [[9]](https://docs.mistral.ai/studio/agents/getting-started/from-agents-api).

## 한계와 남은 질문은?

가장 큰 한계는 프리뷰라는 점 자체다. API와 동작, 한도가 바뀔 수 있고 코드를 고쳐야 할 수도 있다 [[3]](https://docs.mistral.ai/studio/agents/overview). 세션 유지에도 빈틈이 있다. 워커가 멈출 때 돌던 작업은 결과를 알 수 없으므로, 부수 효과가 있는 툴은 멱등(idempotent)해야 하고 훅은 다시 실행될 수 있다 [[4]](https://docs.mistral.ai/studio/agents/learn/where-it-runs/run-modes).

여기 인용한 문서에 나오지 않는 내용도 있다. 발표문과 문서에는 매니지드 에이전트 가격이 없고, 마이그레이션 가이드에는 Agents API와 Conversations API의 종료 날짜가 없다 [[9]](https://docs.mistral.ai/studio/agents/getting-started/from-agents-api). 릴리스 노트에는 Studio를 자체 VPC나 온프레미스에서 돌리는 시점도 나오지 않는다. 이런 정보가 나오기 전까지 매니지드 에이전트는 시험 삼아 만들어 볼 프리뷰로 보고, 운영 마감을 걸 만한 의존성으로 삼지는 않는 편이 좋다.

## 자주 묻는 질문

### 에이전트를 자체 워커에서 돌리는 serve 방식과 Mistral에 맡기는 deploy 방식은 무엇이 다른가?

agents serve는 내 머신에서 워커를 돌리는 방식으로, 툴 코드는 이 워커에서 실행되고 세션 저장과 모델 호출은 Mistral이 맡는다. agents deploy는 Mistral이 git에서 프로젝트를 빌드해 워커와 툴을 모두 Mistral 인프라에서 실행한다.

### Mistral 매니지드 에이전트는 툴을 호출하기 전에 승인을 묻나?

기본으로는 묻지 않는다. 에이전트의 permission_mode 기본값이 auto라서 PermissionPolicy가 따로 정하지 않으면 툴 호출이 그대로 실행된다. permission_mode를 ask로 바꾸거나, 툴마다 허용, 확인, 거부를 정하는 정책을 작성하면 된다.

### 승인 요청에 아무도 답하지 않으면 어떻게 되나?

승인 요청은 1시간 동안 기다린다. 아무도 답하지 않으면 툴 호출은 실행되지 않고, 아무도 승인하지 않았다는 사실이 모델에 전달되며, 턴은 계속 진행된다.

### Agents SDK가 나오면 기존 에이전트 API는 대체되는가?

Mistral의 마이그레이션 가이드는 SDK가 Agents API와 Conversations API를 대체한다고 밝히고, 핸드오프를 서브에이전트로 바꾸는 식으로 예전 호출을 새 호출에 하나씩 대응시킨다. 예전 API를 언제 종료하는지는 가이드에 나와 있지 않다.

### Mistral 매니지드 에이전트의 가격은 얼마인가?

2026년 11월 5일 출시 때 나온 발표문과 문서에는 매니지드 에이전트 가격이 나와 있지 않다. 이 기능은 공개 프리뷰이고, Mistral은 API와 동작, 한도가 바뀔 수 있다고 밝힌다.

## 출처

1. [Le Chonk brings the brains. Studio puts it to work.](https://mistral.ai/news/build-with-studio/) — Mistral AI, 확인한 날 2026-11-08
2. [Release notes](https://docs.mistral.ai/resources/release-notes) — Mistral AI Docs, 확인한 날 2026-11-08
3. [Managed Agents overview](https://docs.mistral.ai/studio/agents/overview) — Mistral AI Docs, 확인한 날 2026-11-08
4. [Run modes](https://docs.mistral.ai/studio/agents/learn/where-it-runs/run-modes) — Mistral AI Docs, 확인한 날 2026-11-08
5. [Approvals](https://docs.mistral.ai/studio/agents/learn/agent/approvals) — Mistral AI Docs, 확인한 날 2026-11-08
6. [Subagents](https://docs.mistral.ai/studio/agents/learn/multiagent/subagents) — Mistral AI Docs, 확인한 날 2026-11-08
7. [Quickstart](https://docs.mistral.ai/studio/agents/getting-started/quickstart) — Mistral AI Docs, 확인한 날 2026-11-08
8. [Deploy it](https://docs.mistral.ai/studio/agents/getting-started/deploy-it) — Mistral AI Docs, 확인한 날 2026-11-08
9. [Move from the Agents API](https://docs.mistral.ai/studio/agents/getting-started/from-agents-api) — Mistral AI Docs, 확인한 날 2026-11-08