Merge branch 'feat/update-docs'

Author: ashpreetbedi

agents/introduction.mdx

@@ -4,24 +4,30 @@ title: Introduction
 
 ## What are Agents?
 
-**Agents** are intelligent programs that solve problems autonomously.
+**Agents** are AI programs that operate autonomously.
 
-Agents have memory, domain knowledge and the ability to use tools (like searching the web, querying a database, making API calls). Unlike traditional programs that follow a predefined execution path, Agents dynamically adapt their approach based on the context and tool results.
+The core of an Agent is a model, the tools it has access to, and instructions to guide its behavior.
 
-Instead of a rigid binary definition, let's think of Agents in terms of agency and autonomy.
+- The **model** acts as the **brain** of the Agent - helping it reason, act, and respond to the user. Better the model, smarter the Agent.
+- **Tools** are the **body** of the Agent - enabling it to interact with the real world. "Tool-use" is what makes these systems "Agentic".
+- **Instructions** guide the **behavior** of the Agent. Better the model, better it is at following instructions.
 
-- **Level 0**: Agents with no tools (basic inference tasks).
-- **Level 1**: Agents with tools for autonomous task execution.
-- **Level 2**: Agents with knowledge, combining memory and reasoning.
-- **Level 3**: Teams of specialized agents collaborating on complex workflows.
+Agents also have **memory**, **knowledge**, **storage** and the ability to **reason**.
+
+- **reasoning:** lets Agents "think" before responding and "analyze" the results of their actions (i.e. tool calls). Reasoning improves the Agents ability to solve problems that require multi-step tool use. Reasoning improves quality, but also increases latency and cost.
+- **knowledge:** is domain-specific information the Agent can **_search on demand_** to make better decisions (dynamic few-shot learning) or provide accurate responses (agentic RAG). This knowledge is stored in a vector database and this _**Agent's searching on demand**_ pattern is known as Agentic Search. **Agno (is aiming to) have first class support for the popular Agentic Search pattern, Hybrid Search + Reranking, for every major vector database.**
+- **storage:** is used by Agents to save session history and state in a database. Model APIs are stateless and storage enables us to continue conversations across runs using a `session_id`. This makes Agents stateful and enables multi-turn conversations.
+- **memory:** gives Agents the ability to store and recall information from previous interactions, allowing them to learn user preferences and personalize their responses. This is an evolving field and Agno is aiming to support the popular Memory patterns.
 
 <img height="200" src="/images/agent.png" style={{ borderRadius: "8px" }} />
 
-If this is your first time building agents, [follow this guide](/agents) and then dive into more advanced concepts.
+<Check>
+If this is your first time building agents, [follow these examples](/introduction/agents#basic-agent) before diving into advanced concepts.
+</Check>
 
 ## Example: Research Agent
 
-Let's create a research agent that can search the web using DuckDuckGo, scrape the top links using Newspaper4k and write a research report for us. Ideally we'll use specialized tools (like Exa) but let's start with the free tools first.
+Let's build a research agent using Exa to showcase how to guide the Agent to produce the report in a specific format. In advanced cases, we should use [Structured Outputs](/agents/structured-output) instead.
 
 <Note>
   The description and instructions are converted to the system message and the

agents/run.mdx

@@ -4,6 +4,10 @@ title: Agent.run()
 
 Use the `Agent.run()` function to run the agent and return the response as a `RunResponse` object or a stream of `RunResponse` objects.
 
+<Tip>
+Many of our examples use `agent.print_response()` but that is just a helper utility to print the response in the terminal. In practice, you should always use `agent.run()`.
+</Tip>
+
 ```python
 from typing import Iterator
 from agno.agent import Agent, RunResponse

agents/sessions.mdx

@@ -1,15 +1,18 @@
 ---
-title: 
+title: Sessions
 ---
 
-Agents are able to maintain a conversation with one or more users. It is important to understand the following concepts:
+When we call `Agent.run()`, it creates a stateless, singular Agent run.
 
-- **Session:** Each conversation with an Agent is called a **session**. Sessions are identified by a `session_id` and should be unique for each user.
-- **Run:** Every interaction (i.e. chat) within a session is called a **run**. Runs are identified by a `run_id`.
-- **Messages:** are the individual messages sent to and received from the model. They have a `role` (`system`, `user` or `assistant`) and `content`.
+But what if we want to continue this run i.e. have a multi-turn conversation? That's where `sessions` come in. A session is a multi-turn conversation between a user and an Agent. Using a `session_id`, we can maintain conversation history and state across multiple runs.
 
+Let's outline some key concepts:
 
-Below is an example where a single run is created with an Agent. A `session_id` is automatically generated and added to the run. This won't be associated with any specific user.
+- **Session:** A session is a multi-turn conversation between a user and an Agent. Sessions are identified by a `session_id` and each turn is called a **run**.
+- **Run:** Every interaction (i.e. chat or turn) with an Agent is called a **run**. Runs are identified by a `run_id`. `Agent.run()` creates a new `run_id` when called.
+- **Messages:** are the individual messages sent to and received from the model. They are the underlying data structure that the Agent and model communicate using. Each run contains a list of messages and each session contains a list of runs.
+
+Let's start with an example where a single run is created with an Agent. A `run_id` is automatically generated, as well as a `session_id` (because we didn't provide one to continue the conversation). This run is not yet associated with a specific user.
 
 ```python
 from typing import Iterator
@@ -23,22 +26,31 @@ agent = Agent(model=OpenAIChat(id="gpt-4o-mini"))
 agent.print_response("Tell me a 5 second short story about a robot")
 ```
 
-## Multiple Users with Sessions
+## Each User gets a Unique Set of Sessions
+
+Each user that is interacting with an Agent maintains a unique set of sessions. Set a `user_id` to connect a user to their sessions.
+
+In the examples below, we set a `session_id` to demo how you can continue multi-turn conversations with multiple users at the same time. In production, the `session_id` is automatically generated.
 
-Sessions are unique for each user. If you want to maintain a conversation with multiple users, you can use the `user_id` and `session_id` to identify the session.
+Note: Multi-user, multi-session currently only works with `Memory.v2`.
 
-This requires storage of sessions. See [storage](/agents/storage) for more information.
+<Tip>
+
+`Memory.v2` will become the default memory implementation in the next release.
+
+</Tip>
 
 ```python
-from typing import Iterator
-from agno.agent import Agent, RunResponse
+from agno.agent import Agent
 from agno.models.openai import OpenAIChat
-from agno.utils.pprint import pprint_run_response
-from agno.storage.postgres import PostgresStorage
+from agno.memory.v2 import Memory
 
 agent = Agent(
-    model=OpenAIChat(id="gpt-4o-mini"), 
-    storage=PostgresStorage(table_name="agent_sessions", db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"),
+    model=OpenAIChat(id="gpt-4o-mini"),
+    # Multi-user, multi-session only work with Memory.v2
+    memory=Memory(),
+    add_history_to_messages=True,
+    num_history_runs=3,
 )
 
 user_1_id = "user_101"
@@ -48,7 +60,11 @@ user_1_session_id = "session_101"
 user_2_session_id = "session_102"
 
 # Start the session with user 1
-agent.print_response("Tell me a 5 second short story about a robot.", user_id=user_1_id, session_id=user_1_session_id)
+agent.print_response(
+    "Tell me a 5 second short story about a robot.",
+    user_id=user_1_id,
+    session_id=user_1_session_id,
+)
 # Continue the session with user 1
 agent.print_response("Now tell me a joke.", user_id=user_1_id, session_id=user_1_session_id)
 
@@ -57,6 +73,10 @@ agent.print_response("Tell me about quantum physics.", user_id=user_2_id, sessio
 # Continue the session with user 2
 agent.print_response("What is the speed of light?", user_id=user_2_id, session_id=user_2_session_id)
 
-# Continue the session with user 1
-agent.print_response("What can you tell me about what AIs are capable of?", user_id=user_1_id, session_id=user_1_session_id)
+# Ask the agent to give a summary of the conversation, this will use the history from the previous messages
+agent.print_response(
+    "Give me a summary of our conversation.",
+    user_id=user_1_id,
+    session_id=user_1_session_id,
+)
 ```

introduction.mdx

@@ -5,7 +5,7 @@ sidebarTitle: What is Agno
 
 **Agno is a lightweight library for building Agents with memory, knowledge, tools and reasoning.**
 
-Developers use Agno to build Reasoning Agents, Multimodal Agents, Teams of Agents and Agentic Workflows. Agno also provides a beautiful UI to chat with Agents and tools to monitor and evaluate their performance.
+Developers use Agno to build Reasoning Agents, Multimodal Agents, Teams of Agents and Agentic Workflows. Agno also provides a beautiful UI to chat with your Agents and tools to monitor and evaluate their performance.
 
 Here's an Agent that researches and writes a report on a stock, reasoning through each step:
 
@@ -45,19 +45,19 @@ agent.print_response("Write a report on NVDA", stream=True, show_full_reasoning=
 
 Agno is simple, fast and model-agnostic. Here are some key features:
 
-- **Model Agnostic**: Agno provides a unified interface to 23+ model providers, no lock-in.
+- **Model Agnostic**: Agno Agents can connect to 23+ model providers, no lock-in.
 - **Lightning Fast**: Agents instantiate in **~2μs** on average (10,000x faster than LangGraph) and use **~3.75Kib** memory on average (50x less than LangGraph) (see [benchmarks](https://github.com/agno-agi/agno#performance)).
-- **Reasoning is a first class citizen**: Build Agents that can "think" and "analyze" using Reasoning Models, `ReasoningTools` or our custom `CoT+Tool-use` approach.
+- **Reasoning is a first class citizen**: Make your Agents "think" and "analyze" using Reasoning Models, `ReasoningTools` or our custom `CoT+Tool-use` approach.
 - **Natively Multi Modal**: Agno Agents are natively multi modal, they can take in text, image, audio and video and generate text, image, audio and video as output.
 - **Advanced Multi Agent Architecture**: Agno provides an industry leading multi-agent architecture with 3 different modes: `route`, `collaborate` and `coordinate`.
-- **Long-term Memory & Session Storage**: Agno provides `Storage` & `Memory` classes to provide your Agents with long-term memory and session storage.
-- **20+ Vector Databases for Knowledge**: Add domain knowledge to your Agents by integrating with 20+ vector databases. **Fully async and highly performant.**
-- **Structured Outputs**: Agno Agents have first class support for structured outputs using native structured outputs or `json_mode`.
+- **Agentic RAG using Hybrid Search + Reranking**: Give your Agents access to domain knowledge using one of 20+ vector databases. Get access to state-of-the-art Agentic search that uses hybrid search with re-ranking. **Fully async and highly performant.**
+- **Long-term Memory & Session Storage**: Agno provides plug-n-play `Storage` & `Memory` drivers that give your Agents long-term memory and session storage.
+- **Structured Outputs**: Agno Agents can return fully-typed responses using model provided structured outputs or `json_mode`.
 - **Monitoring**: Monitor agent sessions and performance in real-time on [agno.com](https://app.agno.com).
 
 # Getting Started
 
-If you're new to Agno, start by building your [first Agent](/introduction/agents), then chat with it on the [playground](/introduction/playground) and finally, monitor it on [agno.com](/introduction/monitoring).
+If you're new to Agno, start by building your [first Agent](/introduction/agents), chat with it on the [playground](/introduction/playground) and finally, monitor it on [agno.com](/introduction/monitoring).
 
 <CardGroup cols={3}>
   <Card
@@ -90,59 +90,73 @@ After that, checkout the [Examples Gallery](/examples) and build real-world appl
 
 # Dive deeper
 
-Agno is a battle-tested framework with a state-of-the-art multi-agent architecture and ridiculous performance, checkout the following guides to dive-in:
+Agno is a battle-tested framework with a state-of-the-art reasoning and multi-agent architecture, checkout the following guides to dive-in:
 
 <CardGroup cols={3}>
   <Card title="Agents" icon="user-astronaut" iconType="duotone" href="/agents">
-    Learn core Agent concepts
+    Learn how to build lightning fast Agents.
+  </Card>
+  <Card title="Teams" icon="microchip" iconType="duotone" href="/teams">
+    Build state-of-the-art multi-agent teams.
   </Card>
   <Card title="Models" icon="microchip" iconType="duotone" href="/models">
-    Use any model, any provider, no lock-in
+    Use any model, any provider, no lock-in.
   </Card>
   <Card
     title="Tools"
     icon="screwdriver-wrench"
     iconType="duotone"
     href="/tools"
   >
-    Use 100s of tools to extend your Agents
+    Use 100s of tools to extend your Agents.
+  </Card>
+  <Card title="Reasoning" icon="brain" iconType="duotone" href="/reasoning">
+    Make your Agents "think" and "analyze".
   </Card>
   <Card title="Knowledge" icon="brain" iconType="duotone" href="/knowledge">
-    Add domain-specific knowledge to your Agents
+    Add domain knowledge using Agentic RAG.
   </Card>
   <Card
     title="Vector Databases"
     icon="spider-web"
     iconType="duotone"
     href="/vectordb"
   >
-    Add semantic search and retrieval to your Agents
+    Vector databases that can be used with Knowledge.
   </Card>
   <Card title="Storage" icon="database" iconType="duotone" href="/storage">
-    Persist agent states and conversations in a database
+    Persist agent session and state in a database.
   </Card>
   <Card
     title="Memory"
     icon="lightbulb"
     iconType="duotone"
     href="/agents/memory"
   >
-    Remember user details and session summaries
+    Remember user details and session summaries.
   </Card>
   <Card
     title="Embeddings"
     icon="network-wired"
     iconType="duotone"
     href="/embedder"
   >
-    Generate embeddings for your knowledge base
+    Generate embeddings for your knowledge base.
   </Card>
   <Card
     title="Workflows"
     icon="diagram-project"
     iconType="duotone"
     href="/workflows"
   >
-    Build complex workflows with Agents
+    Build stateful, dynamic, multi-agent workflows.
+  </Card>
+  <Card
+    title="Evals"
+    icon="diagram-project"
+    iconType="duotone"
+    href="/evals"
+  >
+    Evaluate your Agents and monitor performance.
   </Card>
 </CardGroup>