Refacto doc

README.md

@@ -25,22 +25,44 @@ limitations under the License.
 </p>
 
 <h3 align="center">
-<p>Run agents!
+<p>Run agents!</p>
 </h3>
 
-W
+# Agents
 
-<div class="flex justify-center">
-    <img
-        class="block dark:hidden"
-        src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/Agent_ManimCE.gif"
-    />
-    <img
-        class="hidden dark:block"
-        src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/Agent_ManimCE.gif"
-    />
-</div>
+Agents is a library that enables you to run powerful agents in a few lines of code!
+It is:
+- lightweight
+- understandable (we kept abstractions to the minimum)
+- the only library with first-class support for Code Agents, i.e. agents that write their actions in code!
 
-To run Docker, run `docker build -t pyrunner:latest .`
+Quick demo:
+First install the package.
+```bash
+pip install agents
+```
+Then define your agent, give it the tools it needs and run it!
+```py
+from agents import CodeAgent, WebSearchTool
 
-This will use the Local Dockerfile to create your Docker image!
+agent = CodeAgent(tools=[WebSearchTool()])
+
+agent.run("What time would the world's fastest car take to travel from New York to San Francisco?")
+```
+
+> TODO: Add video
+
+## Code agents?
+
+We built agents where the LLM engine writes its actions in code. This approach is demonstrated to work better than the current industry practice of letting the LLM output a dictionary of the tools it wants to calls: [uses 30% fewer steps](https://huggingface.co/papers/2402.01030) (thus 30% fewer LLM calls)
+and [reaches higher performance on difficult benchmarks](https://huggingface.co/papers/2411.01747). Head to [./conceptual_guides/intro_agents.md] to learn more on that.
+
+Especially, since code execution can be a security concern (arbitrary code execution!), we provide options at runtime:
+  - a secure python interpreter to run code more safely in your environment
+  - a sandboxed environment.
+
+## How lightweight is it?
+
+We strived to keep abstractions to a strict minimum, with the main code in `agents.py` being roughly 1,000 lines of code, and still being quite complete, with several types of agents implemented: `CodeAgent` writing its actions in code snippets, `JsonAgent`, `ToolCallingAgent`...
+
+Many people ask: 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. Its variables have to be properly handled throughout. So our framework handles this complexity for you.

docs/source/_toctree.yml

@@ -2,8 +2,8 @@
   sections:
   - local: index
     title: 🤗 Agents
-  - local: quicktour
-    title: ⏱️ Quick tour
+  - local: guided_tour
+    title: Guided tour
 - title: Tutorials
   sections:
   - local: tutorials/building_good_agents

docs/source/guided_tour.md

@@ -25,12 +25,10 @@ To initialize an agent, you need these arguments:
 
 - An LLM to power your agent - because the agent is different from a simple LLM, it is a system that uses a LLM as its engine.
 - A toolbox from which the agent pick tools to execute
-- A system prompt: what the LLM engine will be prompted with to generate its output
 
-Upon initialization of the agent system, the `system_prompt` is built automatically by turning the description extracted from the tools into a predefined system prompt template.
+Upon initialization of the agent system, a system prompt (attribute `system_prompt`) is built automatically by turning the description extracted from the tools into a predefined system prompt template. But you can customize it!
 
-
-Build your LLM engine by defining a `llm_engine` method which accepts a list of [messages](./chat_templating) and returns text. This callable also needs to accept a `stop` argument that indicates when to stop generating.
+For defining your llm, you can make a `llm_engine` method which accepts a list of [messages](./chat_templating) and returns text. This callable also needs to accept a `stop` argument that indicates when to stop generating.
 
 ```python
 from huggingface_hub import login, InferenceClient

docs/source/index.md

@@ -15,33 +15,15 @@ rendered properly in your Markdown viewer.
 
 # Agents
 
-Agents is a library that enables you to run powerful agents in a few lines of code!
-It is:
-- lightweight
-- understandable (we kept abstractions to the minimum)
-- the only library with first-class support for Code Agents, i.e. agents that write their actions in code!
+This library is the simplest framework out there to build powerful agents!
 
-Here is a demo:
+In particular, it has first-class support for Code Agents, i.e. agents that write their actions in code (as opposed to "agents being used to write code", which many good libraries do).
 
-## How lightweight is it?
-
-We strived to keep abstractions to a strict minimum.
-You could go lower and code it all yourself, but some of this stuff is non-trivial. For instance, if you define a format for tool expression, you have to specify the same format in your system prompt, your parser, and your possibke error logging to let the LLM correct itself.
-
-
-## Code agents?
-
-We can let LLMs powering agentic systems write their actions in code. This approach is demonstrated to work better than the current industry practice of letting the LLM output a dictionary of the tools it wants to calls: [uses 30% fewer steps](https://huggingface.co/papers/2402.01030) (thus 30% fewer LLM calls)
-and [reaches higher performance on difficult benchmarks](https://huggingface.co/papers/2411.01747). Head to [./conceptual_guides/intro_agents.md] to learn more on that.
-
-Especially, since code execution can be a security concern (arbitrary code execution!), we provide options at runtime:
-  - a secure python interpreter to run code more safely in your environment
-  - a sandboxed environment.
 
 <div class="mt-10">
   <div class="w-full flex flex-col space-y-4 md:space-y-0 md:grid md:grid-cols-2 md:gap-y-4 md:gap-x-5">
-    <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./tutorials/tools"
-      ><div class="w-full text-center bg-gradient-to-br from-blue-400 to-blue-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Tutorials</div>
+    <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./guided_tour"
+      ><div class="w-full text-center bg-gradient-to-br from-blue-400 to-blue-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Guided tour</div>
       <p class="text-gray-700">Learn the basics and become familiar with using Agents. Start here if you are using Agents for the first time!</p>
     </a>
     <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./examples/text_to_sql"
@@ -53,8 +35,8 @@ Especially, since code execution can be a security concern (arbitrary code execu
       <p class="text-gray-700">High-level explanations for building a better understanding of important topics to build better functioning agents.</p>
    </a>
     <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./tutorials/building_good_agents"
-      ><div class="w-full text-center bg-gradient-to-br from-purple-400 to-purple-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Reference</div>
-      <p class="text-gray-700">General, horizontal tutorials.</p>
+      ><div class="w-full text-center bg-gradient-to-br from-purple-400 to-purple-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Tutorials</div>
+      <p class="text-gray-700">Horizontal tutorials that cover important aspects of building agents.</p>
     </a>
   </div>
 </div>

docs/source/tutorials/building_good_agents.md

@@ -152,6 +152,10 @@ The first step to debugging your agent is thus "Use a more powerful LLM". Altern
 
 Then you can also use less powerful models but guide them better.
 
+Put yourself in the shoes if your model: if you were the model solving the task, would you struggle with the information available to you (from the system prompt + task formulation + tool description) ?
+
+Would you need some added claritications ? 
+
 To provide extra information, we do not recommend modifying the system prompt compared to default : there are many adjustments there that you do not want to mess up except if you understand the prompt very well.
 Better ways to guide your LLM engine are:
 - If it 's about the task to solve: add all these details to the task. The task could be 100s of pages long.