AgentSessionManager.Core.Session (AgentSessionManager v0.1.1)

Represents an AI agent session.

A session is a logical container for a series of runs (interactions) with an AI agent. It maintains state, context, and metadata across multiple runs.

Session Lifecycle

Sessions follow this state machine:

pending -> active -> completed
                 -> failed
                 -> cancelled
         -> paused -> active (resumed)

Fields

id - Unique session identifier
agent_id - Identifier for the agent type/configuration
status - Current session status (:pending, :active, :paused, :completed, :failed, :cancelled)
parent_session_id - Optional parent session for hierarchical sessions
metadata - Arbitrary metadata associated with the session
context - Shared context data (system prompts, configuration)
tags - List of tags for categorization
created_at - Session creation timestamp
updated_at - Last update timestamp

Usage

# Create a new session
{:ok, session} = Session.new(%{agent_id: "my-agent"})

# Update status
{:ok, active} = Session.update_status(session, :active)

# Serialize for storage
map = Session.to_map(session)

Summary

Types

status()

t()

Functions

from_map(map)

Reconstructs a session from a map.

new(attrs)

Creates a new session with the given attributes.

to_map(session)

Converts a session to a map suitable for JSON serialization.

update_status(session, status)

Updates the session status.

Types

status()

@type status() :: :pending | :active | :paused | :completed | :failed | :cancelled

t()

@type t() :: %AgentSessionManager.Core.Session{
  agent_id: String.t() | nil,
  context: map(),
  created_at: DateTime.t() | nil,
  id: String.t() | nil,
  metadata: map(),
  parent_session_id: String.t() | nil,
  status: status(),
  tags: [String.t()],
  updated_at: DateTime.t() | nil
}

Functions

from_map(map)

@spec from_map(map()) :: {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}

Reconstructs a session from a map.

new(attrs)

@spec new(map()) :: {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}

Creates a new session with the given attributes.

Required

:agent_id - The agent identifier

Optional

:id - Custom ID (auto-generated if not provided)
:parent_session_id - Parent session for hierarchical sessions
:metadata - Arbitrary metadata map
:context - Shared context data
:tags - List of string tags

Examples

iex> Session.new(%{agent_id: "my-agent"})
{:ok, %Session{agent_id: "my-agent", status: :pending, ...}}

iex> Session.new(%{})
{:error, %Error{code: :validation_error, ...}}

to_map(session)

@spec to_map(t()) :: map()

Converts a session to a map suitable for JSON serialization.

update_status(session, status)

@spec update_status(t(), status()) ::
  {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}

Updates the session status.

Valid statuses

:pending - Session created but not started
:active - Session is currently active
:paused - Session is paused
:completed - Session completed successfully
:failed - Session failed
:cancelled - Session was cancelled

Examples

iex> {:ok, session} = Session.new(%{agent_id: "agent"})
iex> Session.update_status(session, :active)
{:ok, %Session{status: :active, ...}}

iex> Session.update_status(session, :invalid)
{:error, %Error{code: :invalid_status}}