> ## Documentation Index
> Fetch the complete documentation index at: https://ikun.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

当我们调用 `Agent.run()` 时，它会创建一个无状态、单一的 Agent 运行。

但是，如果我们想继续这次运行，例如进行多轮对话，该怎么办？这时就需要用到 `sessions`。Session 是一系列连续运行的集合。

实际上，Session 是用户和 Agent 之间进行的多轮对话。通过 `session_id`，我们可以在多次运行中连接对话历史记录和状态。

让我们概述一些关键概念：

* **Session:** Session 是连续运行的集合，就像用户和 Agent 之间的多轮对话一样。Session 由 `session_id` 标识，每一轮是一个 **run**。
* **Run:** 与 Agent 的每一次交互（即聊天或轮次）都称为一次 **run**。Run 由 `run_id` 标识，调用 `Agent.run()` 时会创建一个新的 `run_id`。
* **Messages:** 是在模型和 Agent 之间发送的独立消息。Messages 是 Agent 和模型之间的通信协议。

让我们从一个使用 Agent 创建单次运行的示例开始。系统会自动生成 `run_id` 和 `session_id`（因为我们没有提供 `session_id` 来继续对话）。这次运行尚未与用户关联。

```python theme={null}
from typing import Iterator
from agno.agent import Agent, RunResponse
from agno.models.openai import OpenAIChat
from agno.utils.pprint import pprint_run_response

agent = Agent(model=OpenAIChat(id="gpt-4o-mini"))

# 运行 agent 并将响应返回给一个变量
agent.print_response("Tell me a 5 second short story about a robot")
```

## 多用户、多 Session 的 Agent

每个与 Agent 交互的用户都有自己的一组唯一的 Session，并且您可以让多个用户同时与同一个 Agent 进行交互。

设置 `user_id` 可以将用户与其在 Agent 上的 Session 联系起来。

在下面的示例中，我们设置了 `session_id` 来演示如何同时与多个用户进行多轮对话。在生产环境中，`session_id` 是自动生成的。

<Note>
  注意：多用户、多 Session 目前仅支持 `Memory.v2`，它将在下一个版本中成为默认的内存实现。
</Note>

```python theme={null}
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.memory.v2 import Memory

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    # 多用户、多 Session 仅支持 Memory.v2
    memory=Memory(),
    add_history_to_messages=True,
    num_history_runs=3,
)

user_1_id = "user_101"
user_2_id = "user_102"

user_1_session_id = "session_101"
user_2_session_id = "session_102"

# 开始与 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,
)
# 继续与 user 1 的会话
agent.print_response("Now tell me a joke.", user_id=user_1_id, session_id=user_1_session_id)

# 开始与 user 2 的会话
agent.print_response("Tell me about quantum physics.", user_id=user_2_id, session_id=user_2_session_id)
# 继续与 user 2 的会话
agent.print_response("What is the speed of light?", user_id=user_2_id, session_id=user_2_session_id)

# 要求 Agent 对对话进行总结，这将使用之前消息中的历史记录
agent.print_response(
    "Give me a summary of our conversation.",
    user_id=user_1_id,
    session_id=user_1_session_id,
)
```

## 获取最近 N 个 Session 的消息

在某些场景下，您可能希望获取最近 N 个 Session 的消息，以提供上下文或对话的连续性。

以下是一个实现此目的的示例：

```python theme={null}
# 在运行脚本前删除临时数据库文件
import os

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.storage.sqlite import SqliteStorage

os.remove("tmp/data.db")

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    user_id="user_1",
    storage=SqliteStorage(table_name="agent_sessions_new", db_file="tmp/data.db"),
    search_previous_sessions_history=True,  # 允许搜索之前的 Session
    num_history_sessions=2,  # 搜索时仅包含最近的 2 个 Session，以避免上下文长度问题
    show_tool_calls=True,
)

session_1_id = "session_1_id"
session_2_id = "session_2_id"
session_3_id = "session_3_id"
session_4_id = "session_4_id"
session_5_id = "session_5_id"

agent.print_response("What is the capital of South Africa?", session_id=session_1_id)
agent.print_response("What is the capital of China?", session_id=session_2_id)
agent.print_response("What is the capital of France?", session_id=session_3_id)
agent.print_response("What is the capital of Japan?", session_id=session_4_id)
agent.print_response(
    "What did I discuss in my previous conversations?", session_id=session_5_id
)  # 这应该只包含最近的 2 个 Session
```

<Note>
  要启用从最近 N 个 Session 获取消息，您需要使用以下标志：

  * `search_previous_sessions_history`: 设置为 `True` 以允许搜索之前的 Session。
  * `num_history_sessions`: 指定要在搜索中包含的过去 Session 的数量。在此示例中，它设置为 `2`，只包含最近的 2 个 Session。
    建议目前将此数量保持为 2 或 3，因为较大的数量可能会填满模型的上下文长度，从而可能导致性能问题。

  这些标志有助于管理上下文长度，并确保对话中只包含相关的 Session 历史记录。
</Note>