Modal Sandbox

ModalSandbox는 에이전트에게 명령 실행과 파일 작업을 위한 격리된 클라우드 컨테이너를 줘요. 모델이 생성한 명령을 애플리케이션 호스트에서 실행하면 안 되는 코딩·데이터 처리·그 밖의 작업에 쓰세요.

이 capability는 Modal sandbox로 뒷받침되는 셸·파일 도구를 추가해요. 기본적으로 모든 에이전트 실행이 컨테이너 이미지에서 만들어진 새 샌드박스를 받아요. capability는 실행이 끝나면 종료를 요청해요. 기존 샌드박스를 붙이거나 여러 실행에 걸쳐 하나를 재사용할 수도 있어요.

Pydantic AI Harness가 0.x 릴리스인 동안 API는 마이너 릴리스 사이에 바뀔 수 있어요. 바뀔 때는 폐기 경고와 릴리스 노트 마이그레이션 안내가 정확히 어떻게 업그레이드할지 알려줘요. 버전 정책 참고.

출처: 문서

본문

빠른 시작 (Quick start)

modal 엑스트라를 설치하고 Modal CLI로 인증하세요. CI에서는 대신 MODAL_TOKEN_ID와 MODAL_TOKEN_SECRET을 설정해요.

pip install "pydantic-ai-harness[modal]"

uv add "pydantic-ai-harness[modal]"

 modal token new                # writes ~/.modal.toml

uv run modal token new                # writes ~/.modal.toml

CI에서는 인터랙티브 인증 대신 환경 변수를 사용하세요:

export MODAL_TOKEN_ID=...
export MODAL_TOKEN_SECRET=...

ModalSandbox를 에이전트에 추가하세요:

from pydantic_ai import Agent
from pydantic_ai_harness import ModalSandbox

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[ModalSandbox(image='python:3.12-slim')],
)

result = agent.run_sync('Create a Python script and run its tests.')
print(result.output)

실행 중 에이전트는 파일을 만들고, 작업 디렉터리를 검사하고, 명령을 실행하고, 명령 실패에 반응할 수 있어요. 샌드박스는 호스트 파일시스템과 프로세스 공간에서 분리돼요.

capability는 네 도구를 기여해요:

도구	용도
`run_command`	`sh -c`를 통한 셸 명령 실행
`read_file`	경계 있는 출력과 줄 페이징으로 UTF-8 텍스트 파일 읽기
`write_file`	UTF-8 텍스트 파일 쓰기, 부모 디렉터리 생성
`list_directory`	디렉터리 항목 나열, 디렉터리에 `/` 표시

명령 출력은 stdout과 stderr을 라벨하고 0이 아닌 종료 코드를 모델에 보고해요. 절단할 때 꼬리를 유지해 나중 진단이 보이게 해요. 파일 읽기는 머리를 유지하고 더 많은 콘텐츠가 있을 때 다음 줄 오프셋을 반환해요.

라이프사이클 (Lifecycle)

기본적으로 각 에이전트 실행은 소유 샌드박스를 만들고 실행이 종료되면 그 종료를 요청하므로, 실행당 콜드-스타트 비용을 기대하세요. 분해는 경계 있는 기간 동안 확인을 기다려요. 제어 평면이 응답하지 않으면 sandbox_timeout이 서버 측 정리 백스톱으로 남아요. 샌드박스 도구가 호출되지 않아도 샌드박스는 실행이 capability toolset에 들어갈 때 프로비저닝돼요. 지연 도구 로딩은 어떤 도구 정의가 모델에 닿는지를 제어하지, toolset 라이프사이클을 지연시키지 않아요.

ID로 다른 곳에서 관리되는 샌드박스에 붙이기:

from pydantic_ai_harness import ModalSandbox

ModalSandbox(sandbox_id='sb-abc123')

실행에 걸쳐 샌드박스를 공유하면서 그 수명을 제어하려면, ModalSandboxSession을 직접 만들고 들어가세요:

from pydantic_ai import Agent
from pydantic_ai_harness import ModalSandbox
from pydantic_ai_harness.modal_sandbox import ModalSandboxSession

async with ModalSandboxSession(image='python:3.12-slim', sandbox_timeout=1800) as session:
    agent = Agent(
        'anthropic:claude-sonnet-4-6',
        capabilities=[ModalSandbox(session=session, max_command_timeout=600)],
    )
    await agent.run('Install the project dependencies.')
    await agent.run('Run the test suite in the same sandbox.')

세션의 sandbox_timeout을 전체 워크로드에 맞게 크게 잡으세요. 기본 300s는 여러 실행 세션 도중에 만료될 거예요. capability는 재사용된 샌드박스의 실제 수명을 볼 수 없으므로, 거기서 각 명령은 max_command_timeout이 상한을 올리지 않으면 300s로 상한이 정해져요.

붙여지고 주입된 샌드박스는 에이전트 실행이 끝날 때 실행 중으로 남아요. 그것들은 파일시스템과 프로세스 공간을 공유하므로, 격리가 필요한 겹치는 실행에 같은 샌드박스를 쓰지 마세요.

타임아웃과 출력 한도 (Timeouts and output limits)

모든 모델 직면 명령은 유한 마감을 받아요. default_command_timeout이 기본값을 공급하고 max_command_timeout이 모델 제공 값을 상한으로 잡아요. Modal은 정수 초 마감을 받아들이므로, 분수 값은 구성된 정수 상한을 초과하지 않고 반올림돼요.

Modal은 명령별 kill 연산을 노출하지 않아요. 클라이언트 대기 취소가 원격 명령을 즉시 멈추지 않아요. 그 명령 마감이나 샌드박스 종료까지 계속돼요.

각 명령 스트림은 모든 전송 청크 후 마지막 max_output_bytes를 유지하고, 각 스트림의 페이로드도 도구 출력에서 max_output_bytes·max_output_lines로 별도 절단돼요. 큰 stderr이 stdout을 밀어내지 못하고 [stdout]/[stderr] 라벨이 항상 살아남게요. 어떤 절단도 표시돼요. 라벨·절단·계속 메모·명령 상태가 그 페이로드 한도를 넘어 조금 추가돼요. 하나의 전송 청크는 바이트 한도를 일시적으로 초과할 수 있어요. 잘못된 UTF-8은 대체 문자로 디코딩돼요.

read_file은 파일 메타데이터를 먼저 확인하고 반환된 바이트 수를 다시 확인해요. 그 사이에 자라는 파일은 거부되기 전에 클라이언트 메모리에서 max_read_bytes를 일시적으로 초과할 수 있어요. Modal의 파일시스템 API는 경계 있는 읽기를 노출하지 않으므로, 가상 파일이나 보고된 크기가 오해의 소지가 있는 경로에는 경계 있는 셸 명령을 사용하세요.

list_directory는 절단 전에 완전한 디렉터리 목록을 구체화해요. 항목이 많은 디렉터리를 나열하는 것은 따라서 항목 수에 비례하는 메모리를 사용해요. 비정상적으로 큰 디렉터리에는 좁혀진 셸 명령을 사용하세요.

Modal의 SDK는 asyncio 네이티브예요. capability는 asyncio 이벤트 루프를 요구하고 trio 아래서는 실행되지 않아요.

오류와 구성 (Errors and composition)

복구 가능한 명령·파일시스템 실패는 모델 재시도 프롬프트가 돼요. 종료된 샌드박스는 ModalSandboxUnavailableError를, 거부된 Modal 자격 증명은 ModalSandboxAuthError를 발생시켜요(둘 다 ModalSandboxTerminalError 서브클래스). 같은 사용 불가 샌드박스에 재시도하는 대신.

toolset은 구현 세부사항이에요. 공개 저수준 API는 ModalSandboxSession, ModalSandboxExecResult, 타입화된 샌드박스 오류 클래스로 구성돼요.

이 capability를 run_command, read_file, write_file, list_directory를 등록하는 다른 비프리픽스 capability(Shell이나 FileSystem capability 같은)와 결합하지 마세요. Pydantic AI는 중복 도구 이름을 거부해요. 같은 이름을 쓰는 다른 capability와 구성하기 전에 capability에 프리픽스를 붙이세요:

from pydantic_ai.capabilities import PrefixTools

from pydantic_ai_harness import ModalSandbox

sandbox = PrefixTools(
    wrapped=ModalSandbox(
        instructions=(
            'You have a Modal cloud sandbox. Use the modal_-prefixed tools to run '
            'shell commands and manage files in it.'
        )
    ),
    prefix='modal',
)

프리픽싱은 도구를 이름 바꾸지만(modal_run_command, ...) 비프리픽스 도구를 이름 짓는 capability의 기본 지시문은 다시 쓰지 않아요. 프리픽스 이름과 일치하는 텍스트로 instructions를 넘기세요.

구성 (Configuration)

from pydantic_ai_harness import ModalSandbox

ModalSandbox(
    image='python:3.12-slim',
    sandbox_id=None,
    session=None,
    app_name='pydantic-ai-harness',
    create_app_if_missing=True,
    sandbox_timeout=300,
    workdir=None,
    env=None,
    default_command_timeout=60.0,
    max_command_timeout=None,
    max_output_bytes=50 * 1024,
    max_output_lines=2000,
    max_read_bytes=5 * 1024 * 1024,
    instructions=None,
)

기본 지시문은 도구, 명령 타임아웃, 그 상한을 명시해요. 아무것도 추가하지 않으려면 instructions='', 기본을 대체하려면 고유 텍스트를 넘기세요.

샌드박스를 만들 때만 쓰는 설정은 sandbox_id나 주입된 session과 결합할 수 없어요. 이 충돌은 무시되는 대신 구성 시 실패해요.

아직 지원되지 않음 (Not yet supported)

스트리밍 명령 출력: run_command는 명령이 끝나면(또는 마감에 닿으면) 반환하지, 증분으로 반환하지 않아요.
커스텀 빌드 이미지, 마운트, modal.Secret: image는 레지스트리 태그를, env는 평문 환경 변수를 받아요. 더 풍부한 것은 Modal SDK로 샌드박스를 직접 만들고 sandbox_id나 session으로 넘기세요.
전체 출력을 파일로 유출: 잘린 파일 읽기는 다음 offset으로 끝나 페이지할 수 있고, 과대한 파일은 셸-슬라이스 힌트를, 잘린 명령 출력은 절단 마커를 얻어요. 모델이 열도록 샌드박스에 파일에 아무것도 쓰지 않아요.

에이전트 스펙 (Agent specs)

에이전트 스펙을 로드할 때 ModalSandbox를 커스텀 capability 타입으로 등록하세요:

model: anthropic:claude-sonnet-4-6
capabilities:
  - ModalSandbox:
      image: python:3.12-slim
      sandbox_timeout: 600

from pydantic_ai import Agent
from pydantic_ai_harness import ModalSandbox

agent = Agent.from_file('agent.yaml', custom_capability_types=[ModalSandbox])

API 참고 (API reference)

ModalSandbox

Bases: AbstractCapability[AgentDepsT]

Modal이 구동하는 격리된 클라우드 샌드박스 접근.

에이전트에게 Modal 샌드박스 안에서 명령을 실행하고 파일을 관리하는 도구를 줘요. 호스트를 건드리지 않고 신뢰할 수 없거나 모델 생성된 코드를 실행할 장소죠. 기본적으로 각 실행은 image에서 만들어진 새 샌드박스를 받아요. 실행이 끝나면 capability는 종료를 요청하고 경계 있는 기간을 기다려요. sandbox_timeout은 서버 측 정리 백스톱이에요. 한 샌드박스를 실행에 걸쳐 유지하려면, 다른 곳에서 관리하는 샌드박스에 붙는 sandbox_id를 설정하거나, 수명을 제어하고 sandbox_id를 읽을 수 있는 소유 세션(열린 ModalSandboxSession)을 session으로 넘기세요. capability는 당신이 넘긴 session을 열거나 종료하지 않아요.

modal 엑스트라(uv add "pydantic-ai-harness[modal]")와 Modal 자격 증명이 필요하고, Modal CLI처럼 구성돼요. modal token new를 한 번 실행하거나 환경에 MODAL_TOKEN_ID / MODAL_TOKEN_SECRET을 설정하세요.

from pydantic_ai import Agent
from pydantic_ai_harness.modal_sandbox import ModalSandbox

agent = Agent('anthropic:claude-sonnet-4-6', capabilities=[ModalSandbox()])
result = agent.run_sync('Write a Python script that prints the first 10 primes and run it.')
print(result.output)

속성 (Attributes)

image

소유 샌드박스용 컨테이너 이미지, 레지스트리 태그(예: python:3.12-slim).

타입: str 기본: _DEFAULT_IMAGE

sandbox_id

만드는 대신 ID로 기존 샌드박스에 붙이기. 붙인 샌드박스는 종료되지 않아요.

이것을 사용해 다른 곳(예: Modal CLI를 통해)에서 만든 샌드박스를 재사용해요. 샌드박스를 만들 때만 적용되는 설정(image, app_name, create_app_if_missing, sandbox_timeout, workdir, env)은 sandbox_id와 결합할 수 없어요.

타입: str | None 기본: None

session

실행별이 아니라 실행에 걸쳐 열어 두는, 소유한 샌드박스 세션 사용.

이미 들어간 ModalSandboxSession을 넘기면 한 샌드박스를 실행에 걸쳐 재사용하면서 수명을 직접 제어해요. capability는 그것을 쓰지만 열거나 종료하지 않아요. sandbox_id나 소유-샌드박스 생성 설정(세션이 이미 그들을 소유)과 결합할 수 없어요. sandbox_id처럼 공유 세션도 겹치는 실행에 걸쳐 동시성 안전하지 않아요.

타입: ModalSandboxSession | None 기본: None

app_name

소유 샌드박스가 만들어지는 Modal 앱.

타입: str 기본: _DEFAULT_APP_NAME

create_app_if_missing

True면 Modal 앱이 이미 존재하지 않을 때 만듦.

타입: bool 기본: True

sandbox_timeout

Modal이 종료하기 전 소유 샌드박스의 최대 수명(초).

이것은 전체 샌드박스를 경계 짓고, default_command_timeout은 단일 명령을 경계 지어요.

타입: int 기본: _DEFAULT_SANDBOX_TIMEOUT

workdir

소유 샌드박스 안 명령의 작업 디렉터리(None이면 Modal 기본값).

타입: str | None 기본: None

env

소유 샌드박스에 설정할 환경 변수.

소유 샌드박스 전용이에요. 붙여지거나 주입된 샌드박스에 시크릿·env를 주입하려면 그 샌드박스를 직접 만들 때 설정하세요(예: modal.Secret).

타입: Mapping[str, str] | None 기본: None

default_command_timeout

하나의 run_command의 기본 타임아웃(초), 모델이 생략할 때 사용.

이것은 단일 명령을 경계 짓고, sandbox_timeout은 전체 샌드박스 수명을 경계 지어요. Modal은 정수 초 마감을 강제하므로 분수 값은 반올림돼요(0.5는 1로 동작).

타입: float 기본: 60.0

max_command_timeout

모델 제공 timeout_seconds를 포함, 어떤 단일 run_command의 하드 상한(초). None은 sandbox_timeout으로 폴백.

Modal에는 명령별 kill이 없으므로 취소된 명령이 그 마감까지 계속돼요. 이것은 그 최악의 경우가 얼마나 길 수 있는지 상한으로 잡아요. 소유 명령은 어쨌든 sandbox_timeout보다 오래 살 수 없으므로, 소유 샌드박스에 대해 기본 상한은 정확해요.

붙여지거나 주입된 샌드박스에 대한 폴백은 여전히 sandbox_timeout이고, capability가 만들지 않은 샌드박스의 실제 수명을 모르므로 그 모드에서는 기본값(300s)에 고정돼요. 그래서 거기서 모든 명령은 max_command_timeout을 샌드박스가 실제 허용하는 값으로 설정하지 않으면 300s로 상한이 정해져요.

타입: int | None 기본: None

max_output_bytes

명령 스트림 또는 파일 읽기당 보유하는 최대 페이로드, UTF-8 바이트로 측정.

명령에서 상한은 stdout과 stderr에 별도로 적용돼요. 클라이언트 측(각 스트림이 Modal이 각 전송 청크 후 최대 이 바이트 유지)과 도구 출력 모두에서, 큰 stderr이 stdout을 밀어내지 않게요. 라벨·절단 메모·계속 오프셋·타임아웃·종료 코드가 이 페이로드 한도를 넘어 조금 추가돼요. max_output_bytes와 max_output_lines 중 먼저 닿는 쪽이 이겨요.

타입: int 기본: DEFAULT_MAX_BYTES

max_output_lines

max_output_bytes와 함께, 명령 스트림 또는 파일 읽기당 보유하는 최대 페이로드 줄.

많은 짧은 줄이 바이트 예산 아래 쌓이지 못하게 하는 두 번째 상한. 먼저 닿는 상한이 이겨요. 라벨과 절단·상태 메모가 이 페이로드 한도를 넘어 줄을 추가할 수 있어요. 두 상한 모두 컨텍스트 예산을 대리하고, 미래의 토큰 기반 상한은 추가적일 거예요.

타입: int 기본: DEFAULT_MAX_LINES

max_read_bytes

read_file이 통째로 읽을 가장 큰 파일. 더 큰 파일은 셸 도구 사용 힌트와 함께 거부.

Modal은 경계 있는 파일 읽기 API가 없어요. 도구는 읽기 전에 메타데이터를, 반환된 바이트 수를 다시 확인하지만, 그 사이에 자라는 파일은 거부되기 전에 클라이언트 메모리에서 이 값을 잠시 초과할 수 있어요.

타입: int 기본: _DEFAULT_MAX_READ_BYTES

instructions

모델에게 샌드박스를 어떻게 쓰는지 알려주는 지시문, 시스템 프롬프트에 추가.

모드를 매칭하는 기본값(실행마다 새 샌드박스, 또는 이전 실행에서 파일을 나를 수 있는 재사용된 샌드박스)에 None을 두고 명령 타임아웃과 상한을 명시해요. 지시문을 추가하지 않으려면 '', 또는 고유 텍스트를 넘기세요 — 예를 들어 PrefixTools로 감쌀 때 텍스트의 도구 이름이 프리픽스된 것과 일치하도록.

타입: str | None 기본: None

메서드 (Methods)

post_init

def __post_init__() -> None

선택한 모드가 무시할 설정을 거부해, 죽은 값이 오도하지 않게 함.

세 모드가 있다: 소유(기본), 붙이기(sandbox_id), 주입(session). 붙이기와 주입 둘 다 기존 샌드박스를 재사용하므로, 소유 전용 생성 설정은 거기서 효과가 없어요. session은 또한 sandbox_id를 포괄해요. 충돌하는 값을 무시하기보다 제거할 이름과 함께 구성 시 실패해요.

반환

None

get_instructions

def get_instructions() -> str | None

instructions로 오버라이드·비활성화되지 않았다면 샌드박스를 모델에게 설명.

반환

str | None

get_toolset

def get_toolset() -> AgentToolset[AgentDepsT]

Modal 샌드박스 toolset 구축·반환.

반환

AgentToolset[AgentDepsT]

ModalSandboxSession

Modal 샌드박스를 소유하거나 붙는 비동기 컨텍스트 매니저.

소유 모드(기본)에서는 진입 시 image에서 새 샌드박스를 만든다. 종료 시 종료를 요청하고 경계 있는 기간을 기다린다. sandbox_timeout은 서버 측 정리 백스톱이에요. 붙이기 모드(sandbox_id 설정)에서는 기존 샌드박스를 찾아 종료 시 실행 중으로 남겨, 다른 곳에서 관리하는 샌드박스를 실행에 걸쳐 재사용할 수 있게 한다.

Modal의 SDK는 asyncio 네이티브이므로 이 세션은 .aio 코루틴 API를 직접 구동하고 asyncio 이벤트 루프가 필요해요. Modal CLI와 SDK처럼 인증해요. modal token new가 쓴 구성에서, 또는 MODAL_TOKEN_ID/MODAL_TOKEN_SECRET 환경 변수(우선)에서요.

from pydantic_ai_harness.modal_sandbox import ModalSandboxSession

async with ModalSandboxSession(image='python:3.12-slim') as session:
    result = await session.exec(['echo', 'hello'])

속성 (Attributes)

sandbox_id

실행 중인 샌드박스의 id, 또는 실행 중이 아니면 None.

타입: str | None

메서드 (Methods)

aenter

@async

def __aenter__() -> Self

샌드박스 만들기 또는 붙기.

반환

Self

aexit

@async

def __aexit__(*args: object) -> None

소유일 때 종료 요청, 그다음 경계 있는 대기 안에서 분리 시도.

반환

None

exec

@async

def exec(
    argv: Sequence[str],
    *,
    timeout: float | None = None,
    max_output_bytes: int | None = None,
) -> ModalSandboxExecResult

샌드박스에서(셸 없이) 인자 벡터 실행하고 그 결과 반환.

Modal은 현재 실행별 kill을 노출하지 않으므로 이 코루틴 취소가 우리가 명령을 기다리는 것을 멈추지만 명령을 멈추지는 않는다. 그것은 timeout 마감(또는 샌드박스 자체가 종료될 때)까지 계속돼요. 취소·포기된 명령이 무한히 실행되지 않도록 유한 timeout을 넘기세요. timeout=None은 무경계로 남기고, 그래서 toolset이 항상 하나를 설정해요.

반환

ModalSandboxExecResult

파라미터

argv : Sequence[str]

명령과 그 인자들.

timeout : float | None 기본: None

Modal이 서버 측에서 강제하는 명령별 마감(초). None은 마감 없음(명령이 취소보다 오래 살 수 있음).

max_output_bytes : int | None 기본: None

각 스트림이 클라이언트 메모리에 보유하는 양의 상한. 명령은 호출자가 모델에게 보여줄 것보다 훨씬 더 많이 인쇄할 수 있으므로, 설정하면 각 스트림의 마지막 max_output_bytes 바이트만 정확히 유지돼요. 보유된 바이트 접미사는 멀티바이트 문자 안에서 시작할 수 있고 대체로 디코딩돼요. None은 각 스트림을 통째로 읽는다 — 직접 세션 호출자의 작은 출력에는 좋지만, toolset은 항상 설정해요.

file_size

@async

def file_size(path: str) -> int

Modal 파일시스템 API로 파일의 바이트 크기를 반환, 읽지 않고.

호출자가 전체 파일을 읽기 전에 크기를 확인하게 해요. 상대 path는 샌드박스 작업 디렉터리에 대해 해석된다(_resolve 참고).

반환

int

발생

ModalSandboxError — 파일을 stat할 수 없을 때(누락, 디렉터리, ...).

read_bytes

@async

def read_bytes(path: str) -> bytes

Modal 파일시스템 API로 샌드박스에서 파일의 원시 바이트를 읽음.

세션이 바이트로 다루므로 각 도구 계층이 필요에 따라 디코딩(또는 안 함)하고, 텍스트 처리는 세션이 아니라 위에 있어요. 상대 path는 샌드박스 작업 디렉터리에 대해 해석된다(_resolve 참고).

반환

bytes

발생

ModalSandboxError — 파일을 읽을 수 없을 때(누락, 디렉터리, ...).

write_bytes

@async

def write_bytes(path: str, data: bytes) -> None

샌드박스의 파일에 원시 바이트를 쓰고, 부모 디렉터리 생성.

상대 path는 샌드박스 작업 디렉터리에 대해 해석된다(_resolve 참고). 셸로 나가는 것과 달리 Modal의 파일시스템 API는 콘텐츠를 스트리밍하므로 크기가 명령의 인자 길이 한도에 묶이지 않고, 부모 디렉터리를 스스로 만든다.

반환

None

발생

ModalSandboxError — 파일을 쓸 수 없을 때(나쁜 경로, 권한, ...).

list_files

@async

def list_files(path: str) -> list[tuple[str, bool]]

샌드박스 디렉터리를 (name, is_dir) 쌍으로 나열.

상대 path는 샌드박스 작업 디렉터리에 대해 해석된다(_resolve 참고). Modal 네이티브 FileInfo 항목은 여기서 프라이빗 타입이 세션을 넘지 않도록 평문 튜플로 정규화된다.

반환

list[tuple[str, bool]]

발생

ModalSandboxError — 디렉터리를 나열할 수 없을 때.

ModalSandboxExecResult

샌드박스에서 명령 실행의 결과.

속성 (Attributes)

stdout

명령의 표준 출력, max_output_bytes가 설정되면 꼬리 절단.

타입: str

stderr

명령의 표준 오류, max_output_bytes가 설정되면 꼬리 절단.

타입: str

returncode

종료 상태: 실제 종료면 0-255(시그널 n에 128+n), 또는 Modal의 -1 마감 센티널.

타입: int

stdout_truncated

max_output_bytes가 더 이른 stdout 바이트를 버렸으면 True; stdout은 보유된 꼬리.

타입: bool 기본: False

stderr_truncated

max_output_bytes가 더 이른 stderr 바이트를 버렸으면 True; stderr은 보유된 꼬리.

타입: bool 기본: False

timed_out

마감이 적용되고 명령이 그것에 죽었으면 True.

Modal은 클라이언트 측 마감 kill을 returncode -1로 보고하고, 같은 마감의 서버 측 kill은 평문 SIGKILL 종료(137)로 표면화되므로, 그 종료도 명령이 전체 마감 윈도우를 소비했을 때 타임아웃으로 읽힌다.

타입: bool 기본: False

applied_timeout

Modal이 이 명령에 강제한 정수-초 마감, 또는 무경계면 None.

이것은 호출자가 요청한(어쩌면 분수의) 타임아웃이 아니라 Modal에 실제로 보내진 양자화된 값이라, 호출자가 정확한 마감을 보고할 수 있어요.

타입: int | None 기본: None

ModalSandboxError

Bases: RuntimeError

Modal 샌드박스 통합이 보고하는 실패의 베이스 클래스.

toolset은 직접 인스턴스를 ModelRetry로 바꾼다. 종료 서브클래스는 재시도가 누락된 샌드박스나 자격 증명을 복원할 수 없으므로 전파된다.

ModalSandboxTerminalError

Bases: ModalSandboxError

재시도가 고칠 수 없는 샌드박스 실패라, 실행이 루프가 아니라 끝나야 한다.

toolset은 이것을 ModelRetry로 바꾸는 대신 도구 밖으로 전파(실행 종료)시킨다. 같은 명령을 재발행하면 같은 벽에 부딪히니까. 더 이상 존재하지 않는 샌드박스는 ModalSandboxUnavailableError로, 거부된 자격 증명은 ModalSandboxAuthError로 발생된다.

ModalSandboxAuthError

Bases: ModalSandboxTerminalError

Modal이 자격 증명을 거부해 어떤 샌드박스 연산도 성공할 수 없다.

이것을 고치는 것은 운영자 동작(자격 증명 구성)이지 재시도나 새 실행이 할 수 있는 게 아니므로 종료다.

ModalSandboxUnavailableError

Bases: ModalSandboxTerminalError

샌드박스가 더 이상 존재하지 않는다: 종료됐거나 sandbox_timeout에서 만료.

그에 대한 이후의 모든 명령이 같은 방식으로 실패하므로 종료다. 소유 모드에서 이것은 실행이 샌드박스 수명보다 오래 사는 모습이고, 실행이 합법적으로 더 오래 필요하면 sandbox_timeout을 올리거나 작업을 줄여라.

더 알아보기 (Learn more)

Modal sandboxes — Modal 문서.
Pydantic AI Harness — 패키지 전반.