Apply suggestions from code review

Co-authored-by: Pedro Cuenca <pedro@huggingface.co>
Co-authored-by: Aymeric Roucher <69208727+aymeric-roucher@users.noreply.github.com>

units/en/unit2/smolagents/introduction.mdx

@@ -10,15 +10,15 @@ This module provides a comprehensive overview of key concepts and practical stra
 
 With so many open-source frameworks available, it's essential to understand the components and capabilities that make `smolagents` a useful option or to determine when another solution might be a better fit. 
 
-We'll explore critical agent types, including code agents designed for software development tasks, tool calling agents for creating modular, function-driven workflows and retrieval agents that access and synthesize information. 
+We'll explore critical agent types, including code agents designed for software development tasks, tool calling agents for creating modular, function-driven workflows, and retrieval agents that access and synthesize information. 
 
-Additionally, we'll cover the orchestration of multiple agents and the integration of vision capabilities and web browsing to unlock new possibilities for dynamic and context-aware applications.
+Additionally, we'll cover the orchestration of multiple agents as well as the integration of vision capabilities and web browsing, which unlock new possibilities for dynamic and context-aware applications.
 
 In this unit, Alfred, the agent from Unit 1, makes his return. This time, he’s using the `smolagents` framework for his internal workings. Together, we’ll explore the key concepts behind this framework as Alfred tackles various tasks. Alfred is organizing a party at the Wayne Manor while the Wayne family 🦇 is away, and he has plenty to do. Join us as we showcase his journey and how he handles these tasks with `smolagents`!
 
 <Tip>
 
-From this unit, you will learn to build AI agents with the `smolagents` library. Your agents will be able to search for data, execute code, and interact with web pages. You will also learn how to combine multiple agents to create more powerful systems.
+In this unit, you will learn to build AI agents with the `smolagents` library. Your agents will be able to search for data, execute code, and interact with web pages. You will also learn how to combine multiple agents to create more powerful systems.
 
 </Tip>
 
@@ -26,11 +26,11 @@ From this unit, you will learn to build AI agents with the `smolagents` library.
 
 ## Contents
 
-During this unit on `smolagents`, we going to cover:  
+During this unit on `smolagents`, we cover:  
 
 ### 1️⃣ [Why Use smolagents](./why_use_smolagents)
 
-`smolagents` is one of the many open-source agent frameworks available for application development. Alternative options include `LlamaIndex` and `LangGraph`, which are also covered in other modules in this course. This library offers several key features that might make it a great fit for specific use cases, but we should always consider all options when selecting a framework. This module explores the advantages and drawbacks of using `smolagents`, helping you make an informed decision based on your project's requirements.
+`smolagents` is one of the many open-source agent frameworks available for application development. Alternative options include `LlamaIndex` and `LangGraph`, which are also covered in other modules in this course. `smolagents` offers several key features that might make it a great fit for specific use cases, but we should always consider all options when selecting a framework. We'll explore the advantages and drawbacks of using `smolagents`, helping you make an informed decision based on your project's requirements.
 
 ### 2️⃣ [CodeAgents](./code_agents)
 
@@ -38,15 +38,15 @@ During this unit on `smolagents`, we going to cover:
 
 ### 3️⃣ [ToolCallingAgents](./tool_calling_agents)
 
-`ToolCallingAgents` are the second type of agent supported by `smolagents`. Unlike `CodeAgents`, which generate Python code, these agents rely on JSON/text blobs that the system must parse and interpret to execute actions. This module covers their functionality, their key differences from `CodeAgents`, and it provides a coding example to illustrate their usage.  
+`ToolCallingAgents` are the second type of agent supported by `smolagents`. Unlike `CodeAgents`, which generate Python code, these agents rely on JSON/text blobs that the system must parse and interpret to execute actions. This module covers their functionality, their key differences from `CodeAgents`, and it provides an example to illustrate their usage.
 
 ### 4️⃣ [Tools](./tools)
 
-Tools are functions that an LLM can use within an agentic system, acting as essential building blocks for agent behavior. This module covers how to create tools, their structure, and different implementation methods using the `Tool` class or the `@tool` decorator. You'll also learn about the default toolbox, how to share tools with the community, and how to load community-contributed tools for use in your agents.  
+As we saw in Unit 1, tools are functions that an LLM can use within an agentic system, and they act as the essential building blocks for agent behavior. This module covers how to create tools, their structure, and different implementation methods using the `Tool` class or the `@tool` decorator. You'll also learn about the default toolbox, how to share tools with the community, and how to load community-contributed tools for use in your agents.
 
 ### 5️⃣ [Retrieval Agents](./retrieval_agents)
 
-Retrieval agents combine models with knowledge bases, allowing them to search, synthesize, and retrieve information from multiple sources. They leverage vector stores for efficient retrieval and implement **Retrieval-Augmented Generation (RAG)** patterns. These agents are particularly useful for integrating web search with custom knowledge bases while maintaining conversation context through memory systems. This module explores implementation strategies, including fallback mechanisms for robust information retrieval.  
+Retrieval agents allow models access to knowledge bases, making it possible to search, synthesize, and retrieve information from multiple sources. They leverage vector stores for efficient retrieval and implement **Retrieval-Augmented Generation (RAG)** patterns. These agents are particularly useful for integrating web search with custom knowledge bases while maintaining conversation context through memory systems. This module explores implementation strategies, including fallback mechanisms for robust information retrieval.
 
 ### 6️⃣ [Multi-Agent Systems](./multi_agent_systems)
 

units/en/unit2/smolagents/tool_calling_agents.mdx

@@ -4,7 +4,7 @@
     {label: "Google Colab", value: "https://colab.research.google.com/github/huggingface/agents-course/blob/main/notebooks/unit2/smolagents/tool_calling_agents.ipynb"},
 ]} />
 
-# Integrating Agents With Tools
+# Writing actions as code snippets or JSON blobs
 
 <Tip>
 You can follow the code in <a href="https://huggingface.co/agents-course/notebooks/blob/main/unit2/smolagents/tool_calling_agents.ipynb" target="_blank">this notebook</a> that you can run using Google Colab.

units/en/unit2/smolagents/why_use_smolagents.mdx

@@ -10,28 +10,28 @@ In this module, we will explore the pros and cons of using [smolagents](https://
 As we learned in unit 1, AI agents are programs that use LLMs to generate **'thoughts'** based on **'observations'** to perform **'actions'**. Let's explore how this is implemented in smolagents.
 
 ### Key Advantages of `smolagents`
-- **Simplicity:** Minimal code complexity and abstractions
+- **Simplicity:** Minimal code complexity and abstractions, to make the framework easy to understand, adopt and extend
 - **Flexible LLM Support:** Works with any LLM through integration with Hugging Face tools and external APIs
-- **Code-First Approach:** First-class support for Code Agents that directly write their actions in code
+- **Code-First Approach:** First-class support for Code Agents that write their actions directly in code, removing the need for parsing and simplifying tool calling 
-- **HF Hub Integration:** Seamless integration with Hugging Face Hub, allowing the use of Gradio Spaces as tools
+- **HF Hub Integration:** Seamless integration with the Hugging Face Hub, allowing the use of Gradio Spaces as tools
 
 ### When to use smolagents?
 
 With these advantages in mind, when should we use smolagents over other frameworks? 
 
-Smolagents is ideal when:
+smolagents is ideal when:
 - You need a **lightweight and minimal solution.**
 - You want to **experiment quickly** without complex configurations.
 - Your **application logic is straightforward.**
 
 ### Code vs. JSON Actions
-Unlike other frameworks where agents write actions in JSON that require parsing, `smolagents` **focuses on direct tool calls in code**, simplifying the execution process. 
+Unlike other frameworks where agents write actions in JSON, `smolagents` **focuses on tool calls in code**, simplifying the execution process. This is because there's no need to parse the JSON in order to build code that calls the tools: the output can be executed directly.
 
 The following diagram illustrates this difference:
 
 ![Code vs. JSON actions](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/code_vs_json_actions.png)
 
-If you don't remember the difference between Code vs JSON Actions, check [Unit 1, Section Actions](https://huggingface.co/learn/agents-course/unit1/actions#actions-enabling-the-agent-to-engage-with-its-environment).
+To review the difference between Code vs JSON Actions, you can revisit [the Actions Section in Unit 1](https://huggingface.co/learn/agents-course/unit1/actions#actions-enabling-the-agent-to-engage-with-its-environment).
 
 ### Agent Types in `smolagents`
 
@@ -41,26 +41,24 @@ Each [`MultiStepAgent`](https://huggingface.co/docs/smolagents/main/en/reference
 - One thought
 - One tool call and execution
 
-The framework offers two types of agents:
+In addition to using **[CodeAgent](https://huggingface.co/docs/smolagents/main/en/reference/agents#smolagents.CodeAgent)** as the primary type of agent, smolagents also supports **[ToolCallingAgent](https://huggingface.co/docs/smolagents/main/en/reference/agents#smolagents.ToolCallingAgent)**, which writes tool calls in JSON.
-1. **[CodeAgent](https://huggingface.co/docs/smolagents/main/en/reference/agents#smolagents.CodeAgent):** The default agent type that writes tool calls using Python
-2. **[ToolCallingAgent](https://huggingface.co/docs/smolagents/main/en/reference/agents#smolagents.ToolCallingAgent):** Writes tool calls in JSON
 
-We will explore each agent type in more detail in the following units.
+We will explore each agent type in more detail in the following sections.
 
 <Tip> 
-In smolagents, tools are defined using <code>@tool</code> or the <code>Tool</code> class. They are distinct from <code>ToolCallingAgent</code>. Both <code>CodeAgents</code> and <code>ToolCallingAgent</code> utilize tools. Keep this distinction in mind throughout the rest of the unit to avoid confusion! 
+In smolagents, tools are defined using <code>@tool</code> decorator wrapping a python function or the <code>Tool</code> class.
 </Tip>
 
 ### Model Integration in `smolagents`
 `smolagents` supports flexible LLM integration, allowing you to use any callable model that meets [certain criteria](https://huggingface.co/docs/smolagents/main/en/reference/models). The framework provides several predefined classes to simplify model connections:
 
 - **[TransformersModel](https://huggingface.co/docs/smolagents/main/en/reference/models#smolagents.TransformersModel):** Implements a local `transformers` pipeline for seamless integration.
-- **[HfApiModel](https://huggingface.co/docs/smolagents/main/en/reference/models#smolagents.HfApiModel):** Wraps Hugging Face's [InferenceClient](https://huggingface.co/docs/huggingface_hub/main/en/guides/inference) to support the [Inference API](https://huggingface.co/docs/api-inference/index) and [Inference Providers](https://huggingface.co/blog/inference-providers).
+- **[HfApiModel](https://huggingface.co/docs/smolagents/main/en/reference/models#smolagents.HfApiModel):** Supports [serverless inference](https://huggingface.co/docs/huggingface_hub/main/en/guides/inference) calls through [Hugging Face's infrastructure](https://huggingface.co/docs/api-inference/index), or via a growing number of [third-party inference providers](https://huggingface.co/docs/huggingface_hub/main/en/guides/inference#supported-providers-and-tasks).
-- **[LiteLLMModel](https://huggingface.co/docs/smolagents/main/en/reference/models#smolagents.LiteLLMModel):** Leverages [LitLLM](https://www.litellm.ai/) for lightweight model interactions.
+- **[LiteLLMModel](https://huggingface.co/docs/smolagents/main/en/reference/models#smolagents.LiteLLMModel):** Leverages [LiteLLM](https://www.litellm.ai/) for lightweight model interactions.
-- **[OpenAIServerModel](https://huggingface.co/docs/smolagents/main/en/reference/models#smolagents.OpenAIServerModel):** Connects to models compatible with the OpenAI API server.
+- **[OpenAIServerModel](https://huggingface.co/docs/smolagents/main/en/reference/models#smolagents.OpenAIServerModel):** Connects to any service that offers an OpenAI API interface.
 - **[AzureOpenAIServerModel](https://huggingface.co/docs/smolagents/main/en/reference/models#smolagents.AzureOpenAIServerModel):** Supports integration with any Azure OpenAI deployment.
 
-This flexibility ensures that developers can choose the most suitable model integration for their specific use cases.
+This flexibility ensures that developers can choose the model and service most suitable for their specific use cases, and allows for easy experimentation.
 
 Now that we understood why and when to use smolagents, let's dive deeper into this powerful library!