langchain-modal為 Deep Agents 接入 Modal 云沙箱的官方集成指南【免費(fèi)下載鏈接】deepagentsThe batteries-included agent harness.項目地址: https://gitcode.com/GitHub_Trending/de/deepagents本篇技術(shù)指南介紹 Deep Agents 官方合作伙伴包langchain-modal它把 Modal 的云端沙箱modal.Sandbox封裝為符合 Deep AgentsSandboxBackendProtocol的后端實(shí)現(xiàn)讓 Agent 可以在 Modal 托管的隔離環(huán)境中執(zhí)行 Shell 命令、上傳與下載文件。閱讀本文后你將掌握從安裝、創(chuàng)建沙箱到調(diào)用execute/upload_files/download_files的完整鏈路并能理解其與 Deep Agents 后端協(xié)議對接的底層原理。一、背景Deep Agents 的可插拔沙箱后端Deep Agents 是一個開箱即用batteries-included的 Agent 編排框架。為了讓 Agent 擁有可執(zhí)行命令、讀寫文件的隔離運(yùn)行環(huán)境Deep Agents 在 libs/deepagents/deepagents/backends/protocol.py 中定義了統(tǒng)一的BackendProtocol與SandboxBackendProtocolBackendProtocol定義了文件類操作read、write、edit、delete、ls、grep、glob、upload_files、download_files等SandboxBackendProtocol在BackendProtocol之上擴(kuò)展了 Shell 命令執(zhí)行能力execute/aexecute與沙箱唯一標(biāo)識id屬性面向容器、虛擬機(jī)、遠(yuǎn)程主機(jī)等隔離環(huán)境。在此基礎(chǔ)上libs/deepagents/deepagents/backends/sandbox.py 提供了BaseSandbox基類它把文件列舉、grep、glob、read 等操作全部用 Shell 命令經(jīng)execute()派生實(shí)現(xiàn)具體后端只需要實(shí)現(xiàn)execute()與upload_files()兩個原語。langchain-modal正是這樣一款合作伙伴后端它把 Modal 的云端沙箱對象包裝成一個 Deep Agents 后端讓同一個 Agent 編排邏輯可以無縫運(yùn)行在 Modal 的 GPU/CPU 基礎(chǔ)設(shè)施上。二、安裝langchain-modal已發(fā)布為獨(dú)立的 PyPI 包推薦使用uv安裝uv add langchain-modal從 pyproject.toml 可以看出包的基本約束Python 版本要求3.11,4.0同時聲明了對 3.113.14 的兼容性核心依賴deepagents0.7.0,0.8.0后端協(xié)議與BaseSandbox基類以及modalModal 官方 Python SDK開發(fā)階段倉庫通過[tool.uv.sources]將deepagents指向本地libs/deepagents的可編輯安裝便于在 monorepo 內(nèi)聯(lián)調(diào)試。包對外暴露的唯一入口是ModalSandbox類見 libs/partners/modal/langchain_modal/init.py。三、快速上手創(chuàng)建沙箱并執(zhí)行命令libs/partners/modal/README.md 給出了最簡用法把已有的modal.Sandbox實(shí)例包裝為ModalSandbox即可調(diào)用execute執(zhí)行命令import modal from langchain_modal import ModalSandbox sandbox ModalSandbox(modal.Sandbox.create(appmodal.App.lookup(your-app))) result sandbox.execute(echo hello) print(result.output)幾個要點(diǎn)ModalSandbox包裝的是已經(jīng)存在的 Modal 沙箱構(gòu)造函數(shù)是關(guān)鍵字參數(shù)ModalSandbox(*, sandbox: modal.Sandbox)你負(fù)責(zé)創(chuàng)建并持有modal.Sandbox的生命周期execute返回ExecuteResponse其中output是合并后的 stdoutstderr 文本exit_code是命令退出碼truncated表示輸出是否因后端限制被截斷execute底層是bash -c從 sandbox.py 的實(shí)現(xiàn)看命令經(jīng)由self._sandbox.exec(bash, -c, command, timeout...)發(fā)起。如果想要從零創(chuàng)建沙箱而不是App.lookup可以參考集成測試 tests/integration_tests/test_integration.py 的寫法import modal def _create_modal_sandbox() - modal.Sandbox: sandbox modal.Sandbox.create( python:3.11-slim, secrets[modal.Secret.from_name(modal-token)], ) sandbox.wait() return sandbox四、ModalSandbox核心 API 詳解ModalSandbox定義在 libs/partners/modal/langchain_modal/sandbox.py繼承自BaseSandbox是協(xié)議SandboxBackendProtocol的一個具體實(shí)現(xiàn)。核心成員如下4.1 構(gòu)造與標(biāo)識def __init__(self, *, sandbox: modal.Sandbox) - None: self._sandbox sandbox self._default_timeout 30 * 60sandbox被包裝的 Modal 沙箱實(shí)例必須是關(guān)鍵字參數(shù)_default_timeout默認(rèn)命令超時30 分鐘所有未顯式指定timeout的execute調(diào)用都會使用它id屬性返回self._sandbox.object_id作為該后端實(shí)例的唯一標(biāo)識供上層 Agent 跟蹤會話。4.2 命令執(zhí)行executedef execute(self, command: str, *, timeout: int | None None) - ExecuteResponse: effective_timeout timeout if timeout is not None else self._default_timeout process self._sandbox.exec(bash, -c, command, timeouteffective_timeout) process.wait() stdout process.stdout.read() stderr process.stderr.read() output stdout or if stderr: output \n stderr if output else stderr return ExecuteResponse( outputoutput, exit_codeprocess.returncode, truncatedFalse, )需要特別注意的語義timeout0表示無限期等待這是 Modal 實(shí)現(xiàn)的特殊約定與SandboxBackendProtocol文檔中0 可能在后端禁用超時的說明一致見 protocol.py 中SandboxBackendProtocol.execute的 docstringoutput會合并 stdout 與 stderr且優(yōu)先展示 stdoutstderr 以換行符銜接便于 LLM 一次性讀取完整命令結(jié)果truncated恒為False當(dāng)前實(shí)現(xiàn)不做輸出大小裁剪完整輸出直接返回execute接受可選的timeout關(guān)鍵字因此可以通過協(xié)議層execute_accepts_timeout的運(yùn)行時檢測兼容所有調(diào)用方。4.3 文件上傳與下載def upload_files(self, files: list[tuple[str, bytes]]) - list[FileUploadResponse]: return [self._write_file(path, content) for path, content in files] def download_files(self, paths: list[str]) - list[FileDownloadResponse]: return [self._read_file(path) for path in paths]底層_read_file/_write_file直接使用 Modal 沙箱的sandbox.open(path, rb/wb)文件句柄讀寫路徑必須為絕對路徑以/開頭否則直接返回invalid_path錯誤碼讀取時對memoryview會轉(zhuǎn)換為bytes字符串會按 UTF-8 編碼錯誤碼做了協(xié)議級歸一化FileNotFoundError→file_not_foundModal 的FilesystemExecutionError會根據(jù)消息內(nèi)容區(qū)分為is_directory提示信息包含 is a directory或file_not_found寫入遇到PermissionError→permission_denied。返回的FileUploadResponse/FileDownloadResponse均為批量接口響應(yīng)順序與輸入順序一一對應(yīng)每個條目攜帶獨(dú)立的error字段允許部分成功例如{path: /app/data.txt, content: b..., error: None}與{path: /wrong/path.txt, content: None, error: file_not_found}。4.4 繼承而來的文件操作由于繼承BaseSandboxModalSandbox無需重新實(shí)現(xiàn)即可獲得完整的文件操作能力包括read服務(wù)端分頁讀取、write先os.makedirs創(chuàng)建父目錄再上傳內(nèi)容、edit服務(wù)端字符串替換、ls、grep字面量匹配、glob帶**通配與花括號展開的路徑匹配等。這些操作全部經(jīng)由execute(bash, -c, ...)在 Modal 沙箱內(nèi)部以 Python 內(nèi)聯(lián)腳本完成參數(shù)使用 base64 編碼傳遞以避免 Shell 轉(zhuǎn)義問題并帶有MAX_MATCHES、時間預(yù)算等防失控保護(hù)。換一個后端如本地文件系統(tǒng)或 DockerAgent 得到的接口與行為保持一致——這正是后端協(xié)議抽象的價值所在。五、與 Deep Agents 后端協(xié)議的對接方式從類型層面看ModalSandbox滿足 protocol.py 中的SandboxBackendProtocolBackendProtocol ├── 文件操作ls / read / grep / glob / write / edit / delete / upload_files / download_files └── SandboxBackendProtocol繼承并擴(kuò)展 ├── id 屬性沙箱唯一標(biāo)識 └── execute(command, *, timeout) - ExecuteResponseModalSandbox直接實(shí)現(xiàn)了execute()、upload_files()、download_files()與id其余文件操作由BaseSandbox基于execute()派生見 sandbox.py 模塊 docstring。這意味著上層 Agent 工具層只需面向協(xié)議編程不感知底層是 Modal、Docker 還是本地文件系統(tǒng)ExecuteResponse為 LLM 消費(fèi)做了簡化輸出、退出碼、截斷標(biāo)記三要素齊全且status與exit_code分離——命令即使非零退出也被視為已執(zhí)行成功模型需要閱讀輸出自行判斷。六、測試與驗(yàn)證langchain-modal配套了單元測試與集成測試兩類驗(yàn)證手段。單元測試tests/unit_tests/test_import.py 與 tests/test_import.py只做導(dǎo)入冒煙驗(yàn)證確保langchain_modal包在無 Modal 憑據(jù)的環(huán)境下也能正常導(dǎo)入。集成測試tests/integration_tests/test_integration.py則真正在云端運(yùn)行從環(huán)境變量讀取憑據(jù)MODAL_TOKEN_ID與MODAL_TOKEN_SECRET缺失時直接拋錯并提示設(shè)置通過_create_modal_sandbox()創(chuàng)建python:3.11-slim沙箱并注入名為modal-token的 Secret用ModalSandbox(sandboxsandbox)包裝后交給langchain_tests.integration_tests.SandboxIntegrationTests這一共享測試基類跑一套標(biāo)準(zhǔn)化的沙箱行為契約測試測試結(jié)束在finally中調(diào)用sandbox.terminate()釋放云端資源。MakefileMakefile提供了便捷入口make test # 運(yùn)行單元測試禁用網(wǎng)絡(luò)僅允許 unix socket make integration_test # 運(yùn)行集成測試需先導(dǎo)出 MODAL_TOKEN_ID / MODAL_TOKEN_SECRET make lint # ruff 檢查 ty 類型檢查 make type # 僅運(yùn)行 ty 類型檢查ty check langchain_modal七、版本與依賴說明當(dāng)前倉庫中的langchain-modal版本為0.0.6見 pyproject.toml 與 _version.py后者帶有x-release-please-version注解由 release-please 在發(fā)布時與 pyproject 同步升版依賴deepagents0.7.0,0.8.0使用時請確保兩者版本兼容許可證為 MITPython 3.11 可用。小結(jié)langchain-modal是 Deep Agents 官方生態(tài)中接入 Modal 云沙箱的最簡路徑安裝一個包、包裝一個modal.Sandbox即可獲得協(xié)議完備的execute、文件上傳下載與全套派生文件操作。結(jié)合本倉庫 libs/deepagents/deepagents/backends/protocol.py 與 sandbox.py 閱讀源碼你可以清晰看到協(xié)議定義 → 基類派生 → 具體后端的三層設(shè)計并據(jù)此理解其他合作伙伴后端如 Daytona、Runloop、Vercel Sandbox 等的實(shí)現(xiàn)方式?！久赓M(fèi)下載鏈接】deepagentsThe batteries-included agent harness.項目地址: https://gitcode.com/GitHub_Trending/de/deepagents創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 langchain-modal：為 Deep Agents 接入 Modal 云沙箱的官方集成指南
langchain-modal為 Deep Agents 接入 Modal 云沙箱的官方集成指南【免費(fèi)下載鏈接】deepagentsThe batteries-included agent harness.項目地址: https://gitcode.com/GitHub_Trending/de/deepagents本篇技術(shù)指南介紹 Deep Agents 官方合作伙伴包langchain-modal它把 Modal 的云端沙箱modal.Sandbox封裝為符合 Deep AgentsSandboxBackendProtocol的后端實(shí)現(xiàn)讓 Agent 可以在 Modal 托管的隔離環(huán)境中執(zhí)行 Shell 命令、上傳與下載文件。閱讀本文后你將掌握從安裝、創(chuàng)建沙箱到調(diào)用execute/upload_files/download_files的完整鏈路并能理解其與 Deep Agents 后端協(xié)議對接的底層原理。一、背景Deep Agents 的可插拔沙箱后端Deep Agents 是一個開箱即用batteries-included的 Agent 編排框架。為了讓 Agent 擁有可執(zhí)行命令、讀寫文件的隔離運(yùn)行環(huán)境Deep Agents 在 libs/deepagents/deepagents/backends/protocol.py 中定義了統(tǒng)一的BackendProtocol與SandboxBackendProtocolBackendProtocol定義了文件類操作read、write、edit、delete、ls、grep、glob、upload_files、download_files等SandboxBackendProtocol在BackendProtocol之上擴(kuò)展了 Shell 命令執(zhí)行能力execute/aexecute與沙箱唯一標(biāo)識id屬性面向容器、虛擬機(jī)、遠(yuǎn)程主機(jī)等隔離環(huán)境。在此基礎(chǔ)上libs/deepagents/deepagents/backends/sandbox.py 提供了BaseSandbox基類它把文件列舉、grep、glob、read 等操作全部用 Shell 命令經(jīng)execute()派生實(shí)現(xiàn)具體后端只需要實(shí)現(xiàn)execute()與upload_files()兩個原語。langchain-modal正是這樣一款合作伙伴后端它把 Modal 的云端沙箱對象包裝成一個 Deep Agents 后端讓同一個 Agent 編排邏輯可以無縫運(yùn)行在 Modal 的 GPU/CPU 基礎(chǔ)設(shè)施上。二、安裝langchain-modal已發(fā)布為獨(dú)立的 PyPI 包推薦使用uv安裝uv add langchain-modal從 pyproject.toml 可以看出包的基本約束Python 版本要求3.11,4.0同時聲明了對 3.113.14 的兼容性核心依賴deepagents0.7.0,0.8.0后端協(xié)議與BaseSandbox基類以及modalModal 官方 Python SDK開發(fā)階段倉庫通過[tool.uv.sources]將deepagents指向本地libs/deepagents的可編輯安裝便于在 monorepo 內(nèi)聯(lián)調(diào)試。包對外暴露的唯一入口是ModalSandbox類見 libs/partners/modal/langchain_modal/init.py。三、快速上手創(chuàng)建沙箱并執(zhí)行命令libs/partners/modal/README.md 給出了最簡用法把已有的modal.Sandbox實(shí)例包裝為ModalSandbox即可調(diào)用execute執(zhí)行命令import modal from langchain_modal import ModalSandbox sandbox ModalSandbox(modal.Sandbox.create(appmodal.App.lookup(your-app))) result sandbox.execute(echo hello) print(result.output)幾個要點(diǎn)ModalSandbox包裝的是已經(jīng)存在的 Modal 沙箱構(gòu)造函數(shù)是關(guān)鍵字參數(shù)ModalSandbox(*, sandbox: modal.Sandbox)你負(fù)責(zé)創(chuàng)建并持有modal.Sandbox的生命周期execute返回ExecuteResponse其中output是合并后的 stdoutstderr 文本exit_code是命令退出碼truncated表示輸出是否因后端限制被截斷execute底層是bash -c從 sandbox.py 的實(shí)現(xiàn)看命令經(jīng)由self._sandbox.exec(bash, -c, command, timeout...)發(fā)起。如果想要從零創(chuàng)建沙箱而不是App.lookup可以參考集成測試 tests/integration_tests/test_integration.py 的寫法import modal def _create_modal_sandbox() - modal.Sandbox: sandbox modal.Sandbox.create( python:3.11-slim, secrets[modal.Secret.from_name(modal-token)], ) sandbox.wait() return sandbox四、ModalSandbox核心 API 詳解ModalSandbox定義在 libs/partners/modal/langchain_modal/sandbox.py繼承自BaseSandbox是協(xié)議SandboxBackendProtocol的一個具體實(shí)現(xiàn)。核心成員如下4.1 構(gòu)造與標(biāo)識def __init__(self, *, sandbox: modal.Sandbox) - None: self._sandbox sandbox self._default_timeout 30 * 60sandbox被包裝的 Modal 沙箱實(shí)例必須是關(guān)鍵字參數(shù)_default_timeout默認(rèn)命令超時30 分鐘所有未顯式指定timeout的execute調(diào)用都會使用它id屬性返回self._sandbox.object_id作為該后端實(shí)例的唯一標(biāo)識供上層 Agent 跟蹤會話。4.2 命令執(zhí)行executedef execute(self, command: str, *, timeout: int | None None) - ExecuteResponse: effective_timeout timeout if timeout is not None else self._default_timeout process self._sandbox.exec(bash, -c, command, timeouteffective_timeout) process.wait() stdout process.stdout.read() stderr process.stderr.read() output stdout or if stderr: output \n stderr if output else stderr return ExecuteResponse( outputoutput, exit_codeprocess.returncode, truncatedFalse, )需要特別注意的語義timeout0表示無限期等待這是 Modal 實(shí)現(xiàn)的特殊約定與SandboxBackendProtocol文檔中0 可能在后端禁用超時的說明一致見 protocol.py 中SandboxBackendProtocol.execute的 docstringoutput會合并 stdout 與 stderr且優(yōu)先展示 stdoutstderr 以換行符銜接便于 LLM 一次性讀取完整命令結(jié)果truncated恒為False當(dāng)前實(shí)現(xiàn)不做輸出大小裁剪完整輸出直接返回execute接受可選的timeout關(guān)鍵字因此可以通過協(xié)議層execute_accepts_timeout的運(yùn)行時檢測兼容所有調(diào)用方。4.3 文件上傳與下載def upload_files(self, files: list[tuple[str, bytes]]) - list[FileUploadResponse]: return [self._write_file(path, content) for path, content in files] def download_files(self, paths: list[str]) - list[FileDownloadResponse]: return [self._read_file(path) for path in paths]底層_read_file/_write_file直接使用 Modal 沙箱的sandbox.open(path, rb/wb)文件句柄讀寫路徑必須為絕對路徑以/開頭否則直接返回invalid_path錯誤碼讀取時對memoryview會轉(zhuǎn)換為bytes字符串會按 UTF-8 編碼錯誤碼做了協(xié)議級歸一化FileNotFoundError→file_not_foundModal 的FilesystemExecutionError會根據(jù)消息內(nèi)容區(qū)分為is_directory提示信息包含 is a directory或file_not_found寫入遇到PermissionError→permission_denied。返回的FileUploadResponse/FileDownloadResponse均為批量接口響應(yīng)順序與輸入順序一一對應(yīng)每個條目攜帶獨(dú)立的error字段允許部分成功例如{path: /app/data.txt, content: b..., error: None}與{path: /wrong/path.txt, content: None, error: file_not_found}。4.4 繼承而來的文件操作由于繼承BaseSandboxModalSandbox無需重新實(shí)現(xiàn)即可獲得完整的文件操作能力包括read服務(wù)端分頁讀取、write先os.makedirs創(chuàng)建父目錄再上傳內(nèi)容、edit服務(wù)端字符串替換、ls、grep字面量匹配、glob帶**通配與花括號展開的路徑匹配等。這些操作全部經(jīng)由execute(bash, -c, ...)在 Modal 沙箱內(nèi)部以 Python 內(nèi)聯(lián)腳本完成參數(shù)使用 base64 編碼傳遞以避免 Shell 轉(zhuǎn)義問題并帶有MAX_MATCHES、時間預(yù)算等防失控保護(hù)。換一個后端如本地文件系統(tǒng)或 DockerAgent 得到的接口與行為保持一致——這正是后端協(xié)議抽象的價值所在。五、與 Deep Agents 后端協(xié)議的對接方式從類型層面看ModalSandbox滿足 protocol.py 中的SandboxBackendProtocolBackendProtocol ├── 文件操作ls / read / grep / glob / write / edit / delete / upload_files / download_files └── SandboxBackendProtocol繼承并擴(kuò)展 ├── id 屬性沙箱唯一標(biāo)識 └── execute(command, *, timeout) - ExecuteResponseModalSandbox直接實(shí)現(xiàn)了execute()、upload_files()、download_files()與id其余文件操作由BaseSandbox基于execute()派生見 sandbox.py 模塊 docstring。這意味著上層 Agent 工具層只需面向協(xié)議編程不感知底層是 Modal、Docker 還是本地文件系統(tǒng)ExecuteResponse為 LLM 消費(fèi)做了簡化輸出、退出碼、截斷標(biāo)記三要素齊全且status與exit_code分離——命令即使非零退出也被視為已執(zhí)行成功模型需要閱讀輸出自行判斷。六、測試與驗(yàn)證langchain-modal配套了單元測試與集成測試兩類驗(yàn)證手段。單元測試tests/unit_tests/test_import.py 與 tests/test_import.py只做導(dǎo)入冒煙驗(yàn)證確保langchain_modal包在無 Modal 憑據(jù)的環(huán)境下也能正常導(dǎo)入。集成測試tests/integration_tests/test_integration.py則真正在云端運(yùn)行從環(huán)境變量讀取憑據(jù)MODAL_TOKEN_ID與MODAL_TOKEN_SECRET缺失時直接拋錯并提示設(shè)置通過_create_modal_sandbox()創(chuàng)建python:3.11-slim沙箱并注入名為modal-token的 Secret用ModalSandbox(sandboxsandbox)包裝后交給langchain_tests.integration_tests.SandboxIntegrationTests這一共享測試基類跑一套標(biāo)準(zhǔn)化的沙箱行為契約測試測試結(jié)束在finally中調(diào)用sandbox.terminate()釋放云端資源。MakefileMakefile提供了便捷入口make test # 運(yùn)行單元測試禁用網(wǎng)絡(luò)僅允許 unix socket make integration_test # 運(yùn)行集成測試需先導(dǎo)出 MODAL_TOKEN_ID / MODAL_TOKEN_SECRET make lint # ruff 檢查 ty 類型檢查 make type # 僅運(yùn)行 ty 類型檢查ty check langchain_modal七、版本與依賴說明當(dāng)前倉庫中的langchain-modal版本為0.0.6見 pyproject.toml 與 _version.py后者帶有x-release-please-version注解由 release-please 在發(fā)布時與 pyproject 同步升版依賴deepagents0.7.0,0.8.0使用時請確保兩者版本兼容許可證為 MITPython 3.11 可用。小結(jié)langchain-modal是 Deep Agents 官方生態(tài)中接入 Modal 云沙箱的最簡路徑安裝一個包、包裝一個modal.Sandbox即可獲得協(xié)議完備的execute、文件上傳下載與全套派生文件操作。結(jié)合本倉庫 libs/deepagents/deepagents/backends/protocol.py 與 sandbox.py 閱讀源碼你可以清晰看到協(xié)議定義 → 基類派生 → 具體后端的三層設(shè)計并據(jù)此理解其他合作伙伴后端如 Daytona、Runloop、Vercel Sandbox 等的實(shí)現(xiàn)方式?！久赓M(fèi)下載鏈接】deepagentsThe batteries-included agent harness.項目地址: https://gitcode.com/GitHub_Trending/de/deepagents創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考