Merge pull request #16 from huggingface/v1.15-release

V1.15 release

Author: joaopauloschuler

README.md

@@ -51,16 +51,16 @@ Full documentation can be found [here](https://huggingface.co/docs/smolagents/in
 
 ## Quick demo
 
-First install the package.
+First install the package with a default set of tools:
 ```bash
-pip install smolagents
+pip install smolagents[toolkit]
 ```
 Then define your agent, give it the tools it needs and run it!
 ```py
-from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel
+from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
 
 model = InferenceClientModel()
-agent = CodeAgent(tools=[DuckDuckGoSearchTool()], model=model)
+agent = CodeAgent(tools=[WebSearchTool()], model=model)
 
 agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")
 ```

docs/source/en/_toctree.yml

@@ -2,6 +2,8 @@
   sections:
   - local: index
     title: 🤗 Agents
+  - local: installation
+    title: Installation
   - local: guided_tour
     title: Guided tour
 - title: Tutorials
@@ -32,6 +34,8 @@
     title: Orchestrate a multi-agent system
   - local: examples/web_browser
     title: Build a web browser agent using vision models
+  - local: examples/using_different_models
+    title: Using different models
 - title: Reference
   sections:
   - local: reference/agents

docs/source/en/examples/multiagents.mdx

@@ -25,7 +25,7 @@ Let's set up this system.
 Run the line below to install the required dependencies:
 
 ```py
-! pip install markdownify duckduckgo-search smolagents --upgrade -q
+!pip install smolagents[toolkit] --upgrade -q
 ```
 
 Let's login to HF in order to call Inference Providers:
@@ -46,9 +46,9 @@ model_id = "Qwen/Qwen2.5-Coder-32B-Instruct"
 
 ## 🔍 Create a web search tool
 
-For web browsing, we can already use our pre-existing [`DuckDuckGoSearchTool`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py#L151-L176) tool to provide a Google search equivalent.
+For web browsing, we can already use our native [`WebSearchTool`] tool to provide a Google search equivalent.
 
-But then we will also need to be able to peak into the page found by the `DuckDuckGoSearchTool`.
+But then we will also need to be able to peak into the page found by the `WebSearchTool`.
 To do so, we could import the library's built-in `VisitWebpageTool`, but we will build it again to see how it's done.
 
 So let's create our `VisitWebpageTool` tool from scratch using `markdownify`.
@@ -109,14 +109,14 @@ from smolagents import (
     CodeAgent,
     ToolCallingAgent,
     InferenceClientModel,
-    DuckDuckGoSearchTool,
+    WebSearchTool,
     LiteLLMModel,
 )
 
 model = InferenceClientModel(model_id=model_id)
 
 web_agent = ToolCallingAgent(
-    tools=[DuckDuckGoSearchTool(), visit_webpage],
+    tools=[WebSearchTool(), visit_webpage],
     model=model,
     max_steps=10,
     name="web_search_agent",

docs/source/en/examples/using_different_models.mdx

@@ -0,0 +1,48 @@
+# Using different models
+
+[[open-in-colab]]
+
+`smolagents` provides a flexible framework that allows you to use various language models from different providers.
+This guide will show you how to use different model types with your agents.
+
+## Available model types
+
+`smolagents` supports several model types out of the box:
+1. [`InferenceClientModel`]: Uses Hugging Face's Inference API to access models
+2. [`TransformersModel`]: Runs models locally using the Transformers library
+3. [`VLLMModel`]: Uses vLLM for fast inference with optimized serving
+4. [`MLXModel`]: Optimized for Apple Silicon devices using MLX
+5. [`LiteLLMModel`]: Provides access to hundreds of LLMs through LiteLLM
+6. [`LiteLLMRouterModel`]: Distributes requests among multiple models
+7. [`OpenAIServerModel`]: Connects to OpenAI's API
+8. [`AzureOpenAIServerModel`]: Uses Azure's OpenAI service
+9. [`AmazonBedrockServerModel`]: Connects to AWS Bedrock's API
+
+## Using Google Gemini Models
+
+As explained in the Google Gemini API documentation (https://ai.google.dev/gemini-api/docs/openai),
+Google provides an OpenAI-compatible API for Gemini models, allowing you to use the [`OpenAIServerModel`]
+with Gemini models by setting the appropriate base URL.
+
+First, install the required dependencies:
+```bash
+pip install smolagents[openai]
+```
+
+Then, [get a Gemini API key](https://ai.google.dev/gemini-api/docs/api-key) and set it in your code:
+```python
+GEMINI_API_KEY = <YOUR-GEMINI-API-KEY>
+```
+
+Now, you can initialize the Gemini model using the `OpenAIServerModel` class
+and setting the `api_base` parameter to the Gemini API base URL:
+```python
+from smolagents import OpenAIServerModel
+
+model = OpenAIServerModel(
+    model_id="gemini-2.0-flash",
+    api_key=GEMINI_API_KEY,
+    # Google Gemini OpenAI-compatible API base URL
+    api_base="https://generativelanguage.googleapis.com/v1beta/openai/",
+)
+```

docs/source/en/guided_tour.mdx

@@ -281,7 +281,7 @@ When the agent is initialized, the tool attributes are used to generate a tool d
 
 ### Default toolbox
 
-`smolagents` comes with a default toolbox for empowering agents, that you can add to your agent upon initialization with argument `add_base_tools=True`:
+If you install `smolagents` with the "toolkit" extra, it comes with a default toolbox for empowering agents, that you can add to your agent upon initialization with argument `add_base_tools=True`:
 
 - **DuckDuckGo web search***: performs a web search using DuckDuckGo browser.
 - **Python code interpreter**: runs your LLM generated Python code in a secure environment. This tool will only be added to [`ToolCallingAgent`] if you initialize it with `add_base_tools=True`, since code-based agent can already natively execute Python code
@@ -290,9 +290,10 @@ When the agent is initialized, the tool attributes are used to generate a tool d
 You can manually use a tool by calling it with its arguments.
 
 ```python
-from smolagents import DuckDuckGoSearchTool
+# !pip install smolagents[toolkit]
+from smolagents import WebSearchTool
 
-search_tool = DuckDuckGoSearchTool()
+search_tool = WebSearchTool()
 print(search_tool("Who's the current president of Russia?"))
 ```
 
@@ -339,7 +340,7 @@ def model_download_tool(task: str) -> str:
 The function needs:
 - A clear name. The name should be descriptive enough of what this tool does to help the LLM brain powering the agent. Since this tool returns the model with the most downloads for a task, let's name it `model_download_tool`.
 - Type hints on both inputs and output
-- A description, that includes an 'Args:' part where each argument is described (without a type indication this time, it will be pulled from the type hint). Same as for the tool name, this description is an instruction manual for the LLM powering you agent, so do not neglect it.
+- A description, that includes an 'Args:' part where each argument is described (without a type indication this time, it will be pulled from the type hint). Same as for the tool name, this description is an instruction manual for the LLM powering your agent, so do not neglect it.
 
 All these elements will be automatically baked into the agent's system prompt upon initialization: so strive to make them as clear as possible!
 
@@ -364,7 +365,7 @@ class ModelDownloadTool(Tool):
 
 The subclass needs the following attributes:
 - A clear `name`. The name should be descriptive enough of what this tool does to help the LLM brain powering the agent. Since this tool returns the model with the most downloads for a task, let's name it `model_download_tool`.
-- A `description`. Same as for the `name`, this description is an instruction manual for the LLM powering you agent, so do not neglect it.
+- A `description`. Same as for the `name`, this description is an instruction manual for the LLM powering your agent, so do not neglect it.
 - Input types and descriptions
 - Output type
 All these attributes will be automatically baked into the agent's system prompt upon initialization: so strive to make them as clear as possible!
@@ -423,15 +424,15 @@ You can easily build hierarchical multi-agent systems with `smolagents`.
 To do so, just ensure your agent has `name` and`description` attributes, which will then be embedded in the manager agent's system prompt to let it know how to call this managed agent, as we also do for tools.
 Then you can pass this managed agent in the parameter managed_agents upon initialization of the manager agent.
 
-Here's an example of making an agent that managed a specific web search agent using our [`DuckDuckGoSearchTool`]:
+Here's an example of making an agent that managed a specific web search agent using our native [`WebSearchTool`]:
 
 ```py
-from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool
+from smolagents import CodeAgent, InferenceClientModel, WebSearchTool
 
 model = InferenceClientModel()
 
 web_agent = CodeAgent(
-    tools=[DuckDuckGoSearchTool()],
+    tools=[WebSearchTool()],
     model=model,
     name="web_search",
     description="Runs web searches for you. Give it your query as an argument."

docs/source/en/installation.mdx

@@ -0,0 +1,114 @@
+# Installation Guide
+
+The `smolagents` library can be installed using pip. Here are the different installation methods and options available.
+
+## Prerequisites
+- Python 3.10 or newer
+- pip
+
+## Basic Installation
+
+Install `smolagents` core library with:
+```bash
+pip install smolagents
+```
+
+## Installation with Extras
+
+`smolagents` provides several optional dependencies (extras) that can be installed based on your needs.
+You can install these extras using the following syntax:
+```bash
+pip install "smolagents[extra1,extra2]"
+```
+
+### Tools
+These extras include various tools and integrations:
+- **toolkit**: Install a default set of tools for common tasks.
+  ```bash
+  pip install "smolagents[toolkit]"
+  ```
+- **mcp**: Add support for the Model Context Protocol (MCP) to integrate with external tools and services.
+  ```bash
+  pip install "smolagents[mcp]"
+  ```
+
+### Model Integration
+These extras enable integration with various AI models and frameworks:
+- **openai**: Add support for OpenAI API models.
+  ```bash
+  pip install "smolagents[openai]"
+  ```
+- **transformers**: Enable Hugging Face Transformers models.
+  ```bash
+  pip install "smolagents[transformers]"
+  ```
+- **vllm**: Add VLLM support for efficient model inference.
+  ```bash
+  pip install "smolagents[vllm]"
+  ```
+- **mlx-lm**: Enable support for MLX-LM models.
+  ```bash
+  pip install "smolagents[mlx-lm]"
+  ```
+- **litellm**: Add LiteLLM support for lightweight model inference.
+  ```bash
+  pip install "smolagents[litellm]"
+  ```
+- **bedrock**: Enable support for AWS Bedrock models.
+  ```bash
+  pip install "smolagents[bedrock]"
+  ```
+
+### Multimodal Capabilities
+Extras for handling different types of media and input:
+- **vision**: Add support for image processing and computer vision tasks.
+  ```bash
+  pip install "smolagents[vision]"
+  ```
+- **audio**: Enable audio processing capabilities.
+  ```bash
+  pip install "smolagents[audio]"
+  ```
+
+### Remote Execution
+Extras for executing code remotely:
+- **docker**: Add support for executing code in Docker containers.
+  ```bash
+  pip install "smolagents[docker]"
+  ```
+- **e2b**: Enable E2B support for remote execution.
+  ```bash
+  pip install "smolagents[e2b]"
+  ```
+
+### Telemetry and User Interface
+Extras for telemetry, monitoring and user interface components:
+- **telemetry**: Add support for monitoring and tracing.
+  ```bash
+  pip install "smolagents[telemetry]"
+  ```
+- **gradio**: Add support for interactive Gradio UI components.
+  ```bash
+  pip install "smolagents[gradio]"
+  ```
+
+### Complete Installation
+To install all available extras, you can use:
+```bash
+pip install "smolagents[all]"
+```
+
+## Verifying Installation
+After installation, you can verify that `smolagents` is installed correctly by running:
+```python
+import smolagents
+print(smolagents.__version__)
+```
+
+## Next Steps
+Once you have successfully installed `smolagents`, you can:
+- Follow the [guided tour](./guided_tour) to learn the basics.
+- Explore the [how-to guides](./examples/text_to_sql) for practical examples.
+- Read the [conceptual guides](./conceptual_guides/intro_agents) for high-level explanations.
+- Check out the [tutorials](./tutorials/building_good_agents) for in-depth tutorials on building agents.
+- Explore the [API reference](./reference/index) for detailed information on classes and functions.

docs/source/en/reference/tools.mdx

@@ -42,6 +42,10 @@ contains the API docs for the underlying classes.
 
 [[autodoc]] UserInputTool
 
+### WebSearchTool
+
+[[autodoc]] WebSearchTool
+
 ### DuckDuckGoSearchTool
 
 [[autodoc]] DuckDuckGoSearchTool

docs/source/en/tutorials/building_good_agents.mdx

@@ -397,15 +397,15 @@ This also works with the [`ToolCallingAgent`].
 We provide a model for a supplementary planning step, that an agent can run regularly in-between normal action steps. In this step, there is no tool call, the LLM is simply asked to update a list of facts it knows and to reflect on what steps it should take next based on those facts.
 
 ```py
-from smolagents import load_tool, CodeAgent, InferenceClientModel, DuckDuckGoSearchTool
+from smolagents import load_tool, CodeAgent, InferenceClientModel, WebSearchTool
 from dotenv import load_dotenv
 
 load_dotenv()
 
 # Import tool from Hub
 image_generation_tool = load_tool("m-ric/text-to-image", trust_remote_code=True)
 
-search_tool = DuckDuckGoSearchTool()
+search_tool = WebSearchTool()
 
 agent = CodeAgent(
     tools=[search_tool, image_generation_tool],

docs/source/en/tutorials/inspect_runs.mdx

@@ -30,7 +30,7 @@ Here's how it then looks like on the platform:
 First install the required packages. Here we install [Phoenix by Arize AI](https://github.com/Arize-ai/phoenix) because that's a good solution to collect and inspect the logs, but there are other OpenTelemetry-compatible platforms that you could use for this collection & inspection part.
 
 ```shell
-pip install 'smolagents[telemetry]'
+pip install 'smolagents[telemetry,toolkit]'
 ```
 
 Then run the collector in the background.
@@ -54,15 +54,15 @@ Then you can run your agents!
 from smolagents import (
     CodeAgent,
     ToolCallingAgent,
-    DuckDuckGoSearchTool,
+    WebSearchTool,
     VisitWebpageTool,
     InferenceClientModel,
 )
 
 model = InferenceClientModel()
 
 search_agent = ToolCallingAgent(
-    tools=[DuckDuckGoSearchTool(), VisitWebpageTool()],
+    tools=[WebSearchTool(), VisitWebpageTool()],
     model=model,
     name="search_agent",
     description="This is an agent that can do web search.",
@@ -143,7 +143,7 @@ SmolagentsInstrumentor().instrument(tracer_provider=trace_provider)
 from smolagents import (
     CodeAgent,
     ToolCallingAgent,
-    DuckDuckGoSearchTool,
+    WebSearchTool,
     VisitWebpageTool,
     InferenceClientModel,
 )
@@ -153,7 +153,7 @@ model = InferenceClientModel(
 )
 
 search_agent = ToolCallingAgent(
-    tools=[DuckDuckGoSearchTool(), VisitWebpageTool()],
+    tools=[WebSearchTool(), VisitWebpageTool()],
     model=model,
     name="search_agent",
     description="This is an agent that can do web search.",

docs/source/en/tutorials/memory.mdx

@@ -83,7 +83,7 @@ Then you should pass this function in the `step_callbacks` argument upon initial
 
 ```py
 CodeAgent(
-    tools=[DuckDuckGoSearchTool(), go_back, close_popups, search_item_ctrl_f],
+    tools=[WebSearchTool(), go_back, close_popups, search_item_ctrl_f],
     model=model,
     additional_authorized_imports=["helium"],
     step_callbacks=[update_screenshot],