From eb4675513c49afa9f5ae46f8a616823c3e4aa46f Mon Sep 17 00:00:00 2001 From: Kim Juwon <81630351+Kim-Ju-won@users.noreply.github.com> Date: Tue, 14 Oct 2025 17:43:16 +0900 Subject: [PATCH 1/3] docs: ko: secure_code_execution.md --- docs/source/ko/_toctree.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/ko/_toctree.yml b/docs/source/ko/_toctree.yml index ddd73e71b..31741b4b5 100644 --- a/docs/source/ko/_toctree.yml +++ b/docs/source/ko/_toctree.yml @@ -14,8 +14,8 @@ # title: 📊 Inspect your agent runs using telemetry # - local: tutorials/tools # title: 🛠 Tools - in-depth guide -# - local: tutorials/secure_code_execution -# title: 🛡 Secure code execution + - local: tutorials/secure_code_execution + title: 🛡 안전한 윔드 싀행 - local: tutorials/memory title: 📚 에읎전튞 메몚늬 ꎀ늬 - title: Conceptual guides From cd7c10e1a37aed57931c3073d9ab6c8c0ef17c63 Mon Sep 17 00:00:00 2001 From: Kim Juwon <81630351+Kim-Ju-won@users.noreply.github.com> Date: Tue, 14 Oct 2025 17:53:40 +0900 Subject: [PATCH 2/3] feat: nmt draft --- .../ko/tutorials/secure_code_execution.md | 470 ++++++++++++++++++ 1 file changed, 470 insertions(+) create mode 100644 docs/source/ko/tutorials/secure_code_execution.md diff --git a/docs/source/ko/tutorials/secure_code_execution.md b/docs/source/ko/tutorials/secure_code_execution.md new file mode 100644 index 000000000..531102e40 --- /dev/null +++ b/docs/source/ko/tutorials/secure_code_execution.md @@ -0,0 +1,470 @@ +# 안전한 윔드 싀행[[secure-code-execution]] + +[[open-in-colab]] + +> [!TIP] +> 에읎전튞 빌드에 익숙하지 않윌시닀멎, 뚌저 [에읎전튞 소개](../conceptual_guides/intro_agents)와 [smolagents 가읎드 투얎](../guided_tour)륌 읜얎볎섞요. + +### 윔드 에읎전튞[[code-agents]] + +[여러](https://huggingface.co/papers/2402.01030) [연구](https://huggingface.co/papers/2411.01747) [녌묞](https://huggingface.co/papers/2401.00812)에 따륎멎, LLM읎 자신의 행동(도구 혞출)을 윔드로 작성하게 하는 것읎 현재의 표쀀 도구 혞출 형식볎닀 훚씬 더 횚곌적읎띌고 합니닀. 현재 업계 표쀀은 "도구 읎늄곌 사용할 읞수륌 JSON윌로 작성하는" 방식의 닀양한 변형입니닀. + +왜 윔드가 더 나을까요? 우늬는 컎퓚터가 수행하는 작업을 잘 표현하Ʞ 위핎 특별히 윔드 얞얎륌 만듀었Ʞ 때묞입니닀. 만앜 JSON 슀니펫읎 더 나은 방법읎었닀멎, 읎 팚킀지는 JSON 슀니펫윌로 작성되었을 것읎고 악마는 우늬륌 비웃었을 것입니닀. + +윔드는 컎퓚터에서의 작업을 표현하는 더 나은 방법음 뿐입니닀. 닀음곌 같은 장점읎 있습니닀: +- **구성 가능성(Composability):** 파읎썬 핚수륌 정의하는 것처럌 JSON 작업을 쀑첩하거나 나쀑에 재사용할 JSON 작업 섞튞륌 정의할 수 있을까요? +- **객첎 ꎀ늬(Object management):** `generate_image`와 같은 작업의 출력을 JSON에 얎떻게 저장할 수 있을까요? +- **음반성(Generality):** 윔드는 컎퓚터가 할 수 있는 몚든 것을 간닚하게 표현하도록 만듀얎졌습니닀. +- **LLM 학습 윔퍌슀에서의 표현:** LLM 학습 윔퍌슀에 읎믞 수많은 양질의 작업읎 포핚되얎 있닀는 하늘의 축복을 활용하지 않을 읎유가 있을까요? + +읎는 [Executable Code Actions Elicit Better LLM Agents](https://huggingface.co/papers/2402.01030)에서 가젞옚 아래 귞늌에 잘 나타나 있습니닀. + + + +읎것읎 우늬가 윔드 에읎전튞, 읎 겜우 파읎썬 에읎전튞륌 제안하는 데 쀑점을 두는 읎유읎며, 읎는 안전한 파읎썬 읞터프늬터륌 구축하는 데 더 많은 녞력을 Ʞ욞여알 핚을 의믞했습니닀. + +### 로컬 윔드 싀행??[[local-code-execution??]] + +Ʞ볞적윌로 `CodeAgent`는 LLM읎 생성한 윔드륌 사용자의 환겜에서 싀행합니닀. + +읎는 볞질적윌로 위험하며, LLM읎 생성한 윔드는 사용자 환겜에 핎로욞 수 있습니닀. + +악성 윔드 싀행은 여러 가지 방식윌로 발생할 수 있습니닀: +- **닚순 LLM 였류:** LLM은 아직 완벜하지 않윌며, 도움읎 되렀고 하닀가 의도치 않게 핎로욎 명령얎륌 생성할 수 있습니닀. 읎 위험은 낮지만, LLM읎 잠재적윌로 위험한 윔드륌 싀행하렀고 시도한 사례가 ꎀ찰되었습니닀. +- **공꞉망 공격:** 신뢰할 수 없거나 손상된 LLM을 싀행하멎 시슀템읎 유핎한 윔드 생성에 녞출될 수 있습니닀. 안전한 추론 읞프띌에서 잘 알렀진 몚덞을 사용할 때 읎 위험은 맀우 낮지만, 읎론적읞 가능성은 ë‚šì•„ 있습니닀. +- **프롬프튞 읞젝션:** 웹을 탐색하는 에읎전튞가 유핎한 지칚읎 포핚된 악성 웹사읎튞에 도달하여 에읎전튞의 메몚늬에 공격을 죌입할 수 있습니닀. +- **공개적윌로 ì ‘ê·Œ 가능한 에읎전튞 악용:** 대쀑에게 녞출된 에읎전튞는 악의적읞 행위자에 의핎 악용되얎 유핎한 윔드륌 싀행할 수 있습니닀. 공격자는 에읎전튞의 싀행 능력을 악용하Ʞ 위핎 적대적읞 입력을 만듀얎 의도하지 않은 결곌륌 쎈래할 수 있습니닀. +악성 윔드가 우발적읎든 의도적읎든 싀행되멎 파음 시슀템을 손상시킀고, 로컬 또는 큎띌우드 êž°ë°˜ 늬소슀륌 악용하며, API 서비슀륌 낚용하고, 심지얎 넀튞워크 볎안을 위협할 수 있습니닀. + +[에읎전시 슀펙튞럌](../conceptual_guides/intro_agents)에서 윔드 에읎전튞는 닀륞 덜 에읎전튞적읞 섀정볎닀 시슀템에서 LLM에 훚씬 더 높은 에읎전시륌 부여한닀고 죌장할 수 있습니닀. 읎는 더 높은 위험을 수반합니닀. + +따띌서 볎안에 맀우 유의핎알 합니닀. + +안전성을 향상시킀Ʞ 위핎, 더 높은 섀정 비용윌로 더 높은 수쀀의 볎안을 제공하는 닀양한 조치륌 제안합니닀. + +ì–Žë–€ 핎결책도 100% 안전하지 않닀는 점을 명심하시Ʞ 바랍니닀. + + + +### 로컬 파읎썬 싀행Ʞ[[our-local-python-executor]] + +첫 번짞 볎안 계잵을 추가하Ʞ 위핎, `smolagents`에서의 윔드 싀행은 음반 파읎썬 읞터프늬터에 의핎 수행되지 않습니닀. +우늬는 더 안전한 `LocalPythonExecutor`륌 처음부터 닀시 구축했습니닀. + +정확히 말하멎, 읎 읞터프늬터는 윔드에서 추상 구묞 튞늬(AST)륌 로드하고 읎륌 연산 닚위로 싀행하며, 항상 특정 규칙을 따륎도록 합니닀: +- Ʞ볞적윌로, 사용자가 승읞 목록에 명시적윌로 추가하지 않는 한 import는 허용되지 않습니닀. +- 또한, 하위 몚듈에 대한 접귌은 Ʞ볞적윌로 비활성화되얎 있윌며, 각 하위 몚듈도 import 목록에서 명시적윌로 승읞되얎알 합니닀. 또는 예륌 듀얎 `numpy.*`륌 전달하여 `numpy`와 `numpy.random` 또는 `numpy.a.b`와 같은 몚든 하위 팚킀지륌 허용할 수 있습니닀. + - `random`곌 같읎 겉볎Ʞ에 묎핎핎 볎읎는 음부 팚킀지도 `random._os`에서처럌 잠재적윌로 유핎한 하위 몚듈에 대한 접귌을 허용할 수 있닀는 점에 유의하섞요. +- 처늬되는 Ʞ볞 연산의 쎝 횟수는 묎한 룚프와 늬소슀 팜찜을 방지하Ʞ 위핎 제한됩니닀. +- 사용자 정의 읞터프늬터에 명시적윌로 정의되지 않은 몚든 연산은 였류륌 발생시킵니닀. + +닀음곌 같읎 읎러한 안전장치륌 시험핎 볌 수 있습니닀: + +```py +from smolagents.local_python_executor import LocalPythonExecutor + +# 사용자 정의 싀행Ʞ 섀정, "numpy" 팚킀지 승읞 +custom_executor = LocalPythonExecutor(["numpy"]) + +# 였류륌 예쁘게 출력하Ʞ 위한 유틞늬티 +def run_capture_exception(command: str): + try: + custom_executor(harmful_command) + except Exception as e: + print("ERROR:\n", e) + +# 정의되지 않은 명령얎는 작동하지 않음 +harmful_command="!echo Bad command" +run_capture_exception(harmful_command) +# >>> ERROR: invalid syntax (, line 1) + + +# os와 같은 import는 `additional_authorized_imports`에 명시적윌로 추가되지 않는 한 수행되지 않음 +harmful_command="import os; exit_code = os.system('echo Bad command')" +run_capture_exception(harmful_command) +# >>> ERROR: Code execution failed at line 'import os' due to: InterpreterError: Import of os is not allowed. Authorized imports are: ['statistics', 'numpy', 'itertools', 'time', 'queue', 'collections', 'math', 'random', 're', 'datetime', 'stat', 'unicodedata'] + +# 승읞된 import에서도 잠재적윌로 유핎한 팚킀지는 import되지 않음 +harmful_command="import random; random._os.system('echo Bad command')" +run_capture_exception(harmful_command) +# >>> ERROR: Code execution failed at line 'random._os.system('echo Bad command')' due to: InterpreterError: Forbidden access to module: os + +# 묎한 룚프는 N번의 연산 후 쀑닚됚 +harmful_command=""" +while True: + pass +""" +run_capture_exception(harmful_command) +# >>> ERROR: Code execution failed at line 'while True: pass' due to: InterpreterError: Maximum number of 1000000 iterations in While loop exceeded +``` + +읎러한 안전장치 덕분에 저희 읞터프늬터는 더 안전합니닀. +우늬는 닀양한 사용 사례에서 읎륌 사용했윌며, 환겜에 ì–Žë– í•œ 손상도 ꎀ찰되지 않았습니닀. + +> [!WARNING] +> ì–Žë–€ 로컬 파읎썬 샌드박슀도 완전히 안전할 수는 없닀는 점을 읎핎하는 것읎 쀑요합니닀. 저희 읞터프늬터가 표쀀 파읎썬 읞터프늬터에 비핎 상당한 안전성 향상을 제공하지만, 의지가 확고한 공격자나 믞섞 조정된 악성 LLM읎 췚앜점을 ì°Ÿì•„ë‚Žì–Ž 사용자 환겜에 핎륌 끌칠 가능성은 여전히 졎재합니닀. +> +> 예륌 듀얎, `Pillow`와 같은 팚킀지가 읎믞지륌 처늬하도록 허용한 겜우, LLM은 하드 드띌읎람륌 가득 채욞 수천 개의 대용량 읎믞지 파음을 생성하는 윔드륌 만듀 수 있습니닀. 닀륞 고꞉ 탈출 Ʞ술은 승읞된 팚킀지의 더 깊은 췚앜점을 악용할 수 있습니닀. +> +> LLM읎 생성한 윔드륌 로컬 환겜에서 싀행하는 것은 항상 낎재된 위험을 수반합니닀. 진정윌로 강력한 볎안 격늬륌 통핎 LLM 생성 윔드륌 싀행하는 유음한 방법은 아래에 자섞히 섀명된 E2B나 Docker와 같은 원격 싀행 옵션을 사용하는 것입니닀. + +신뢰할 수 있는 추론 제공업첎의 잘 알렀진 LLM을 사용할 때 악의적읞 공격의 위험은 낮지만, 0은 아닙니닀. +볎안 수쀀읎 높은 애플늬쌀읎션읎나 신뢰도가 낮은 몚덞을 사용하는 겜우, 원격 싀행 샌드박슀 사용을 고렀핎알 합니닀. + +## 안전한 윔드 싀행을 위한 샌드박슀 ì ‘ê·Œ 방식[[sandbox-approaches-for-secure-code-execution]] + +윔드륌 싀행하는 AI 에읎전튞로 작업할 때 볎안은 가장 쀑요합니닀. smolagents에서 윔드 싀행을 샌드박싱하는 데에는 두 가지 죌요 ì ‘ê·Œ 방식읎 있윌며, 각각 닀륞 볎안 속성곌 Ʞ능을 가집니닀: + + +![샌드박슀 ì ‘ê·Œ 방식 비교](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/smolagents/sandboxed_execution.png) + +1. **개별 윔드 슀니펫을 샌드박슀에서 싀행**: 읎 ì ‘ê·Œ 방식(닀읎얎귞랚 왌쪜)은 에읎전튞가 생성한 파읎썬 윔드 슀니펫만 샌드박슀에서 싀행하고 나뚞지 에읎전튞 시슀템은 로컬 환겜에 유지합니닀. `executor_type="e2b"`, `executor_type="modal"` 또는 +`executor_type="docker"`륌 사용하여 섀정하Ʞ가 더 간닚하지만, 닀쀑 에읎전튞륌 지원하지 않윌며 여전히 환겜곌 샌드박슀 간에 상태 데읎터륌 전달핎알 합니닀. + +2. **전첎 에읎전튞 시슀템을 샌드박슀에서 싀행**: 읎 ì ‘ê·Œ 방식(닀읎얎귞랚 였륞쪜)은 에읎전튞, 몚덞, 도구륌 포핚한 전첎 에읎전튞 시슀템을 샌드박슀 환겜 낎에서 싀행합니닀. 읎는 더 나은 격늬륌 제공하지만 더 많은 수동 섀정읎 필요하며, 믌감한 자격 슝명(API í‚€ 등)을 샌드박슀 환겜윌로 전달핎알 할 수 있습니닀. + +읎 가읎드에서는 에읎전튞 애플늬쌀읎션을 위핎 두 가지 유형의 샌드박슀 ì ‘ê·Œ 방식을 섀정하고 사용하는 방법을 섀명합니닀. + +### E2B 섀정[[e2b-setup]] + +#### 섀치[[installation]] + +1. [e2b.dev](https://e2b.dev)에서 E2B 계정을 생성합니닀. +2. 필요한 팚킀지륌 섀치합니닀: +```bash +pip install 'smolagents[e2b]' +``` + +#### E2B에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-e2b:-quick-start]] + +E2B 샌드박슀륌 사용하는 ê°„ë‹ší•œ 방법을 제공합니닀. 닀음곌 같읎 에읎전튞 쎈Ʞ화에 `executor_type="e2b"`륌 추가하Ʞ만 하멎 됩니닀: + +```py +from smolagents import InferenceClientModel, CodeAgent + +with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="e2b") as agent: + agent.run("100번짞 플볎나치 수륌 알렀쀄 수 있나요?") +``` + +> [!TIP] +> 에읎전튞륌 컚텍슀튞 ꎀ늬자(`with` 묞)로 사용하멎 에읎전튞가 작업을 완료한 직후 E2B 샌드박슀가 정늬되도록 볎장합니닀. +> 또는 에읎전튞의 `cleanup()` 메서드륌 수동윌로 혞출할 수도 있습니닀. + +읎 솔룚션은 각 `agent.run()` 시작 시 에읎전튞 상태륌 서버로 볎냅니닀. +귞런 닀음 로컬 환겜에서 몚덞읎 혞출되지만, 생성된 윔드는 싀행을 위핎 샌드박슀로 전송되고 출력만 반환됩니닀. + +읎는 아래 귞늌에 섀명되얎 있습니닀. + +

+ sandboxed code execution +

+ +하지만 [ꎀ늬형 에읎전튞](../examples/multiagents)에 대한 몚든 혞출은 몚덞 혞출을 필요로 하는데, 비밀 정볎륌 원격 샌드박슀로 전송하지 ì•Šêž° 때묞에 몚덞 혞출에 자격 슝명읎 부족하게 됩니닀. +따띌서 읎 솔룚션은 더 복잡한 닀쀑 에읎전튞 섀정에서는 (아직) 작동하지 않습니닀. + +#### E2B에서 에읎전튞 싀행하Ʞ: 닀쀑 에읎전튞[[running-your-agent-in-e2b:-multi-agents]] + +E2B 샌드박슀에서 닀쀑 에읎전튞륌 사용하렀멎 E2B 낎에서 에읎전튞륌 완전히 싀행핎알 합니닀. + +방법은 닀음곌 같습니닀: + +```python +from e2b_code_interpreter import Sandbox +import os + +# 샌드박슀 생성 +sandbox = Sandbox() + +# 필요한 팚킀지 섀치 +sandbox.commands.run("pip install smolagents") + +def run_code_raise_errors(sandbox, code: str, verbose: bool = False) -> str: + execution = sandbox.run_code( + code, + envs={'HF_TOKEN': os.getenv('HF_TOKEN')} + ) + if execution.error: + execution_logs = "\n".join([str(log) for log in execution.logs.stdout]) + logs = execution_logs + logs += execution.error.traceback + raise ValueError(logs) + return "\n".join([str(log) for log in execution.logs.stdout]) + +# 에읎전튞 애플늬쌀읎션 정의 +agent_code = """ +import os +from smolagents import CodeAgent, InferenceClientModel + +# 에읎전튞 쎈Ʞ화 +agent = CodeAgent( + model=InferenceClientModel(token=os.getenv("HF_TOKEN"), provider="together"), + tools=[], + name="coder_agent", + description="읎 에읎전튞는 윔드륌 사용하여 얎렀욎 알고늬슘 묞제륌 처늬합니닀." +) + +manager_agent = CodeAgent( + model=InferenceClientModel(token=os.getenv("HF_TOKEN"), provider="together"), + tools=[], + managed_agents=[agent], +) + +# 에읎전튞 싀행 +response = manager_agent.run("20번짞 플볎나치 수는 묎엇읞가요?") +print(response) +""" + +# 샌드박슀에서 에읎전튞 윔드 싀행 +execution_logs = run_code_raise_errors(sandbox, agent_code) +print(execution_logs) +``` + +### Modal 섀정[[modal-setup]] + +#### 섀치[[installation]] + +1. [modal.com](https://modal.com/signup)에서 Modal 계정을 생성합니닀. +2. 필요한 팚킀지륌 섀치합니닀: +```bash +pip install 'smolagents[modal]' +``` + +#### Modal에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-modal:-quick-start]] + +Modal 샌드박슀륌 사용하는 ê°„ë‹ší•œ 방법을 제공합니닀. 닀음곌 같읎 에읎전튞 쎈Ʞ화에 `executor_type="modal"`을 추가하Ʞ만 하멎 됩니닀: + +```py +from smolagents import InferenceClientModel, CodeAgent + +with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="modal") as agent: + agent.run("42번짞 플볎나치 수는 묎엇읞가요?") +``` + +> [!TIP] +> 에읎전튞륌 컚텍슀튞 ꎀ늬자(`with` 묞)로 사용하멎 에읎전튞가 작업을 완료한 직후 Modal 샌드박슀가 정늬되도록 볎장합니닀. +> 또는 에읎전튞의 `cleanup()` 메서드륌 수동윌로 혞출할 수도 있습니닀. + +`InferenceClientModel`에서 생성된 에읎전튞 상태와 윔드는 Modal 샌드박슀로 전송되얎 안전하게 윔드륌 싀행할 수 있습니닀. + +### Docker 섀정[[docker-setup]] + +#### 섀치[[installation]] + +1. [시슀템에 Docker 섀치하Ʞ](https://docs.docker.com/get-started/get-docker/) +2. 필요한 팚킀지륌 섀치합니닀: +```bash +pip install 'smolagents[docker]' +``` + +#### Docker에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-docker:-quick-start]] + +위의 E2B 샌드박슀와 유사하게, Docker륌 빠륎게 시작하렀멎 에읎전튞 쎈Ʞ화에 `executor_type="docker"`륌 추가하Ʞ만 하멎 됩니닀: + +```py +from smolagents import InferenceClientModel, CodeAgent + +with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="docker") as agent: + agent.run("100번짞 플볎나치 수륌 알렀쀄 수 있나요?") +``` + +> [!TIP] +> 에읎전튞륌 컚텍슀튞 ꎀ늬자(`with` 묞)로 사용하멎 에읎전튞가 작업을 완료한 직후 Docker 컚테읎너가 정늬되도록 볎장합니닀. +> 또는 에읎전튞의 `cleanup()` 메서드륌 수동윌로 혞출할 수도 있습니닀. + +#### 고꞉ Docker 사용법[[advanced-docker-usage]] + +Docker에서 닀쀑 에읎전튞 시슀템을 싀행하렀멎 샌드박슀에 사용자 정의 읞터프늬터륌 섀정핎알 합니닀. + +Dockerfile을 섀정하는 방법은 닀음곌 같습니닀: + +```dockerfile +FROM python:3.10-bullseye + +# 빌드 의졎성 섀치 +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + build-essential \ + python3-dev && \ + pip install --no-cache-dir --upgrade pip && \ + pip install --no-cache-dir smolagents && \ + apt-get clean && \ + rm -rf /var/lib/apt/lists/* + +# 작업 디렉토늬 섀정 +WORKDIR /app + +# 제한된 권한윌로 싀행 +USER nobody + +# Ʞ볞 명령얎 +CMD ["python", "-c", "print('Container ready')"] +``` + +윔드륌 싀행할 샌드박슀 ꎀ늬자륌 생성합니닀: + +```python +import docker +import os +from typing import Optional + +class DockerSandbox: + def __init__(self): + self.client = docker.from_env() + self.container = None + + def create_container(self): + try: + image, build_logs = self.client.images.build( + path=".", + tag="agent-sandbox", + rm=True, + forcerm=True, + buildargs={}, + # decode=True + ) + except docker.errors.BuildError as e: + print("Build error logs:") + for log in e.build_log: + if 'stream' in log: + print(log['stream'].strip()) + raise + + # 볎안 제앜 조걎곌 적절한 로깅윌로 컚테읎너 생성 + self.container = self.client.containers.run( + "agent-sandbox", + command="tail -f /dev/null", # 컚테읎너륌 계속 싀행 상태로 유지 + detach=True, + tty=True, + mem_limit="512m", + cpu_quota=50000, + pids_limit=100, + security_opt=["no-new-privileges"], + cap_drop=["ALL"], + environment={ + "HF_TOKEN": os.getenv("HF_TOKEN") + }, + ) + + def run_code(self, code: str) -> Optional[str]: + if not self.container: + self.create_container() + + # 컚테읎너에서 윔드 싀행 + exec_result = self.container.exec_run( + cmd=["python", "-c", code], + user="nobody" + ) + + # 몚든 출력 수집 + return exec_result.output.decode() if exec_result.output else None + + + def cleanup(self): + if self.container: + try: + self.container.stop() + except docker.errors.NotFound: + # 컚테읎너가 읎믞 제거됚, 예상된 동작 + pass + except Exception as e: + print(f"Error during cleanup: {e}") + finally: + self.container = None # ì°žì¡° 제거 + +# 사용 예시: +sandbox = DockerSandbox() + +try: + # 에읎전튞 윔드 정의 + agent_code = """ +import os +from smolagents import CodeAgent, InferenceClientModel + +# 에읎전튞 쎈Ʞ화 +agent = CodeAgent( + model=InferenceClientModel(token=os.getenv("HF_TOKEN"), provider="together"), + tools=[] +) + +# 에읎전튞 싀행 +response = agent.run("20번짞 플볎나치 수는 묎엇읞가요?") +print(response) +""" + + # 샌드박슀에서 윔드 싀행 + output = sandbox.run_code(agent_code) + print(output) + +finally: + sandbox.cleanup() +``` + +### WebAssembly 섀정[[webassembly-setup]] + +WebAssembly(Wasm)는 윔드륌 안전한 샌드박슀 환겜에서 싀행할 수 있게 핎죌는 바읎너늬 명령얎 형식입니닀. +빠륎고 횚윚적읎며 안전하게 섀계되얎 잠재적윌로 신뢰할 수 없는 윔드륌 싀행하는 데 탁월한 선택입니닀. + +`WasmExecutor`는 [Pyodide](https://pyodide.org/)와 [Deno](https://docs.deno.com/)륌 사용합니닀. + +#### 섀치[[installation]] + +1. [시슀템에 Deno 섀치하Ʞ](https://docs.deno.com/runtime/getting_started/installation/) + +#### WebAssembly에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-webassembly:-quick-start]] + +닀음곌 같읎 에읎전튞 쎈Ʞ화에 `executor_type="wasm"`을 전달하Ʞ만 하멎 됩니닀: +```py +from smolagents import InferenceClientModel, CodeAgent + +agent = CodeAgent(model=InferenceClientModel(), tools=[], executor_type="wasm") + +agent.run("100번짞 플볎나치 수륌 알렀쀄 수 있나요?") +``` + +### 샌드박슀 몚범 사례[[best-practices-for-sandboxes]] + +읎러한 핵심 사례는 E2B와 Docker 샌드박슀 몚두에 적용됩니닀: + +- 늬소슀 ꎀ늬 + - 메몚늬 및 CPU 제한 섀정 + - 싀행 시간 쎈곌 구현 + - 늬소슀 사용량 몚니터링 +- 볎안 + - 최소한의 권한윌로 싀행 + - 불필요한 넀튞워크 ì ‘ê·Œ 비활성화 + - 비밀 정볎에 환겜 변수 사용 +- 환겜 + - 의졎성을 최소한윌로 유지 + - 고정된 팚킀지 버전 사용 + - Ʞ볞 읎믞지륌 사용하는 겜우 정Ʞ적윌로 업데읎튞 + +- 정늬 + - 특히 Docker 컚테읎너의 겜우, 늬소슀륌 잡아뚹는 대롱거늬는(dangling) 컚테읎너가 생Ʞ지 않도록 항상 적절한 늬소슀 정늬륌 볎장핎알 합니닀. + +✹ 읎러한 몚범 사례륌 따륎고 적절한 정늬 절찚륌 구현핚윌로썚, 에읎전튞가 샌드박슀 환겜에서 안전하고 횚윚적윌로 싀행되도록 볎장할 수 있습니닀. + +## 볎안 ì ‘ê·Œ 방식 비교[[comparing-security-approaches]] + +앞서 닀읎얎귞랚에서 섀명했듯읎, 두 샌드박싱 ì ‘ê·Œ 방식은 서로 닀륞 볎안적 의믞륌 가집니닀: + +### ì ‘ê·Œ 방식 1: 윔드 슀니펫만 샌드박슀에서 싀행[[approach-1:-running-just-the-code-snippets-in-a-sandbox]] +- **장점**: + - ê°„ë‹ší•œ 파띌믞터(`executor_type="e2b"` 또는 `executor_type="docker"`)로 섀정하Ʞ 더 쉜습니닀. + - API 킀륌 샌드박슀로 전송할 필요가 없습니닀. + - 로컬 환겜을 더 잘 볎혞합니닀. +- **닚점**: + - 닀쀑 에읎전튞(ꎀ늬형 에읎전튞)륌 지원하지 않습니닀. + - 여전히 환겜곌 샌드박슀 간에 상태륌 전송핎알 합니닀. + - 특정 윔드 싀행에 제한됩니닀. + +### ì ‘ê·Œ 방식 2: 전첎 에읎전튞 시슀템을 샌드박슀에서 싀행[[approach-2:-running-the-entire-agentic-system-in-a-sandbox]] +- **장점**: + - 닀쀑 에읎전튞륌 지원합니닀. + - 전첎 에읎전튞 시슀템을 완벜하게 격늬합니닀. + - 복잡한 에읎전튞 아킀텍처에 더 유연합니닀. +- **닚점**: + - 더 많은 수동 섀정읎 필요합니닀. + - 믌감한 API 킀륌 샌드박슀로 전송핎알 할 수 있습니닀. + - 더 복잡한 작업윌로 읞핎 잠재적윌로 더 높은 지연 시간읎 발생할 수 있습니닀. + +볎안 요구 사항곌 애플늬쌀읎션의 요구 사항 사읎에서 가장 균형읎 잘 맞는 ì ‘ê·Œ 방식을 선택하섞요. 더 ê°„ë‹ší•œ 에읎전튞 아킀텍처륌 가진 대부분의 애플늬쌀읎션의 겜우, ì ‘ê·Œ 방식 1읎 볎안곌 사용 펞의성 사읎의 좋은 균형을 제공합니닀. 완전한 격늬가 필요한 더 복잡한 닀쀑 에읎전튞 시슀템의 겜우, 섀정읎 더 복잡하지만 ì ‘ê·Œ 방식 2가 더 나은 볎안을 볎장합니닀. \ No newline at end of file From 7fad286a5853a1fe68bc417977c9efd0207d4be6 Mon Sep 17 00:00:00 2001 From: Kim Juwon <81630351+Kim-Ju-won@users.noreply.github.com> Date: Tue, 14 Oct 2025 19:20:55 +0900 Subject: [PATCH 3/3] fix: manual edits --- .../ko/tutorials/secure_code_execution.md | 96 +++++++++---------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/docs/source/ko/tutorials/secure_code_execution.md b/docs/source/ko/tutorials/secure_code_execution.md index 531102e40..5bd07c948 100644 --- a/docs/source/ko/tutorials/secure_code_execution.md +++ b/docs/source/ko/tutorials/secure_code_execution.md @@ -3,44 +3,44 @@ [[open-in-colab]] > [!TIP] -> 에읎전튞 빌드에 익숙하지 않윌시닀멎, 뚌저 [에읎전튞 소개](../conceptual_guides/intro_agents)와 [smolagents 가읎드 투얎](../guided_tour)륌 읜얎볎섞요. +> 에읎전튞 빌드에 익숙하지 않윌시닀멎, 뚌저 [에읎전튞 소개](../conceptual_guides/intro_agents)와 [smolagents 가읎드 투얎](../guided_tour)륌 읜얎볎시Ʞ 바랍니닀. ### 윔드 에읎전튞[[code-agents]] -[여러](https://huggingface.co/papers/2402.01030) [연구](https://huggingface.co/papers/2411.01747) [녌묞](https://huggingface.co/papers/2401.00812)에 따륎멎, LLM읎 자신의 행동(도구 혞출)을 윔드로 작성하게 하는 것읎 현재의 표쀀 도구 혞출 형식볎닀 훚씬 더 횚곌적읎띌고 합니닀. 현재 업계 표쀀은 "도구 읎늄곌 사용할 읞수륌 JSON윌로 작성하는" 방식의 닀양한 변형입니닀. +[여러](https://huggingface.co/papers/2402.01030) [연구](https://huggingface.co/papers/2411.01747) [녌묞](https://huggingface.co/papers/2401.00812)에 따륎멎, LLM읎 자신의 행동(도구 혞출)을 윔드로 작성하게 하는 것읎 현재의 표쀀 도구 혞출 형식볎닀 훚씬 더 횚곌적읎띌고 합니닀. 현재 업계 표쀀은 ‘도구 읎늄곌 사용할 읞수륌 JSON 형태로 Ʞ술하는’ 닀양한 변형 방식을 따륎고 있습니닀. -왜 윔드가 더 나을까요? 우늬는 컎퓚터가 수행하는 작업을 잘 표현하Ʞ 위핎 특별히 윔드 얞얎륌 만듀었Ʞ 때묞입니닀. 만앜 JSON 슀니펫읎 더 나은 방법읎었닀멎, 읎 팚킀지는 JSON 슀니펫윌로 작성되었을 것읎고 악마는 우늬륌 비웃었을 것입니닀. +왜 윔드가 더 나을까요? 우늬는 컎퓚터가 수행하는 작업을 잘 표현하Ʞ 위핎 특별히 윔드 얞얎륌 만듀었Ʞ 때묞입니닀. 만앜 JSON 슀니펫읎 더 나은 방법읎었닀멎, 읎 팚킀지는 JSON윌로 작성됐을 것읎고, 아마 악마가 우늬륌 비웃었을 겁니닀. -윔드는 컎퓚터에서의 작업을 표현하는 더 나은 방법음 뿐입니닀. 닀음곌 같은 장점읎 있습니닀: -- **구성 가능성(Composability):** 파읎썬 핚수륌 정의하는 것처럌 JSON 작업을 쀑첩하거나 나쀑에 재사용할 JSON 작업 섞튞륌 정의할 수 있을까요? -- **객첎 ꎀ늬(Object management):** `generate_image`와 같은 작업의 출력을 JSON에 얎떻게 저장할 수 있을까요? -- **음반성(Generality):** 윔드는 컎퓚터가 할 수 있는 몚든 것을 간닚하게 표현하도록 만듀얎졌습니닀. -- **LLM 학습 윔퍌슀에서의 표현:** LLM 학습 윔퍌슀에 읎믞 수많은 양질의 작업읎 포핚되얎 있닀는 하늘의 축복을 활용하지 않을 읎유가 있을까요? +윔드는 컎퓚터에서의 작업을 표현하는 더 나은 방법음 뿐입니닀. 닀음곌 같은 장점읎 있습니닀. +- **구성 가능성:** 파읎썬 핚수륌 정의하는 것처럌 JSON 작업을 쀑첩하거나 나쀑에 재사용할 JSON 작업 섞튞륌 정의할 수 있을까요? +- **객첎 ꎀ늬:** `generate_image`와 같은 작업의 출력을 JSON에 얎떻게 저장할 수 있을까요? +- **음반성:** 윔드는 컎퓚터가 할 수 있는 몚든 것을 간닚하게 표현하도록 만듀얎졌습니닀. +- **LLM 훈령 윔퍌슀에서의 표현:** LLM 훈령 윔퍌슀에 읎믞 수많은 양질의 작업읎 포핚되얎 있닀는 하늘의 축복을 활용하지 않을 읎유가 있을까요? 읎는 [Executable Code Actions Elicit Better LLM Agents](https://huggingface.co/papers/2402.01030)에서 가젞옚 아래 귞늌에 잘 나타나 있습니닀. -읎것읎 우늬가 윔드 에읎전튞, 읎 겜우 파읎썬 에읎전튞륌 제안하는 데 쀑점을 두는 읎유읎며, 읎는 안전한 파읎썬 읞터프늬터륌 구축하는 데 더 많은 녞력을 Ʞ욞여알 핚을 의믞했습니닀. +읎것읎 우늬가 윔드 에읎전튞(읎 겜우에는 파읎썬 에읎전튞)륌 제안하는 데 쀑점을 두는 읎유입니닀. 읎는 곧 안전한 파읎썬 읞터프늬터륌 구축하Ʞ 위핎 더 많은 녞력읎 필요핚을 의믞했습니닀. -### 로컬 윔드 싀행??[[local-code-execution??]] +### 로컬 윔드 싀행??[[local-code-execution]] Ʞ볞적윌로 `CodeAgent`는 LLM읎 생성한 윔드륌 사용자의 환겜에서 싀행합니닀. -읎는 볞질적윌로 위험하며, LLM읎 생성한 윔드는 사용자 환겜에 핎로욞 수 있습니닀. +읎는 볞질적윌로 위험하며, LLM읎 생성한 윔드는 사용자의 환겜을 손상시킬 수 있습니닀. -악성 윔드 싀행은 여러 가지 방식윌로 발생할 수 있습니닀: -- **닚순 LLM 였류:** LLM은 아직 완벜하지 않윌며, 도움읎 되렀고 하닀가 의도치 않게 핎로욎 명령얎륌 생성할 수 있습니닀. 읎 위험은 낮지만, LLM읎 잠재적윌로 위험한 윔드륌 싀행하렀고 시도한 사례가 ꎀ찰되었습니닀. +악성 윔드 싀행은 여러 가지 방식윌로 발생할 수 있습니닀. +- **닚순 LLM 였류:** LLM은 아직 완벜하지 않윌며 도움을 죌렀는 곌정에서 의도치 않게 핎로욎 명령얎륌 생성할 수 있습니닀. 읎러한 위험은 낮지만 LLM읎 잠재적윌로 위험한 윔드륌 싀행하렀 시도한 사례가 싀제로 ꎀ찰된 바 있습니닀. - **공꞉망 공격:** 신뢰할 수 없거나 손상된 LLM을 싀행하멎 시슀템읎 유핎한 윔드 생성에 녞출될 수 있습니닀. 안전한 추론 읞프띌에서 잘 알렀진 몚덞을 사용할 때 읎 위험은 맀우 낮지만, 읎론적읞 가능성은 ë‚šì•„ 있습니닀. -- **프롬프튞 읞젝션:** 웹을 탐색하는 에읎전튞가 유핎한 지칚읎 포핚된 악성 웹사읎튞에 도달하여 에읎전튞의 메몚늬에 공격을 죌입할 수 있습니닀. +- **프롬프튞 읞젝션:** 웹을 탐색하는 에읎전튞가 유핎한 지칚읎 포핚된 악성 웹사읎튞에 도달핎 에읎전튞의 메몚늬에 공격을 죌입할 수 있습니닀. - **공개적윌로 ì ‘ê·Œ 가능한 에읎전튞 악용:** 대쀑에게 녞출된 에읎전튞는 악의적읞 행위자에 의핎 악용되얎 유핎한 윔드륌 싀행할 수 있습니닀. 공격자는 에읎전튞의 싀행 능력을 악용하Ʞ 위핎 적대적읞 입력을 만듀얎 의도하지 않은 결곌륌 쎈래할 수 있습니닀. -악성 윔드가 우발적읎든 의도적읎든 싀행되멎 파음 시슀템을 손상시킀고, 로컬 또는 큎띌우드 êž°ë°˜ 늬소슀륌 악용하며, API 서비슀륌 낚용하고, 심지얎 넀튞워크 볎안을 위협할 수 있습니닀. +악성 윔드가 우발적읎든 의도적읎든 싀행되멎 파음 시슀템읎 손상되고, 로컬 또는 큎띌우드 늬소슀가 악용되며, API 서비슀가 낚용되고, 심지얎 넀튞워크 볎안까지 위협받을 수 있습니닀. -[에읎전시 슀펙튞럌](../conceptual_guides/intro_agents)에서 윔드 에읎전튞는 닀륞 덜 에읎전튞적읞 섀정볎닀 시슀템에서 LLM에 훚씬 더 높은 에읎전시륌 부여한닀고 죌장할 수 있습니닀. 읎는 더 높은 위험을 수반합니닀. +[에읎전시 슀펙튞럌](../conceptual_guides/intro_agents)에서 윔드 에읎전튞는 닀륞 덜 에읎전튞적읞 섀정에 비핎 시슀템 낎에서 LLM에게 훚씬 더 높은 수쀀의 에읎전시륌 부여한닀고 할 수 있습니닀. 읎는 곧 더 높은 수쀀의 위험을 수반합니닀. -따띌서 볎안에 맀우 유의핎알 합니닀. +따띌서 볎안에 각별한 죌의가 필요합니닀. -안전성을 향상시킀Ʞ 위핎, 더 높은 섀정 비용윌로 더 높은 수쀀의 볎안을 제공하는 닀양한 조치륌 제안합니닀. +더 강력한 볎안을 위핎, 섀정 비용은 닀소 높지만 볎닀 높은 수쀀의 볎혞륌 제공하는 닀양한 조치륌 제안합니닀. ì–Žë–€ 핎결책도 100% 안전하지 않닀는 점을 명심하시Ʞ 바랍니닀. @@ -48,17 +48,17 @@ ### 로컬 파읎썬 싀행Ʞ[[our-local-python-executor]] -첫 번짞 볎안 계잵을 추가하Ʞ 위핎, `smolagents`에서의 윔드 싀행은 음반 파읎썬 읞터프늬터에 의핎 수행되지 않습니닀. +첫 번짞 볎안 계잵을 추가하Ʞ 위핎, 음반 파읎썬 읞터프늬터에서 `smolagents`의 윔드 싀행가 싀행되지 않습니닀. 우늬는 더 안전한 `LocalPythonExecutor`륌 처음부터 닀시 구축했습니닀. -정확히 말하멎, 읎 읞터프늬터는 윔드에서 추상 구묞 튞늬(AST)륌 로드하고 읎륌 연산 닚위로 싀행하며, 항상 특정 규칙을 따륎도록 합니닀: +정확히 말하멎, 읎 읞터프늬터는 윔드에서 추상 구묞 튞늬(AST)륌 가젞와서 읎륌 연산 닚위로 싀행하며 항상 특정 규칙을 따륎도록 합니닀 - Ʞ볞적윌로, 사용자가 승읞 목록에 명시적윌로 추가하지 않는 한 import는 허용되지 않습니닀. - 또한, 하위 몚듈에 대한 접귌은 Ʞ볞적윌로 비활성화되얎 있윌며, 각 하위 몚듈도 import 목록에서 명시적윌로 승읞되얎알 합니닀. 또는 예륌 듀얎 `numpy.*`륌 전달하여 `numpy`와 `numpy.random` 또는 `numpy.a.b`와 같은 몚든 하위 팚킀지륌 허용할 수 있습니닀. - `random`곌 같읎 겉볎Ʞ에 묎핎핎 볎읎는 음부 팚킀지도 `random._os`에서처럌 잠재적윌로 유핎한 하위 몚듈에 대한 접귌을 허용할 수 있닀는 점에 유의하섞요. - 처늬되는 Ʞ볞 연산의 쎝 횟수는 묎한 룚프와 늬소슀 팜찜을 방지하Ʞ 위핎 제한됩니닀. - 사용자 정의 읞터프늬터에 명시적윌로 정의되지 않은 몚든 연산은 였류륌 발생시킵니닀. -닀음곌 같읎 읎러한 안전장치륌 시험핎 볌 수 있습니닀: +닀음곌 같읎 읎러한 안전장치륌 시험핎 볌 수 있습니닀. ```py from smolagents.local_python_executor import LocalPythonExecutor @@ -66,7 +66,7 @@ from smolagents.local_python_executor import LocalPythonExecutor # 사용자 정의 싀행Ʞ 섀정, "numpy" 팚킀지 승읞 custom_executor = LocalPythonExecutor(["numpy"]) -# 였류륌 예쁘게 출력하Ʞ 위한 유틞늬티 +# 였류 메시지륌 가독성읎 좋게 출력하는 유틞늬티 def run_capture_exception(command: str): try: custom_executor(harmful_command) @@ -98,17 +98,17 @@ run_capture_exception(harmful_command) # >>> ERROR: Code execution failed at line 'while True: pass' due to: InterpreterError: Maximum number of 1000000 iterations in While loop exceeded ``` -읎러한 안전장치 덕분에 저희 읞터프늬터는 더 안전합니닀. -우늬는 닀양한 사용 사례에서 읎륌 사용했윌며, 환겜에 ì–Žë– í•œ 손상도 ꎀ찰되지 않았습니닀. +읎러한 안전장치 덕분에 읞터프늬터는 더 안전하게 싀행할 수 있습니닀. +닀양한 사용 사례에서 읞터프늬터륌 사용했지만 사용자 환겜에 ì–Žë– í•œ 손상도 ꎀ찰되지 않았습니닀. > [!WARNING] -> ì–Žë–€ 로컬 파읎썬 샌드박슀도 완전히 안전할 수는 없닀는 점을 읎핎하는 것읎 쀑요합니닀. 저희 읞터프늬터가 표쀀 파읎썬 읞터프늬터에 비핎 상당한 안전성 향상을 제공하지만, 의지가 확고한 공격자나 믞섞 조정된 악성 LLM읎 췚앜점을 ì°Ÿì•„ë‚Žì–Ž 사용자 환겜에 핎륌 끌칠 가능성은 여전히 졎재합니닀. +> 로컬 파읎썬 샌드박슀 환겜은 볞질적윌로 완전한 안전성을 볎장할 수 없닀는 점을 읞식하는 것읎 쀑요합니닀. 저희 읞터프늬터는 표쀀 파읎썬 읞터프늬터볎닀 안전성읎 크게 향상되었지만, 의지가 확고한 공격자나 악의적윌로 믞섞 조정된 LLM읎 췚앜점을 ì°Ÿì•„ 사용자 환겜에 플핎륌 쀄 가능성은 여전히 졎재합니닀. > > 예륌 듀얎, `Pillow`와 같은 팚킀지가 읎믞지륌 처늬하도록 허용한 겜우, LLM은 하드 드띌읎람륌 가득 채욞 수천 개의 대용량 읎믞지 파음을 생성하는 윔드륌 만듀 수 있습니닀. 닀륞 고꞉ 탈출 Ʞ술은 승읞된 팚킀지의 더 깊은 췚앜점을 악용할 수 있습니닀. > -> LLM읎 생성한 윔드륌 로컬 환겜에서 싀행하는 것은 항상 낎재된 위험을 수반합니닀. 진정윌로 강력한 볎안 격늬륌 통핎 LLM 생성 윔드륌 싀행하는 유음한 방법은 아래에 자섞히 섀명된 E2B나 Docker와 같은 원격 싀행 옵션을 사용하는 것입니닀. +> LLM읎 생성한 윔드륌 로컬 환겜에서 싀행하는 것은 항상 위험을 낎포합니닀. 진정윌로 강력한 볎안 격늬륌 통핎 LLM 생성 윔드륌 싀행하는 유음한 방법은 아래에 자섞히 섀명된 E2B나 Docker와 같은 원격 싀행 옵션을 사용하는 것입니닀. -신뢰할 수 있는 추론 제공업첎의 잘 알렀진 LLM을 사용할 때 악의적읞 공격의 위험은 낮지만, 0은 아닙니닀. +신뢰할 수 있는 추론 제공업첎의 잘 알렀진 LLM을 사용할 때 악의적읞 공격의 위험은 낮지만 0은 아닙니닀. 볎안 수쀀읎 높은 애플늬쌀읎션읎나 신뢰도가 낮은 몚덞을 사용하는 겜우, 원격 싀행 샌드박슀 사용을 고렀핎알 합니닀. ## 안전한 윔드 싀행을 위한 샌드박슀 ì ‘ê·Œ 방식[[sandbox-approaches-for-secure-code-execution]] @@ -135,7 +135,7 @@ run_capture_exception(harmful_command) pip install 'smolagents[e2b]' ``` -#### E2B에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-e2b:-quick-start]] +#### E2B에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-e2b-quick-start]] E2B 샌드박슀륌 사용하는 ê°„ë‹ší•œ 방법을 제공합니닀. 닀음곌 같읎 에읎전튞 쎈Ʞ화에 `executor_type="e2b"`륌 추가하Ʞ만 하멎 됩니닀: @@ -147,8 +147,8 @@ with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="e2b") as a ``` > [!TIP] -> 에읎전튞륌 컚텍슀튞 ꎀ늬자(`with` 묞)로 사용하멎 에읎전튞가 작업을 완료한 직후 E2B 샌드박슀가 정늬되도록 볎장합니닀. -> 또는 에읎전튞의 `cleanup()` 메서드륌 수동윌로 혞출할 수도 있습니닀. +> 에읎전튞륌 컚텍슀튞 ꎀ늬자(`with` 묞)로 사용하멎 에읎전튞가 작업을 완료한 직후 E2B 샌드박슀가 자원 í•Žì œ 및 정늬가 자동윌로 수행되도록 볎장합니닀. +> 또는 에읎전튞의 `cleanup()` 메소드륌 수동윌로 혞출할 수도 있습니닀. 읎 솔룚션은 각 `agent.run()` 시작 시 에읎전튞 상태륌 서버로 볎냅니닀. 귞런 닀음 로컬 환겜에서 몚덞읎 혞출되지만, 생성된 윔드는 싀행을 위핎 샌드박슀로 전송되고 출력만 반환됩니닀. @@ -160,13 +160,13 @@ with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="e2b") as a

하지만 [ꎀ늬형 에읎전튞](../examples/multiagents)에 대한 몚든 혞출은 몚덞 혞출을 필요로 하는데, 비밀 정볎륌 원격 샌드박슀로 전송하지 ì•Šêž° 때묞에 몚덞 혞출에 자격 슝명읎 부족하게 됩니닀. -따띌서 읎 솔룚션은 더 복잡한 닀쀑 에읎전튞 섀정에서는 (아직) 작동하지 않습니닀. +따띌서 읎 솔룚션은 더 복잡한 닀쀑 에읎전튞 섀정에서는 아직 작동하지 않습니닀. -#### E2B에서 에읎전튞 싀행하Ʞ: 닀쀑 에읎전튞[[running-your-agent-in-e2b:-multi-agents]] +#### E2B에서 에읎전튞 싀행하Ʞ: 닀쀑 에읎전튞[[running-your-agent-in-e2b-multi-agents]] E2B 샌드박슀에서 닀쀑 에읎전튞륌 사용하렀멎 E2B 낎에서 에읎전튞륌 완전히 싀행핎알 합니닀. -방법은 닀음곌 같습니닀: +방법은 닀음곌 같습니닀. ```python from e2b_code_interpreter import Sandbox @@ -229,7 +229,7 @@ print(execution_logs) pip install 'smolagents[modal]' ``` -#### Modal에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-modal:-quick-start]] +#### Modal에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-modal-quick-start]] Modal 샌드박슀륌 사용하는 ê°„ë‹ší•œ 방법을 제공합니닀. 닀음곌 같읎 에읎전튞 쎈Ʞ화에 `executor_type="modal"`을 추가하Ʞ만 하멎 됩니닀: @@ -242,7 +242,7 @@ with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="modal") as > [!TIP] > 에읎전튞륌 컚텍슀튞 ꎀ늬자(`with` 묞)로 사용하멎 에읎전튞가 작업을 완료한 직후 Modal 샌드박슀가 정늬되도록 볎장합니닀. -> 또는 에읎전튞의 `cleanup()` 메서드륌 수동윌로 혞출할 수도 있습니닀. +> 또는 에읎전튞의 `cleanup()` 메소드륌 수동윌로 혞출할 수도 있습니닀. `InferenceClientModel`에서 생성된 에읎전튞 상태와 윔드는 Modal 샌드박슀로 전송되얎 안전하게 윔드륌 싀행할 수 있습니닀. @@ -251,14 +251,14 @@ with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="modal") as #### 섀치[[installation]] 1. [시슀템에 Docker 섀치하Ʞ](https://docs.docker.com/get-started/get-docker/) -2. 필요한 팚킀지륌 섀치합니닀: +2. 필요한 팚킀지륌 섀치합니닀. ```bash pip install 'smolagents[docker]' ``` -#### Docker에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-docker:-quick-start]] +#### Docker에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-docker-quick-start]] -위의 E2B 샌드박슀와 유사하게, Docker륌 빠륎게 시작하렀멎 에읎전튞 쎈Ʞ화에 `executor_type="docker"`륌 추가하Ʞ만 하멎 됩니닀: +위의 E2B 샌드박슀와 유사하게, Docker륌 빠륎게 시작하렀멎 에읎전튞 쎈Ʞ화에 `executor_type="docker"`륌 추가하Ʞ만 하멎 됩니닀. ```py from smolagents import InferenceClientModel, CodeAgent @@ -269,13 +269,13 @@ with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="docker") a > [!TIP] > 에읎전튞륌 컚텍슀튞 ꎀ늬자(`with` 묞)로 사용하멎 에읎전튞가 작업을 완료한 직후 Docker 컚테읎너가 정늬되도록 볎장합니닀. -> 또는 에읎전튞의 `cleanup()` 메서드륌 수동윌로 혞출할 수도 있습니닀. +> 또는 에읎전튞의 `cleanup()` 메소드륌 수동윌로 혞출할 수도 있습니닀. #### 고꞉ Docker 사용법[[advanced-docker-usage]] Docker에서 닀쀑 에읎전튞 시슀템을 싀행하렀멎 샌드박슀에 사용자 정의 읞터프늬터륌 섀정핎알 합니닀. -Dockerfile을 섀정하는 방법은 닀음곌 같습니닀: +Dockerfile을 섀정하는 방법은 닀음곌 같습니닀. ```dockerfile FROM python:3.10-bullseye @@ -290,7 +290,7 @@ RUN apt-get update && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* -# 작업 디렉토늬 섀정 +# 작업 디렉터늬 섀정 WORKDIR /app # 제한된 권한윌로 싀행 @@ -300,7 +300,7 @@ USER nobody CMD ["python", "-c", "print('Container ready')"] ``` -윔드륌 싀행할 샌드박슀 ꎀ늬자륌 생성합니닀: +윔드륌 싀행할 샌드박슀 ꎀ늬자륌 생성합니닀. ```python import docker @@ -410,9 +410,9 @@ WebAssembly(Wasm)는 윔드륌 안전한 샌드박슀 환겜에서 싀행할 수 1. [시슀템에 Deno 섀치하Ʞ](https://docs.deno.com/runtime/getting_started/installation/) -#### WebAssembly에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-webassembly:-quick-start]] +#### WebAssembly에서 에읎전튞 싀행하Ʞ: 빠륞 시작[[running-your-agent-in-webassembly-quick-start]] -닀음곌 같읎 에읎전튞 쎈Ʞ화에 `executor_type="wasm"`을 전달하Ʞ만 하멎 됩니닀: +닀음곌 같읎 에읎전튞 쎈Ʞ화에 `executor_type="wasm"`을 전달하Ʞ만 하멎 됩니닀. ```py from smolagents import InferenceClientModel, CodeAgent @@ -423,7 +423,7 @@ agent.run("100번짞 플볎나치 수륌 알렀쀄 수 있나요?") ### 샌드박슀 몚범 사례[[best-practices-for-sandboxes]] -읎러한 핵심 사례는 E2B와 Docker 샌드박슀 몚두에 적용됩니닀: +읎러한 핵심 사례는 E2B와 Docker 샌드박슀 몚두에 적용됩니닀. - 늬소슀 ꎀ늬 - 메몚늬 및 CPU 제한 섀정 @@ -445,9 +445,9 @@ agent.run("100번짞 플볎나치 수륌 알렀쀄 수 있나요?") ## 볎안 ì ‘ê·Œ 방식 비교[[comparing-security-approaches]] -앞서 닀읎얎귞랚에서 섀명했듯읎, 두 샌드박싱 ì ‘ê·Œ 방식은 서로 닀륞 볎안적 의믞륌 가집니닀: +앞서 닀읎얎귞랚에서 섀명했듯읎, 두 샌드박싱 ì ‘ê·Œ 방식은 서로 닀륞 볎안적 의믞륌 가집니닀. -### ì ‘ê·Œ 방식 1: 윔드 슀니펫만 샌드박슀에서 싀행[[approach-1:-running-just-the-code-snippets-in-a-sandbox]] +### ì ‘ê·Œ 방식 1: 윔드 슀니펫만 샌드박슀에서 싀행[[approach-1-running-just-the-code-snippets-in-a-sandbox]] - **장점**: - ê°„ë‹ší•œ 파띌믞터(`executor_type="e2b"` 또는 `executor_type="docker"`)로 섀정하Ʞ 더 쉜습니닀. - API 킀륌 샌드박슀로 전송할 필요가 없습니닀. @@ -457,7 +457,7 @@ agent.run("100번짞 플볎나치 수륌 알렀쀄 수 있나요?") - 여전히 환겜곌 샌드박슀 간에 상태륌 전송핎알 합니닀. - 특정 윔드 싀행에 제한됩니닀. -### ì ‘ê·Œ 방식 2: 전첎 에읎전튞 시슀템을 샌드박슀에서 싀행[[approach-2:-running-the-entire-agentic-system-in-a-sandbox]] +### ì ‘ê·Œ 방식 2: 전첎 에읎전튞 시슀템을 샌드박슀에서 싀행[[approach-2-running-the-entire-agentic-system-in-a-sandbox]] - **장점**: - 닀쀑 에읎전튞륌 지원합니닀. - 전첎 에읎전튞 시슀템을 완벜하게 격늬합니닀.