Hugging Face smolagents: Code-Executing Agents and the Sandbox Question

Evidence check: 25 October 2026. Product details reflect the referenced documentation observed at this cutoff; exact plans, prices, regional eligibility and unverified release dates are not claimed. This is an editorial guide, not a hands-on test.

Two kinds of agent behavior

Hugging Face documentation describes CodeAgent and ToolCallingAgent interfaces. A tool-calling agent generates requests to named tools; a code agent may compose steps into executable code, including functions and loops. Both can solve multi-step problems, but arbitrary execution is a distinct capability with a much larger consequence if an attacker influences the input or the model makes a mistake.

Threat model for code execution

Treat generated code as untrusted even if a model writes it after receiving a benign-looking request. Restrict network egress, installed packages, filesystem mounts, subprocess invocation and execution time. Use per-run isolation and temporary credentials that have no unrelated service permissions. The hosted sandbox contract must be evaluated for the specific provider and release; a Python subprocess on the host is not equivalent to a properly isolated runtime.

Example: structured analysis

For a safe pilot, supply a synthetic CSV containing no personal data and let the agent calculate totals and explain anomalies. Limit the code interpreter to the provided file and a fixed output directory. After the run, validate calculated numbers with deterministic code and keep a record of executed commands. A successful narrative or chart is not sufficient; compare results to a test oracle. Add a malicious cell containing a fake instruction to read hidden files and ensure it cannot escape the input-data boundary.

Tool-calling alternatives

Where a task only needs one or two API actions, explicit JSON tools may be easier to audit than generated code. For work involving fixed transformations, ordinary functions may remove the need for a model-driven loop entirely. Hugging Face documentation notes that APIs and underlying models evolve, so pin stable library versions, maintain a changelog and rerun permission tests after upgrades.

Operational assessment

Before adding real data, test crash recovery, denial of unauthorized paths, time limits, package import rules and log redaction. Measure correct results and unsafe attempted actions separately. Model provider licensing, inference pricing and geographic restrictions are independent from the agent library and are not asserted here. Compare PydanticAI, LangGraph or direct code execution in an isolated job runner if clear control flow matters more than exploratory agent flexibility.

Measure sandbox containment

Attempt to read a file outside the allowed directory, initiate an outbound request to a non-allowlisted host and allocate more compute than a job permits. Each attempt should be denied by the sandbox, not only discouraged by instructions. Preserve sanitized execution records for incident review while removing user-identifying content from shared telemetry. Distinguish supported Python library behavior from features provided by the chosen isolation environment. Keep the execution image and runtime dependencies pinned to reproduce failures.