Hộp cát phương thức

ModalSandbox cung cấp cho một agent một vùng chứa đám mây riêng biệt để chạy các lệnh và làm việc với các tập tin. Sử dụng nó để mã hóa, xử lý dữ liệu và các tác vụ khác không nên thực thi các lệnh do mô hình tạo trên máy chủ ứng dụng.

Khả năng bổ sung thêm các công cụ shell và file được hỗ trợ bởi một Hộp cát phương thức. Theo mặc định, mọi agent run nhận được một hộp cát mới được tạo từ hình ảnh vùng chứa. Các yêu cầu về năng lực chấm dứt khi quá trình chạy kết thúc. Bạn cũng có thể đính kèm hộp cát hiện có hoặc tái sử dụng một trong nhiều lần chạy.

Mặc dù Pydantic AI Harness có trên các bản phát hành 0.x nhưng API có thể thay đổi giữa các bản phát hành nhỏ; khi đó, cảnh báo ngừng sử dụng và hướng dẫn di chuyển ghi chú phát hành sẽ cho bạn (hoặc người đại diện của bạn) biết chính xác cách nâng cấp. Xem chính sách phiên bản.

Bắt đầu nhanh

Cài đặt modal bổ sung và xác thực bằng Modal CLI. Trong CI, đặt MODAL_TOKEN_ID và MODAL_TOKEN_SECRET thay vào đó.

uv add "pydantic-ai-harness[modal]"
modal token new                # writes ~/.modal.toml
# or, e.g. in CI:
export MODAL_TOKEN_ID=...
export MODAL_TOKEN_SECRET=...

Thêm ModalSandbox tới agent:

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)

Trong quá trình chạy, agent có thể tạo tệp, kiểm tra thư mục làm việc của nó, chạy lệnh và phản ứng với các lỗi lệnh. Hộp cát tách biệt với máy chủ hệ thống tập tin và không gian xử lý.

Khả năng này đóng góp bốn công cụ:

Lệnh đầu ra nhãn stdout và stderr và báo cáo mã thoát khác 0 cho mô hình. Nó giữ lại phần đuôi khi cắt bớt, vì vậy các chẩn đoán sau này vẫn có thể nhìn thấy được. Việc đọc tệp giữ nguyên phần đầu và trả về phần bù dòng tiếp theo khi có nhiều nội dung hơn có sẵn.

Vòng đời

Theo mặc định, mỗi lần chạy agent sẽ tạo một hộp cát thuộc sở hữu và yêu cầu chấm dứt nó khi quá trình chạy kết thúc, do đó, hãy dự kiến chi phí khởi động nguội cho mỗi lần chạy. Sự sụp đổ đang chờ đợi xác nhận trong một khoảng thời gian giới hạn; nếu mặt phẳng điều khiển không phản hồi, sandbox_timeout vẫn là điểm dừng dọn dẹp phía máy chủ. Hộp cát là được cung cấp khi quá trình chạy vào bộ công cụ khả năng, ngay cả khi không có công cụ hộp cát được gọi. Việc tải công cụ bị trì hoãn kiểm soát việc xác định công cụ nào đạt đến mô hình; nó không trì hoãn vòng đời của bộ công cụ.

Đính kèm vào hộp cát được quản lý ở nơi khác bằng ID:

from pydantic_ai_harness import ModalSandbox

ModalSandbox(sandbox_id='sb-abc123')

Để chia sẻ hộp cát qua các lần chạy trong khi kiểm soát thời gian tồn tại của nó, hãy tạo và nhập một ModalSandboxSession chính bạn:

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.')

Kích thước của phiên sandbox_timeout đến toàn bộ khối lượng công việc; 300 mặc định sẽ hết hạn giữa chừng trong phiên chạy nhiều lần. Khả năng không thể nhìn thấy một thời gian tồn tại thực của hộp cát được tái sử dụng, vì vậy mỗi lệnh ở đó được giới hạn ở mức 300 giây trừ khi max_command_timeout nâng trần nhà.

Các hộp cát được đính kèm và chèn vẫn tiếp tục chạy khi quá trình chạy agent kết thúc. Họ chia sẻ hệ thống tập tin và không gian xử lý, do đó, không sử dụng cùng một hộp cát cho các hoạt động chồng chéo cần cách ly.

Thời gian chờ và giới hạn đầu ra

Mỗi lệnh đối mặt với mô hình đều nhận được thời hạn hữu hạn. default_command_timeout cung cấp mặc định và max_command_timeout giới hạn các giá trị do mô hình cung cấp. Modal chấp nhận thời hạn cả giây, rất nhỏ các giá trị làm tròn lên mà không vượt quá mức trần số nguyên được định cấu hình.

Modal không hiển thị thao tác tiêu diệt theo lệnh. Hủy bỏ sự chờ đợi của khách hàng không dừng lệnh từ xa ngay lập tức; nó tiếp tục cho đến khi có lệnh thời hạn hoặc hộp cát bị chấm dứt.

Mỗi luồng lệnh giữ lại lệnh cuối cùng max_output_bytes sau mỗi lần vận chuyển chunk và tải trọng của mỗi luồng cũng được cắt bớt riêng biệt bằng max_output_bytes và max_output_lines trong đầu ra của công cụ, do đó, một stderr lớn không thể lấn át thiết bị xuất chuẩn và [stdout] / [stderr] nhãn luôn tồn tại. Bất kỳ vết cắt nào đều được đánh dấu. Nhãn, ghi chú cắt bớt hoặc tiếp tục và trạng thái lệnh thêm một lượng nhỏ vượt quá giới hạn tải trọng đó. Một đoạn vận chuyển có thể tạm thời lớn hơn giới hạn byte. UTF-8 không hợp lệ được decode bằng ký tự thay thế.

read_file kiểm tra siêu dữ liệu tệp trước khi đọc và kiểm tra byte trả về đếm lại. Một tập tin phát triển giữa các hoạt động đó có thể tạm thời vượt quá max_read_bytes trong bộ nhớ máy khách trước khi bị từ chối. Hệ thống tập tin của Modal API không hiển thị giá trị đọc giới hạn, vì vậy hãy sử dụng lệnh shell giới hạn cho ảo các tệp hoặc đường dẫn khác có kích thước được báo cáo có thể sai lệch.

list_directory cụ thể hóa danh sách thư mục đầy đủ trước khi cắt bớt nó. Do đó, việc liệt kê một thư mục có nhiều mục sẽ sử dụng bộ nhớ tỷ lệ với số lượng mục; sử dụng lệnh shell thu hẹp cho kích thước lớn bất thường thư mục.

SDK của Modal có nguồn gốc không đồng bộ. Khả năng này yêu cầu một vòng lặp sự kiện asyncio và không chạy theo bộ ba.

Lỗi và thành phần

Lệnh có thể phục hồi và lỗi hệ thống tệp trở thành lời nhắc thử lại mô hình. A đợt tăng hộp cát đã chấm dứt ModalSandboxUnavailableError và từ chối Modal tăng thông tin xác thực ModalSandboxAuthError (cả hai ModalSandboxTerminalError các lớp con) thay vì thử lại trên cùng một hộp cát không sử dụng được.

Bộ công cụ là một chi tiết triển khai. API cấp thấp hơn công khai bao gồm ModalSandboxSession, ModalSandboxExecResultvà lỗi hộp cát được nhập các lớp học.

Không kết hợp khả năng này với một khả năng khác không có tiền tố mà đăng ký run_command, read_file, write_filehoặc list_directory (ví dụ: Shell hoặc Khả năng của Hệ thống tệp). Pydantic AI từ chối tên công cụ trùng lặp. Tiền tố khả năng trước khi kết hợp nó với một khả năng khác sử dụng cùng tên:

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',
)

Tiền tố đổi tên các công cụ (modal_run_command, ...) nhưng không viết lại hướng dẫn mặc định của khả năng, đặt tên cho các công cụ chưa được trộn lẫn -- vượt qua instructions với văn bản khớp với tên tiền tố.

Cấu hình

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,
)

Các hướng dẫn mặc định nêu rõ các công cụ, thời gian chờ của lệnh và mức trần của nó. Đặt instructions='' để không thêm gì hoặc chuyển văn bản của riêng bạn để thay thế văn bản mặc định.

Không thể kết hợp các cài đặt chỉ được sử dụng khi tạo hộp cát với sandbox_id hoặc tiêm session. Những xung đột này thất bại trong quá trình xây dựng thay vì bị bỏ qua.

Chưa được hỗ trợ

• Đầu ra lệnh truyền phát: run_command trả về sau khi lệnh kết thúc (hoặc đạt đến thời hạn của nó), không tăng dần.
• Hình ảnh, giá treo hoặc hình ảnh được xây dựng tùy chỉnh modal.Secret: image lấy một thẻ đăng ký, và env lấy các biến môi trường đơn giản. Đối với bất cứ điều gì phong phú hơn, hãy tạo tự mình sandbox bằng Modal SDK và chuyển nó qua sandbox_id hoặc session.
• Đổ toàn bộ đầu ra vào một tệp: tệp bị cắt ngắn sẽ đọc kết thúc bằng tệp tiếp theo offset đến trang từ và các tệp quá khổ sẽ nhận được gợi ý về lát cắt shell; bị cắt cụt đầu ra lệnh nhận được một điểm đánh dấu cắt ngắn. Không có gì được ghi vào một tập tin trong hộp cát để mô hình mở.

Thông số agent

Đăng ký ModalSandbox dưới dạng loại khả năng tùy chỉnh khi tải thông số agent:

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

Tham chiếu API

• Khả năng AI của Pydantic
• Bộ công cụ AI Pydantic
• Hộp cát phương thức
• Mã nguồn Hộp cát phương thức
• Chính sách phiên bản Pydantic AI Harness

::: pydantic_ai_harness.modal_sandbox.ModalSandbox

::: pydantic_ai_harness.modal_sandbox.ModalSandboxSession

::: pydantic_ai_harness.modal_sandbox.ModalSandboxExecResult

::: pydantic_ai_harness.modal_sandbox.ModalSandboxError

::: pydantic_ai_harness.modal_sandbox.ModalSandboxTerminalError

::: pydantic_ai_harness.modal_sandbox.ModalSandboxAuthError

::: pydantic_ai_harness.modal_sandbox.ModalSandboxUnavailableError