From 773008524c475b0b9bfc8512ac6feab19cbbf85a Mon Sep 17 00:00:00 2001 From: Aymeric Date: Sun, 22 Dec 2024 21:42:51 +0100 Subject: [PATCH] Refacto doc --- README.md | 50 +++++++++++++------ docs/source/_toctree.yml | 4 +- docs/source/guided_tour.md | 6 +-- docs/source/index.md | 30 +++-------- docs/source/tutorials/building_good_agents.md | 4 ++ 5 files changed, 50 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index f7abcbc..cdd66a5 100644 --- a/README.md +++ b/README.md @@ -25,22 +25,44 @@ limitations under the License.

-

Run agents! +

Run agents!

-W +# 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! -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! \ No newline at end of file +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. diff --git a/docs/source/_toctree.yml b/docs/source/_toctree.yml index 1027139..d6b0544 100644 --- a/docs/source/_toctree.yml +++ b/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 diff --git a/docs/source/guided_tour.md b/docs/source/guided_tour.md index 21649b3..5c3e5e2 100644 --- a/docs/source/guided_tour.md +++ b/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 diff --git a/docs/source/index.md b/docs/source/index.md index 04b3436..4116215 100644 --- a/docs/source/index.md +++ b/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.
-
Tutorials
+
Guided tour

Learn the basics and become familiar with using Agents. Start here if you are using Agents for the first time!

 High-level explanations for building a better understanding of important topics to build better functioning agents.
Reference
-

General, horizontal tutorials.

+ >
Tutorials
+

Horizontal tutorials that cover important aspects of building agents.
diff --git a/docs/source/tutorials/building_good_agents.md b/docs/source/tutorials/building_good_agents.md index ed01a71..061a218 100644 --- a/docs/source/tutorials/building_good_agents.md +++ b/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.