execution-and-safety
Configure smolagents CodeAgent execution safely: local imports, executor_type choices, remote sandboxes, PythonInterpreterTool, and sandbox troubleshooting.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- execution-and-safety
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Configure smolagents CodeAgent execution safely: local imports, executor_type choices, remote sandboxes, PythonInterpreterTool, and sandbox troubleshooting.
- disable-model-invocation
- true
02 资源文件 4
- 参考文档references/executor-reference.md7.3 KB
- 参考文档references/security-workflows.md6.0 KB
- 参考文档references/troubleshooting.md6.5 KB
- 脚本scripts/check_executor_config.py7.4 KB
03 SKILL.md 正文
Execution and Safety
Use this sub-skill when a task involves how CodeAgent executes Python, how to limit or authorize imports, how to choose executor_type, or how to troubleshoot local and remote execution failures.
Route elsewhere when the request is mainly about:
- Model/API/provider configuration: use
model-providers. - CLI flags or web UI behavior: use
cli-and-ui. - Agent control flow, planning, multi-step runs, or managed agents: use
agent-workflows. - Tool schemas,
Toolsubclasses, MCP, or tool serialization: usetools-and-integrations.
Safety-first defaults
Prefer this decision order:
- Use
CodeAgent(..., executor_type="local")only for trusted tasks and low-risk code, becauseLocalPythonExecutoris a restricted AST interpreter but not a complete security sandbox. - Add
additional_authorized_importsnarrowly, one package or submodule at a time; avoid"*"unless the user explicitly accepts local execution risk. - Use
executor_type="docker","e2b","modal", or"blaxel"for untrusted prompts, web-browsing contexts, public-facing agents, or higher-risk code. - Use a context manager or call
agent.cleanup()for remote executors so sandboxes/containers terminate promptly. - Do not pass destructive, credential-printing, filesystem-mutating, or network-scanning snippets as examples.
Quick local configuration
from smolagents import CodeAgent
agent = CodeAgent(
tools=[],
model=model,
executor_type="local",
additional_authorized_imports=["math", "statistics"],
max_print_outputs_length=10_000,
executor_kwargs={"timeout_seconds": 10},
)
Key points:
additional_authorized_importsextends smolagents' built-in safe module list for local code execution.- Submodules are explicit: authorizing
"numpy"allowsimport numpy; use"numpy.random"for that submodule or"numpy.*"for the package tree. LocalPythonExecutorchecks that authorized modules are importable during initialization, except wildcard"*".max_print_outputs_lengthtruncates captured stdout, not the returned Python value.executor_kwargs={"timeout_seconds": N}sets the local execution timeout;Nonedisables it and should be avoided for untrusted code.
For exact constructor behavior, see executor-reference.md. For risk patterns and sandbox selection, see security-workflows.md. For errors, see troubleshooting.md.
Remote executor choices
CodeAgent accepts exactly these executor names:
executor_type |
Best fit | Extra |
|---|---|---|
"local" |
Trusted local workflows, fastest setup | base package |
"docker" |
Self-hosted isolation, local container control | smolagents[docker] |
"e2b" |
Managed cloud sandbox with E2B account/API setup | smolagents[e2b] |
"modal" |
Managed Modal sandbox with Modal account/API setup | smolagents[modal] |
"blaxel" |
Managed Blaxel sandbox, fast hibernating VMs | smolagents[blaxel] |
Remote executor pattern:
from smolagents import CodeAgent
with CodeAgent(
tools=[],
model=model,
executor_type="docker",
additional_authorized_imports=["numpy"],
executor_kwargs={"build_new_image": False},
) as agent:
result = agent.run("Compute a small numeric result without writing files.")
Remote execution details:
additional_authorized_importsbecomes the list of packages installed in the remote environment.- Tool requirements are also installed remotely when tools are sent to the executor.
- Variables are serialized with safe JSON-compatible serialization by default.
allow_pickle=Trueenables pickle fallback for complex objects but can execute arbitrary code during deserialization; use it only in fully trusted environments.- Managed agents are not supported with snippet-level remote execution; run the whole agentic system in a sandbox for multi-agent isolation.
PythonInterpreterTool
Use PythonInterpreterTool when a tool-calling agent needs a calculator-like Python tool rather than CodeAgent code actions:
from smolagents import PythonInterpreterTool
python_tool = PythonInterpreterTool(
authorized_imports=["math"],
timeout_seconds=10,
)
The tool returns a string containing captured stdout and the final output. Its authorized_imports follows the same allow-list idea as LocalPythonExecutor and includes base built-in modules automatically.
Bundled helper
Use the bundled helper for safe local validation before constructing a real agent:
python sub-skills/execution-and-safety/scripts/check_executor_config.py --executor-type local --imports math statistics --tiny-local-check
python sub-skills/execution-and-safety/scripts/check_executor_config.py --executor-type docker --imports numpy --explain-only
The helper performs parser-only checks by default. It never starts Docker, Modal, E2B, or Blaxel, never reads credentials, and never runs network calls. --tiny-local-check executes only a tiny in-process local interpreter smoke test.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).