Sessions

Session management for multi-turn conversations.

class agent.session.Session(agent, session_id=None, system=None, messages=None)[source]

Bases: object

A session for multi-turn conversation.

Sessions manage message history automatically, allowing natural conversational interactions without manual message management.

Example

```python agent = Agent(provider=”openai”, model=”gpt-4o”) session = agent.session()

session.run(“My name is Alice”) response = session.run(“What’s my name?”) print(response.text) # “Your name is Alice” ```

Parameters:
property session_id: str

Get the session ID.

property system: str | None

Get the system prompt.

property messages: list[Message]

Get the message history (read-only copy).

run(input, *, temperature=None, max_tokens=None, metadata=None)[source]

Send a message and get a response.

The input and response are automatically added to history.

Parameters:

  • input (str) – User message

  • temperature (float | None) – Sampling temperature (overrides default)

  • max_tokens (int | None) – Max tokens (overrides default)

  • metadata (dict[str, Any] | None) – Request metadata

Return type:

AgentResponse

Returns:

AgentResponse with the model’s response

async run_async(input, *, temperature=None, max_tokens=None, metadata=None)[source]

Send a message and get a response asynchronously.

Parameters:

  • input (str) – User message

  • temperature (float | None) – Sampling temperature (overrides default)

  • max_tokens (int | None) – Max tokens (overrides default)

  • metadata (dict[str, Any] | None) – Request metadata

Return type:

AgentResponse

Returns:

AgentResponse with the model’s response

stream(input, *, temperature=None, max_tokens=None, metadata=None)[source]

Send a message and stream the response.

Note: History is updated after stream is consumed.

Parameters:

  • input (str) – User message

  • temperature (float | None) – Sampling temperature

  • max_tokens (int | None) – Max tokens

  • metadata (dict[str, Any] | None) – Request metadata

Return type:

StreamResponse

Returns:

StreamResponse iterator

async stream_async(input, *, temperature=None, max_tokens=None, metadata=None)[source]

Send a message and stream the response asynchronously.

Parameters:

  • input (str) – User message

  • temperature (float | None) – Sampling temperature

  • max_tokens (int | None) – Max tokens

  • metadata (dict[str, Any] | None) – Request metadata

Return type:

AsyncStreamResponse

Returns:

AsyncStreamResponse iterator

json(input, *, schema, temperature=None, max_tokens=None, metadata=None)[source]

Send a message expecting structured JSON output.

Parameters:

  • input (str) – User message

  • schema (type[BaseModel] | dict[str, Any]) – Pydantic model or JSON schema

  • temperature (float | None) – Sampling temperature

  • max_tokens (int | None) – Max tokens

  • metadata (dict[str, Any] | None) – Request metadata

Return type:

AgentResponse

Returns:

AgentResponse with parsed output

async json_async(input, *, schema, temperature=None, max_tokens=None, metadata=None)[source]

Send a message expecting structured JSON output asynchronously.

Parameters:

  • input (str) – User message

  • schema (type[BaseModel] | dict[str, Any]) – Pydantic model or JSON schema

  • temperature (float | None) – Sampling temperature

  • max_tokens (int | None) – Max tokens

  • metadata (dict[str, Any] | None) – Request metadata

Return type:

AgentResponse

Returns:

AgentResponse with parsed output

history()[source]

Get the full message history.

Return type:

list[Message]

clear()[source]

Clear the message history.

Return type:

None

fork(session_id=None)[source]

Create a new session with a copy of the current history.

Parameters:

session_id (str | None) – Optional ID for the new session

Return type:

Session

Returns:

New Session instance

add_message(message)[source]

Manually add a message to history.

Parameters:

message (Message) – Message to add

Return type:

None

to_dict()[source]

Serialize session state to a dictionary.

Return type:

dict[str, Any]

classmethod from_dict(data, agent)[source]

Deserialize session state from a dictionary.

Parameters:

  • data (dict[str, Any]) – Serialized session data

  • agent (Agent) – Agent to use for this session

Return type:

Session

Returns:

Session instance

Stores

Base session store interface.

class agent.stores.base.SessionStore[source]

Bases: ABC

Abstract base class for session storage.

Session stores persist conversation history across sessions.

abstractmethod save(session_id, data)[source]

Save session data.

Parameters:

  • session_id (str) – Unique session identifier

  • data (dict[str, Any]) – Session data to save

Return type:

None

abstractmethod load(session_id)[source]

Load session data.

Parameters:

session_id (str) – Unique session identifier

Return type:

dict[str, Any] | None

Returns:

Session data if found, None otherwise

abstractmethod delete(session_id)[source]

Delete session data.

Parameters:

session_id (str) – Unique session identifier

Return type:

bool

Returns:

True if deleted, False if not found

abstractmethod list_sessions()[source]

List all session IDs.

Return type:

list[str]

Returns:

List of session identifiers

exists(session_id)[source]

Check if a session exists.

Parameters:

session_id (str) – Unique session identifier

Return type:

bool

Returns:

True if session exists

In-memory session store.

class agent.stores.memory.InMemoryStore[source]

Bases: SessionStore

In-memory session store.

Stores sessions in memory. Data is lost when the process ends. Useful for development and testing.

Example

```python store = InMemoryStore()

# Save session store.save(“session-123”, {“messages”: […], “system”: “…”})

# Load session data = store.load(“session-123”) ```

save(session_id, data)[source]

Save session data.

Parameters:
Return type:

None

load(session_id)[source]

Load session data.

Parameters:

session_id (str)

Return type:

dict[str, Any] | None

delete(session_id)[source]

Delete session data.

Parameters:

session_id (str)

Return type:

bool

list_sessions()[source]

List all session IDs.

Return type:

list[str]

clear()[source]

Clear all sessions.

Return type:

None

SQLite session store.

class agent.stores.sqlite.SQLiteStore(db_path='agent_sessions.db')[source]

Bases: SessionStore

SQLite-based session store.

Persists sessions to a SQLite database file.

Example

```python store = SQLiteStore(“sessions.db”)

# Save session store.save(“session-123”, {“messages”: […], “system”: “…”})

# Load session data = store.load(“session-123”) ```

Parameters:

db_path (str | Path)

save(session_id, data)[source]

Save session data.

Parameters:
Return type:

None

load(session_id)[source]

Load session data.

Parameters:

session_id (str)

Return type:

dict[str, Any] | None

delete(session_id)[source]

Delete session data.

Parameters:

session_id (str)

Return type:

bool

list_sessions()[source]

List all session IDs.

Return type:

list[str]

clear()[source]

Clear all sessions.

Return type:

None

vacuum()[source]

Reclaim disk space after deletions.

Return type:

None