{"id":138,"library":"smolagents","title":"smolagents","description":"Minimalist HuggingFace agent framework where agents write actions as Python code. ~1,000 lines of core logic. Released December 2024. Current version is 1.24.0 (Mar 2026). Releases frequently — weekly cadence. Two agent types: CodeAgent (writes Python code) and ToolCallingAgent (JSON tool calls).","status":"active","version":"1.24.0","language":"python","source_language":"en","source_url":"https://github.com/huggingface/smolagents","tags":["huggingface","agents","llm","codeagent","python","agentic-ai"],"install":[{"cmd":"pip install smolagents","lang":"bash","label":"Python (core)"},{"cmd":"pip install 'smolagents[transformers]'","lang":"bash","label":"Python (local model support)"},{"cmd":"pip install 'smolagents[litellm]'","lang":"bash","label":"Python (LiteLLM 100+ providers)"},{"cmd":"pip install 'smolagents[openai]'","lang":"bash","label":"Python (OpenAI provider)"}],"dependencies":[{"reason":"Required for TransformersModel local inference. Install via smolagents[transformers].","package":"torch","optional":true},{"reason":"Required for LiteLLMModel supporting 100+ providers. Install via smolagents[litellm].","package":"litellm","optional":true},{"reason":"Required for InferenceClientModel. Pinned to <1.0.0 in recent versions due to tokenizer build issues.","package":"huggingface-hub","optional":false}],"imports":[{"note":"HfApiModel was removed and replaced by InferenceClientModel. Causes ImportError on smolagents >= 1.x. All LLM tutorials and docs from early 2025 use the old name.","wrong":"from smolagents import CodeAgent, HfApiModel\nmodel = HfApiModel()","symbol":"CodeAgent","correct":"from smolagents import CodeAgent, InferenceClientModel\n\nmodel = InferenceClientModel()\nagent = CodeAgent(tools=[], model=model)\nagent.run('What is 2+2?')"},{"note":"LiteLLM requires provider-prefixed model IDs. Use 'anthropic/claude-...' not 'claude-...' alone.","wrong":"from smolagents import LiteLLMModel\nmodel = LiteLLMModel(model_id='claude-sonnet-4-5')","symbol":"LiteLLMModel","correct":"from smolagents import LiteLLMModel\nmodel = LiteLLMModel(model_id='anthropic/claude-sonnet-4-5', api_key='...')"},{"note":"Same HfApiModel rename applies here. ToolCallingAgent uses JSON tool calls instead of Python code.","wrong":"from smolagents import ToolCallingAgent, HfApiModel","symbol":"ToolCallingAgent","correct":"from smolagents import ToolCallingAgent, InferenceClientModel\n\nmodel = InferenceClientModel()\nagent = ToolCallingAgent(tools=[], model=model)"}],"quickstart":{"code":"from smolagents import CodeAgent, InferenceClientModel, WebSearchTool\nimport os\n\n# Uses HF_TOKEN env var automatically\nmodel = InferenceClientModel()\nagent = CodeAgent(\n    tools=[WebSearchTool()],\n    model=model\n)\nresult = agent.run('How many seconds would it take a leopard at full speed to cross the Pont des Arts?')\nprint(result)","lang":"python","description":"Minimal CodeAgent with web search using InferenceClientModel 1.24.x."},"warnings":[{"fix":"Replace HfApiModel() with InferenceClientModel(). Same constructor signature.","message":"HfApiModel is removed in smolagents >= 1.0. Use InferenceClientModel instead. Causes ImportError: cannot import name 'HfApiModel'.","severity":"breaking","affected_versions":">= 1.0.0"},{"fix":"from smolagents import WebSearchTool","message":"DuckDuckGoSearchTool renamed to WebSearchTool in recent versions. Import fails on newer installs.","severity":"breaking","affected_versions":">= 1.10.0"},{"fix":"pip install 'smolagents[transformers]'","message":"TransformersModel requires torch and transformers installed separately. pip install smolagents alone is not enough for local model inference.","severity":"gotcha","affected_versions":"all"},{"fix":"Let smolagents manage huggingface-hub version. Do not pin huggingface-hub independently.","message":"huggingface-hub is pinned to <1.0.0 in smolagents. Installing huggingface-hub>=1.0.0 separately breaks the tokenizer build.","severity":"gotcha","affected_versions":">= 1.23.0"},{"fix":"Pass managed_agents=[sub_agent] directly to CodeAgent constructor.","message":"ManagedAgent is deprecated. Multi-agent orchestration now uses managed_agents parameter directly on CodeAgent.","severity":"gotcha","affected_versions":">= 1.15.0"},{"fix":"Pass use_e2b_executor=True or configure docker/modal sandbox on agent init.","message":"CodeAgent executes LLM-generated Python code locally by default. Use E2B, Docker, or Modal sandboxing in production.","severity":"gotcha","affected_versions":"all"},{"fix":"Pin with smolagents==1.24.0 in requirements.txt","message":"API marked experimental — breaking changes ship without major version bumps. Weekly release cadence. Pin version in production.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade Python to 3.10 or newer.","message":"smolagents requires Python >= 3.10. Installation fails on older Python versions.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T08:22:06.487Z","next_check":"2026-04-24T00:00:00.000Z","problems":[{"fix":"from smolagents import CodeAgent, ToolCallingAgent","cause":"The primary agent classes like `CodeAgent` and `ToolCallingAgent` are designed to be imported directly from the top-level `smolagents` package, not from a submodule.","error":"ModuleNotFoundError: No module named 'smolagents.agents'"},{"fix":"agent = CodeAgent(model=...)\nagent.run(prompt=\"...\")","cause":"The `CodeAgent` (or `ToolCallingAgent`) uses a method like `run` or `invoke` to execute its logic, not `predict`, which is a method common in other machine learning contexts but not part of the `smolagents` API.","error":"AttributeError: 'CodeAgent' object has no attribute 'predict'"},{"fix":"Verify the model ID (e.g., 'google/gemma-2b') is correct on HuggingFace Hub, ensure you are logged in with `huggingface-cli login` if it's a private or gated model, and check your network connection.","cause":"The specified HuggingFace model ID is incorrect, the model is private or gated requiring authentication, or there's a network issue preventing the model from being downloaded.","error":"OSError: Error while trying to load model google/gemma-2b. Model name 'google/gemma-2b' was not found in model name list."},{"fix":"Review the raw LLM output to understand why it's not valid JSON, and adjust the `ToolCallingAgent`'s prompt to be more explicit about the required JSON format and structure for the LLM.","cause":"The Language Model output for the `ToolCallingAgent` was malformed and could not be parsed as valid JSON, causing Python's built-in JSON decoder to fail.","error":"json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)"}],"ecosystem":"pypi","meta_description":null,"install_score":37,"install_tag":"stale","quickstart_score":70,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.38,"mem_mb":25.5,"disk_size":"230.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.35,"mem_mb":25.4,"disk_size":"103.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.38,"mem_mb":25.4,"disk_size":"76.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.03,"mem_mb":25.4,"disk_size":"214M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.02,"mem_mb":25.4,"disk_size":"103M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"transformers","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.13,"mem_mb":25.4,"disk_size":"4.8G"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1,"mem_mb":25.4,"disk_size":"78M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.08,"mem_mb":28.3,"disk_size":"247.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.09,"mem_mb":28.3,"disk_size":"111.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.04,"mem_mb":28.3,"disk_size":"82.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.74,"mem_mb":28.3,"disk_size":"231M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.68,"mem_mb":28.3,"disk_size":"111M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"transformers","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.96,"mem_mb":28.3,"disk_size":"4.9G"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.71,"mem_mb":28.3,"disk_size":"83M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.99,"mem_mb":27.9,"disk_size":"235.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.9,"mem_mb":27.9,"disk_size":"101.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.96,"mem_mb":27.9,"disk_size":"73.4M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.94,"mem_mb":27.9,"disk_size":"220M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.93,"mem_mb":27.9,"disk_size":"102M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"transformers","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.15,"mem_mb":27.9,"disk_size":"4.9G"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.95,"mem_mb":27.9,"disk_size":"75M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.87,"mem_mb":28.4,"disk_size":"235.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.85,"mem_mb":28.4,"disk_size":"101.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.91,"mem_mb":28.4,"disk_size":"73.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.9,"mem_mb":28.4,"disk_size":"219M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.87,"mem_mb":28.4,"disk_size":"101M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"transformers","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.09,"mem_mb":28.4,"disk_size":"4.9G"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.82,"mem_mb":28.4,"disk_size":"74M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"transformers","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}