Rag.Agent.Session (rag v0.3.4)

View Source

Session management for agent conversations.

A session maintains the conversation history, context, and state for an agent interaction. It handles:

  • Message history (user, assistant, tool results)
  • Context storage (persistent data across turns)
  • Token estimation for context window management

Usage

session = Session.new()
  |> Session.add_message(:user, "Hello!")
  |> Session.add_message(:assistant, "Hi there!")
  |> Session.set_context(:repo, "my_app")

# Get messages for LLM
messages = Session.to_llm_messages(session)

Summary

Types

message()
role()
t()

Functions

add_message(session, role, content)

Adds a message to the session history.

add_tool_result(session, tool_name, result)

Adds a tool result to the session history.

clear_messages(session)

Clears all messages but keeps context and metadata.

context(session)

Returns the session context.

get_context(session, key, default \\ nil)

Gets a context value.

last_messages(session, n)

Returns the last n messages.

merge_context(session, new_context)

Merges values into the context.

message_count(session)

Returns the number of messages in the session.

messages(session)

Returns all messages in the session.

new(opts \\ [])

Creates a new session.

set_context(session, key, value)

Sets a context value.

to_llm_messages(session)

Formats messages for LLM API consumption.

token_estimate(session)

Estimates the token count for the session.

Types

message()

@type message() :: %{
  role: role(),
  content: String.t(),
  timestamp: integer(),
  tool_name: String.t() | nil,
  error: term() | nil
}

role()

@type role() :: :user | :assistant | :system | :tool

t()

@type t() :: %Rag.Agent.Session{
  context: map(),
  created_at: integer(),
  id: String.t(),
  messages: [message()],
  metadata: map()
}

Functions

add_message(session, role, content)

@spec add_message(t(), role(), String.t()) :: t()

Adds a message to the session history.

Parameters

  • session - The session struct
  • role - Message role (:user, :assistant, :system)
  • content - Message content

Examples

iex> session |> Session.add_message(:user, "Hello!")
%Session{messages: [%{role: :user, content: "Hello!", ...}]}

add_tool_result(session, tool_name, result)

@spec add_tool_result(t(), String.t(), {:ok, term()} | {:error, term()}) :: t()

Adds a tool result to the session history.

Parameters

  • session - The session struct
  • tool_name - Name of the tool that was called
  • result - Tool result as {:ok, content} or {:error, reason}

clear_messages(session)

@spec clear_messages(t()) :: t()

Clears all messages but keeps context and metadata.

context(session)

@spec context(t()) :: map()

Returns the session context.

get_context(session, key, default \\ nil)

@spec get_context(t(), atom(), term()) :: term()

Gets a context value.

Examples

iex> Session.get_context(session, :key)
"value"

iex> Session.get_context(session, :missing, "default")
"default"

last_messages(session, n)

@spec last_messages(t(), non_neg_integer()) :: [message()]

Returns the last n messages.

Examples

iex> Session.last_messages(session, 5)
[%{role: :user, ...}, %{role: :assistant, ...}]

merge_context(session, new_context)

@spec merge_context(t(), map()) :: t()

Merges values into the context.

Examples

iex> session |> Session.merge_context(%{a: 1, b: 2})
%Session{context: %{a: 1, b: 2}}

message_count(session)

@spec message_count(t()) :: non_neg_integer()

Returns the number of messages in the session.

messages(session)

@spec messages(t()) :: [message()]

Returns all messages in the session.

new(opts \\ [])

@spec new(keyword()) :: t()

Creates a new session.

Options

  • :id - Custom session ID (generates UUID if not provided)
  • :metadata - Initial metadata map

Examples

iex> Session.new()
%Session{id: "...", messages: [], context: %{}}

iex> Session.new(id: "my-session", metadata: %{user: "alice"})
%Session{id: "my-session", metadata: %{user: "alice"}}

set_context(session, key, value)

@spec set_context(t(), atom(), term()) :: t()

Sets a context value.

Examples

iex> session |> Session.set_context(:key, "value")
%Session{context: %{key: "value"}}

to_llm_messages(session)

@spec to_llm_messages(t()) :: [map()]

Formats messages for LLM API consumption.

Returns a list of simplified message maps suitable for sending to LLM providers.

Examples

iex> Session.to_llm_messages(session)
[%{role: :user, content: "Hello"}, %{role: :assistant, content: "Hi!"}]

token_estimate(session)

@spec token_estimate(t()) :: non_neg_integer()

Estimates the token count for the session.

Uses a rough approximation based on character count.