Smolagents Code Agents
Use code actions when an agent benefits from loops, variables, data transforms, and multi-call tool composition. Treat generated code as untrusted unless it runs in a real sandbox.
Use When
- The user wants a lightweight agent prototype in Python.
- Tool calls need loops, branching, or batching.
- The agent should use Hugging Face Inference Providers, LiteLLM, OpenAI-compatible servers, local
transformers, or Ollama.
- The agent needs MCP tools, Hub tools, or a shared Space.
- You must decide between
CodeAgent and ToolCallingAgent.
Build Pattern
- Choose
CodeAgent when actions need Python control flow; choose ToolCallingAgent for simple structured tool calls.
- Keep tools small, typed, and side-effect explicit.
- Configure the model through environment variables or a provider object, never hard-code secrets.
- Run code execution in Docker, E2B, Modal, Blaxel, or another isolation boundary.
- Allow imports by explicit whitelist only.
- Stream logs and capture intermediate observations for debugging.
- Add a task-level timeout and max-step budget.
Safety Baseline
Never treat LocalPythonExecutor as a security boundary for untrusted code. Use it only for trusted local experiments.
Generate a starter safety scaffold:
python skills/agent-design/smolagents-code-agents/scripts/smolagent_safety_scaffold.py --name research_agent
Review sandboxing-checklist.md before running any agent that executes model-written code.
Quick Selection
| Requirement |
Choose |
| Agent writes Python actions |
CodeAgent |
| Strict JSON-like tool calls |
ToolCallingAgent |
| Untrusted tasks or web data |
Sandboxed executor |
| Local model experiments |
TransformersModel or Ollama-compatible provider |
| Hosted provider flexibility |
InferenceClientModel, LiteLLMModel, or OpenAI-compatible model |
Common Mistakes
| Mistake |
Fix |
| Running untrusted code locally |
Use Docker or managed sandbox |
| Exposing broad filesystem access |
Mount a temporary workspace only |
| Giving tools vague docstrings |
Make inputs, outputs, and side effects explicit |
| Letting agents import anything |
Whitelist imports per task |
| Shipping without trace logs |
Persist steps, code snippets, tool outputs, and final answer |
References
1---2name: smolagents-code-agents3description: Use when building Hugging Face smolagents, code-executing agents, Python-action agents, Hub-shared tools, or lightweight agent prototypes that need sandboxing and provider flexibility.4---56# Smolagents Code Agents78Use code actions when an agent benefits from loops, variables, data transforms, and multi-call tool composition. Treat generated code as untrusted unless it runs in a real sandbox.910## Use When1112- The user wants a lightweight agent prototype in Python.13- Tool calls need loops, branching, or batching.14- The agent should use Hugging Face Inference Providers, LiteLLM, OpenAI-compatible servers, local `transformers`, or Ollama.15- The agent needs MCP tools, Hub tools, or a shared Space.16- You must decide between `CodeAgent` and `ToolCallingAgent`.1718## Build Pattern19201. Choose `CodeAgent` when actions need Python control flow; choose `ToolCallingAgent` for simple structured tool calls.212. Keep tools small, typed, and side-effect explicit.223. Configure the model through environment variables or a provider object, never hard-code secrets.234. Run code execution in Docker, E2B, Modal, Blaxel, or another isolation boundary.245. Allow imports by explicit whitelist only.256. Stream logs and capture intermediate observations for debugging.267. Add a task-level timeout and max-step budget.2728## Safety Baseline2930Never treat `LocalPythonExecutor` as a security boundary for untrusted code. Use it only for trusted local experiments.3132Generate a starter safety scaffold:3334```bash35python skills/agent-design/smolagents-code-agents/scripts/smolagent_safety_scaffold.py --name research_agent36```3738Review [sandboxing-checklist.md](references/sandboxing-checklist.md) before running any agent that executes model-written code.3940## Quick Selection4142| Requirement | Choose |43| --- | --- |44| Agent writes Python actions | `CodeAgent` |45| Strict JSON-like tool calls | `ToolCallingAgent` |46| Untrusted tasks or web data | Sandboxed executor |47| Local model experiments | `TransformersModel` or Ollama-compatible provider |48| Hosted provider flexibility | `InferenceClientModel`, `LiteLLMModel`, or OpenAI-compatible model |4950## Common Mistakes5152| Mistake | Fix |53| --- | --- |54| Running untrusted code locally | Use Docker or managed sandbox |55| Exposing broad filesystem access | Mount a temporary workspace only |56| Giving tools vague docstrings | Make inputs, outputs, and side effects explicit |57| Letting agents import anything | Whitelist imports per task |58| Shipping without trace logs | Persist steps, code snippets, tool outputs, and final answer |5960## References6162- GitHub: huggingface/smolagents - https://github.com/huggingface/smolagents63- Hugging Face docs: smolagents - https://huggingface.co/docs/smolagents/index64- Hugging Face docs: CodeAgent - https://huggingface.co/docs/smolagents/reference/agents65- Hugging Face docs: MCP tools - https://huggingface.co/docs/smolagents/tutorials/mcp
mouadja02