[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2192":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},2192,"smolagents","huggingface\u002Fsmolagents","huggingface","🤗 smolagents: a barebones library for agents that think in code.","https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents",null,"Python",27815,2680,136,261,0,16,112,577,91,45,"Apache License 2.0",false,"main",true,[],"2026-06-12 02:00:38","\u003C!---\nCopyright 2024 The HuggingFace Team. All rights reserved.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n-->\n\u003Cp align=\"center\">\n    \u003C!-- Uncomment when CircleCI is set up\n    \u003Ca href=\"https:\u002F\u002Fcircleci.com\u002Fgh\u002Fhuggingface\u002Faccelerate\">\u003Cimg alt=\"Build\" src=\"https:\u002F\u002Fimg.shields.io\u002Fcircleci\u002Fbuild\u002Fgithub\u002Fhuggingface\u002Ftransformers\u002Fmaster\">\u003C\u002Fa>\n    -->\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsmolagents\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg alt=\"License\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fhuggingface\u002Fsmolagents.svg?color=blue\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\">\u003Cimg alt=\"Documentation\" src=\"https:\u002F\u002Fimg.shields.io\u002Fwebsite\u002Fhttp\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Findex.html.svg?down_color=red&down_message=offline&up_message=online\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsmolagents\u002Freleases\">\u003Cimg alt=\"GitHub release\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Frelease\u002Fhuggingface\u002Fsmolagents.svg\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsmolagents\u002Fblob\u002Fmain\u002FCODE_OF_CONDUCT.md\">\u003Cimg alt=\"Contributor Covenant\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FContributor%20Covenant-v2.0%20adopted-ff69b4.svg\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fdeepwiki.com\u002Fhuggingface\u002Fsmolagents\">\u003Cimg src=\"https:\u002F\u002Fdeepwiki.com\u002Fbadge.svg\" alt=\"Ask DeepWiki\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Ch3 align=\"center\">\n  \u003Cdiv style=\"display:flex;flex-direction:row;\">\n    \u003Cimg src=\"https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fhuggingface\u002Fdocumentation-images\u002Fresolve\u002Fmain\u002Fsmolagents\u002Fsmolagents.png\" alt=\"Hugging Face mascot as James Bond\" width=400px>\n    \u003Cp>Agents that think in code!\u003C\u002Fp>\n  \u003C\u002Fdiv>\n\u003C\u002Fh3>\n\n`smolagents` is a library that enables you to run powerful agents in a few lines of code. It offers:\n\n✨ **Simplicity**: the logic for agents fits in ~1,000 lines of code (see [agents.py](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsmolagents\u002Fblob\u002Fmain\u002Fsrc\u002Fsmolagents\u002Fagents.py)). We kept abstractions to their minimal shape above raw code!\n\n🧑‍💻 **First-class support for Code Agents**. Our [`CodeAgent`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Freference\u002Fagents#smolagents.CodeAgent) writes its actions in code (as opposed to \"agents being used to write code\"). To make it secure, we support executing in sandboxed environments via [Blaxel](https:\u002F\u002Fblaxel.ai), [E2B](https:\u002F\u002Fe2b.dev\u002F), [Modal](https:\u002F\u002Fmodal.com\u002F), Docker, or Pyodide+Deno WebAssembly sandbox.\n\n🤗 **Hub integrations**: you can [share\u002Fpull tools or agents to\u002Ffrom the Hub](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Freference\u002Ftools#smolagents.Tool.from_hub) for instant sharing of the most efficient agents!\n\n🌐 **Model-agnostic**: smolagents supports any LLM. It can be a local `transformers` or `ollama` model, one of [many providers on the Hub](https:\u002F\u002Fhuggingface.co\u002Fblog\u002Finference-providers), or any model from OpenAI, Anthropic and many others via our [LiteLLM](https:\u002F\u002Fwww.litellm.ai\u002F) integration.\n\n👁️ **Modality-agnostic**: Agents support text, vision, video, even audio inputs! Cf [this tutorial](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Fexamples\u002Fweb_browser) for vision.\n\n🛠️ **Tool-agnostic**: you can use tools from any [MCP server](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Freference\u002Ftools#smolagents.ToolCollection.from_mcp), from [LangChain](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Freference\u002Ftools#smolagents.Tool.from_langchain), you can even use a [Hub Space](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Freference\u002Ftools#smolagents.Tool.from_space) as a tool.\n\nFull documentation can be found [here](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Findex).\n\n> [!NOTE]\n> Check the our [launch blog post](https:\u002F\u002Fhuggingface.co\u002Fblog\u002Fsmolagents) to learn more about `smolagents`!\n\n## Quick demo\n\nFirst install the package with a default set of tools:\n```bash\npip install \"smolagents[toolkit]\"\n```\nThen define your agent, give it the tools it needs and run it!\n```py\nfrom smolagents import CodeAgent, WebSearchTool, InferenceClientModel\n\nmodel = InferenceClientModel()\nagent = CodeAgent(tools=[WebSearchTool()], model=model, stream_outputs=True)\n\nagent.run(\"How many seconds would it take for a leopard at full speed to run through Pont des Arts?\")\n```\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F84b149b4-246c-40c9-a48d-ba013b08e600\n\nYou can even share your agent to the Hub, as a Space repository:\n```py\nagent.push_to_hub(\"m-ric\u002Fmy_agent\")\n\n# agent.from_hub(\"m-ric\u002Fmy_agent\") to load an agent from Hub\n```\n\nOur library is LLM-agnostic: you could switch the example above to any inference provider.\n\n\u003Cdetails>\n\u003Csummary> \u003Cb>InferenceClientModel, gateway for all \u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Finference-providers\u002Findex\">inference providers\u003C\u002Fa> supported on HF\u003C\u002Fb>\u003C\u002Fsummary>\n\n```py\nfrom smolagents import InferenceClientModel\n\nmodel = InferenceClientModel(\n    model_id=\"deepseek-ai\u002FDeepSeek-R1\",\n    provider=\"together\",\n)\n```\n\u003C\u002Fdetails>\n\u003Cdetails>\n\u003Csummary> \u003Cb>LiteLLM to access 100+ LLMs\u003C\u002Fb>\u003C\u002Fsummary>\n\n```py\nfrom smolagents import LiteLLMModel\n\nmodel = LiteLLMModel(\n    model_id=\"anthropic\u002Fclaude-4-sonnet-latest\",\n    temperature=0.2,\n    api_key=os.environ[\"ANTHROPIC_API_KEY\"]\n)\n```\n\u003C\u002Fdetails>\n\u003Cdetails>\n\u003Csummary> \u003Cb>OpenAI-compatible servers: Together AI\u003C\u002Fb>\u003C\u002Fsummary>\n\n```py\nimport os\nfrom smolagents import OpenAIModel\n\nmodel = OpenAIModel(\n    model_id=\"deepseek-ai\u002FDeepSeek-R1\",\n    api_base=\"https:\u002F\u002Fapi.together.xyz\u002Fv1\u002F\", # Leave this blank to query OpenAI servers.\n    api_key=os.environ[\"TOGETHER_API_KEY\"], # Switch to the API key for the server you're targeting.\n)\n```\n\u003C\u002Fdetails>\n\u003Cdetails>\n\u003Csummary> \u003Cb>OpenAI-compatible servers: OpenRouter\u003C\u002Fb>\u003C\u002Fsummary>\n\n```py\nimport os\nfrom smolagents import OpenAIModel\n\nmodel = OpenAIModel(\n    model_id=\"openai\u002Fgpt-4o\",\n    api_base=\"https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\", # Leave this blank to query OpenAI servers.\n    api_key=os.environ[\"OPENROUTER_API_KEY\"], # Switch to the API key for the server you're targeting.\n)\n```\n\n\u003C\u002Fdetails>\n\u003Cdetails>\n\u003Csummary> \u003Cb>Local `transformers` model\u003C\u002Fb>\u003C\u002Fsummary>\n\n```py\nfrom smolagents import TransformersModel\n\nmodel = TransformersModel(\n    model_id=\"Qwen\u002FQwen3-Next-80B-A3B-Thinking\",\n    max_new_tokens=4096,\n    device_map=\"auto\"\n)\n```\n\u003C\u002Fdetails>\n\u003Cdetails>\n\u003Csummary> \u003Cb>Azure models\u003C\u002Fb>\u003C\u002Fsummary>\n\n```py\nimport os\nfrom smolagents import AzureOpenAIModel\n\nmodel = AzureOpenAIModel(\n    model_id = os.environ.get(\"AZURE_OPENAI_MODEL\"),\n    azure_endpoint=os.environ.get(\"AZURE_OPENAI_ENDPOINT\"),\n    api_key=os.environ.get(\"AZURE_OPENAI_API_KEY\"),\n    api_version=os.environ.get(\"OPENAI_API_VERSION\")    \n)\n```\n\u003C\u002Fdetails>\n\u003Cdetails>\n\u003Csummary> \u003Cb>Amazon Bedrock models\u003C\u002Fb>\u003C\u002Fsummary>\n\n```py\nimport os\nfrom smolagents import AmazonBedrockModel\n\nmodel = AmazonBedrockModel(\n    model_id = os.environ.get(\"AMAZON_BEDROCK_MODEL_ID\") \n)\n```\n\u003C\u002Fdetails>\n\n## CLI\n\nYou can run agents from CLI using two commands: `smolagent` and `webagent`.\n\n`smolagent` is a generalist command to run a multi-step `CodeAgent` that can be equipped with various tools.\n\n```bash\n# Run with direct prompt and options\nsmolagent \"Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7.\"  --model-type \"InferenceClientModel\" --model-id \"Qwen\u002FQwen3-Next-80B-A3B-Thinking\" --imports pandas numpy --tools web_search\n\n# Run in interactive mode (launches setup wizard when no prompt provided)\nsmolagent\n```\n\nInteractive mode guides you through:\n- Agent type selection (CodeAgent vs ToolCallingAgent)  \n- Tool selection from available toolbox\n- Model configuration (type, ID, API settings)\n- Advanced options like additional imports\n- Task prompt input\n\nMeanwhile `webagent` is a specific web-browsing agent using [helium](https:\u002F\u002Fgithub.com\u002Fmherrmann\u002Fhelium) (read more [here](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsmolagents\u002Fblob\u002Fmain\u002Fsrc\u002Fsmolagents\u002Fvision_web_browser.py)).\n\nFor instance:\n```bash\nwebagent \"go to xyz.com\u002Fmen, get to sale section, click the first clothing item you see. Get the product details, and the price, return them. note that I'm shopping from France\" --model-type \"LiteLLMModel\" --model-id \"gpt-5\"\n```\n\n## How do Code agents work?\n\nOur [`CodeAgent`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Freference\u002Fagents#smolagents.CodeAgent) works mostly like classical ReAct agents - the exception being that the LLM engine writes its actions as Python code snippets.\n\n```mermaid\nflowchart TB\n    Task[User Task]\n    Memory[agent.memory]\n    Generate[Generate from agent.model]\n    Execute[Execute Code action - Tool calls are written as functions]\n    Answer[Return the argument given to 'final_answer']\n\n    Task -->|Add task to agent.memory| Memory\n\n    subgraph ReAct[ReAct loop]\n        Memory -->|Memory as chat messages| Generate\n        Generate -->|Parse output to extract code action| Execute\n        Execute -->|No call to 'final_answer' tool => Store execution logs in memory and keep running| Memory\n    end\n    \n    Execute -->|Call to 'final_answer' tool| Answer\n\n    %% Styling\n    classDef default fill:#d4b702,stroke:#8b7701,color:#ffffff\n    classDef io fill:#4a5568,stroke:#2d3748,color:#ffffff\n    \n    class Task,Answer io\n```\n\nActions are now Python code snippets. Hence, tool calls will be performed as Python function calls. For instance, here is how the agent can perform web search over several websites in one single action:\n```py\nrequests_to_search = [\"gulf of mexico america\", \"greenland denmark\", \"tariffs\"]\nfor request in requests_to_search:\n    print(f\"Here are the search results for {request}:\", web_search(request))\n```\n\nWriting actions as code snippets is demonstrated to work better than the current industry practice of letting the LLM output a dictionary of the tools it wants to call: [uses 30% fewer steps](https:\u002F\u002Fhuggingface.co\u002Fpapers\u002F2402.01030) (thus 30% fewer LLM calls) and [reaches higher performance on difficult benchmarks](https:\u002F\u002Fhuggingface.co\u002Fpapers\u002F2411.01747). Head to [our high-level intro to agents](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Fconceptual_guides\u002Fintro_agents) to learn more on that.\n\nSince code execution can be a serious security concern (arbitrary code execution!), **you should run agent code in a sandbox**. We support several options:\n  - [E2B](https:\u002F\u002Fe2b.dev\u002F), [Blaxel](https:\u002F\u002Fblaxel.ai), [Modal](https:\u002F\u002Fmodal.com\u002F) — managed cloud sandboxes, simplest to set up\n  - [Docker](https:\u002F\u002Fwww.docker.com\u002F) — self-hosted container isolation\n  - Pyodide+Deno WebAssembly — lightweight sandbox for browser or edge environments\n\nThe built-in `LocalPythonExecutor` is **not a security sandbox**. It applies some restrictions but can be bypassed and must not be used as a security boundary.\n\nAlongside [`CodeAgent`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Freference\u002Fagents#smolagents.CodeAgent), we also provide the standard [`ToolCallingAgent`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Freference\u002Fagents#smolagents.ToolCallingAgent) which writes actions as JSON\u002Ftext blobs. You can pick whichever style best suits your use case.\n\n## How smol is this library?\n\nWe strived to keep abstractions to a strict minimum: the main code in `agents.py` has \u003C1,000 lines of code.\nStill, we implement several types of agents: `CodeAgent` writes its actions as Python code snippets, and the more classic `ToolCallingAgent` leverages built-in tool calling methods. We also have multi-agent hierarchies, import from tool collections, remote code execution, vision models...\n\nBy the way, why use a framework at all? Well, because a big part of this stuff is non-trivial. For instance, the code agent has to keep a consistent format for code throughout its system prompt, its parser, the execution. So our framework handles this complexity for you. But of course we still encourage you to hack into the source code and use only the bits that you need, to the exclusion of everything else!\n\n## How strong are open models for agentic workflows?\n\nWe've created [`CodeAgent`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fsmolagents\u002Freference\u002Fagents#smolagents.CodeAgent) instances with some leading models, and compared them on [this benchmark](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fm-ric\u002Fagents_medium_benchmark_2) that gathers questions from a few different benchmarks to propose a varied blend of challenges.\n\n[Find the benchmarking code here](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsmolagents\u002Fblob\u002Fmain\u002Fexamples\u002Fsmolagents_benchmark\u002Frun.py) for more detail on the agentic setup used, and see a comparison of using LLMs code agents compared to vanilla (spoilers: code agents works better).\n\n\u003Cp align=\"center\">\n    \u003Cimg src=\"https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fhuggingface\u002Fdocumentation-images\u002Fresolve\u002Fmain\u002Fsmolagents\u002Fbenchmark_code_agents.jpeg\" alt=\"benchmark of different models on agentic workflows. Open model DeepSeek-R1 beats closed-source models.\" width=60% max-width=500px>\n\u003C\u002Fp>\n\nThis comparison shows that open-source models can now take on the best closed models!\n\n## Security\n\nSecurity is a critical consideration when working with code-executing agents. Ensure you are using one of the sandboxed execution options that provide isolation from untrusted code.\n\n**Warning:** `LocalPythonExecutor` provides best-effort mitigations only and is **not a security boundary**. Do not use it to run untrusted code.\n\nFor security policies, vulnerability reporting, and more information on secure agent execution, please see our [Security Policy](SECURITY.md).\n\n## Contribute\n\nEveryone is welcome to contribute, get started with our [contribution guide](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsmolagents\u002Fblob\u002Fmain\u002FCONTRIBUTING.md).\n\n## Cite smolagents\n\nIf you use `smolagents` in your publication, please cite it by using the following BibTeX entry.\n\n```bibtex\n@Misc{smolagents,\n  title =        {`smolagents`: a smol library to build great agentic systems.},\n  author =       {Aymeric Roucher and Albert Villanova del Moral and Thomas Wolf and Leandro von Werra and Erik Kaunismäki},\n  howpublished = {\\url{https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsmolagents}},\n  year =         {2025}\n}\n```\n","smolagents 是一个用于创建能够以代码形式思考的代理的轻量级库。其核心功能包括通过简洁的代码实现强大的代理逻辑（大约1000行），支持代码代理在安全的沙箱环境中运行，如Blaxel、E2B、Modal等，并且集成了Hugging Face Hub，方便用户分享和获取工具或代理。该项目特别适合需要快速构建、测试及部署基于代码执行任务的场景，例如自动化脚本生成、代码辅助开发等领域。",2,"2026-06-11 02:48:42","top_language"]