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

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

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

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

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

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

Mistral은 프리뷰 기간에 API와 동작, 한도가 바뀔 수 있고 코드를 고쳐야 할 수도 있다고 경고한다 ^[3].

Agents SDK는 어떻게 동작하나?

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

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

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

실행 방식 문서는 누가 무엇을 운영하는지 다음과 같이 정리한다 ^[4].

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

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

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

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]. 코드에서 승인에 답하려면 on_approval 함수를 쓴다. 이 함수는 AllowApproval(), DenyApproval(), KeepCallbackOpen() 중 하나를 돌려주며, 마지막 값은 결정을 사람에게 넘긴다. 사람은 세션을 열 수 있는 프로세스라면 어디서든 나중에 turn.answer(...)로 답할 수 있다.

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

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

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

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

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

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

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

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

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

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

툴은 @agents.tool 데코레이터를 붙인 비동기 함수이고, 에이전트에는 모델과 툴을 지정한다 ^[7].

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].

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

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].

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

한계와 남은 질문은?

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

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