Sessions API Reference¶

This page documents the SessionManager and SessionStore classes --- their methods, parameters, return types, and error behavior. Sessions enable multi-turn conversations between the buyer agent and seller agents, maintaining context across a sequence of messages.

Overview¶

The buyer agent uses two components for session management:

sequenceDiagram
    participant Buyer as Buyer Agent
    participant SM as SessionManager
    participant Store as SessionStore
    participant Seller as Seller Agent

    Buyer->>SM: get_or_create_session(seller_url)
    SM->>Store: Check for active session
    Store-->>SM: None (no active session)
    SM->>Seller: POST /sessions
    Seller-->>SM: {session_id, created_at, expires_at}
    SM->>Store: Persist SessionRecord
    SM-->>Buyer: session_id

    Buyer->>SM: send_message(seller_url, session_id, message)
    SM->>Seller: POST /sessions/{id}/messages
    Seller-->>SM: Response
    SM-->>Buyer: Seller response

    Buyer->>SM: close_session(seller_url, session_id)
    SM->>Seller: POST /sessions/{id}/close
    SM->>Store: Remove session record

SessionManager¶

The SessionManager is the primary interface for session operations.

Initialization¶

from ad_buyer.sessions import SessionManager

# Default store (~/.ad_buyer/sessions.json)
manager = SessionManager()

# Custom store path and timeout
manager = SessionManager(
    store_path="/path/to/sessions.json",
    timeout=60.0,
)

Constructor Parameters¶

Methods¶

create_session(seller_url, buyer_identity)¶

Establish a new session with a seller by posting to their /sessions endpoint.

Returns: str --- the session ID.

Seller endpoint: POST /sessions

session_id = await manager.create_session(
    seller_url="http://seller.example.com:8001",
    buyer_identity={
        "seat_id": "ttd-seat-123",
        "name": "Acme Media Buying",
        "agency_id": "omnicom-456",
    },
)

The manager persists the returned session record to the SessionStore automatically. Sessions follow a 7-day TTL by default.

get_or_create_session(seller_url, buyer_identity)¶

Check for an existing active session with the seller; create a new one if none exists.

Returns: str --- the session ID (existing or newly created).

session_id = await manager.get_or_create_session(
    seller_url="http://seller.example.com:8001",
    buyer_identity={"seat_id": "ttd-seat-123"},
)

send_message(seller_url, session_id, message, buyer_identity)¶

Send a message to the seller on an existing session.

Returns: Seller response (dict).

Seller endpoint: POST /sessions/{session_id}/messages

Automatic recovery: If the seller returns 404 (session expired), the manager transparently removes the stale session, creates a new one, and retries the message.

close_session(seller_url, session_id)¶

Close a session and remove it from the local store.

Returns: None.

Seller endpoint: POST /sessions/{session_id}/close

Close failures are logged but not raised --- local cleanup always occurs.

list_active_sessions()¶

Return all active (non-expired) sessions.

Returns: dict[str, str] --- mapping of seller URLs to session IDs.

SessionStore¶

The SessionStore is the persistence backend, storing session records as a JSON file on disk. It is used internally by SessionManager and can also be accessed directly for inspection or maintenance.

How It Works¶

• Sessions are keyed by seller URL --- one active session per seller
• The store file is created automatically if it does not exist
• Reads happen on initialization; writes happen on every save/remove
• Expired sessions are retained in the file but filtered out by get()

File Format¶

{
  "http://seller-a.example.com:8001": {
    "session_id": "sess-a1b2c3d4",
    "seller_url": "http://seller-a.example.com:8001",
    "created_at": "2026-03-10T14:00:00Z",
    "expires_at": "2026-03-17T14:00:00Z"
  }
}

Direct Access¶

from ad_buyer.sessions import SessionStore, SessionRecord

store = SessionStore("/path/to/sessions.json")

# Look up a specific seller's session
record = store.get("http://seller.example.com:8001")
if record:
    print(f"Session: {record.session_id}")
    print(f"Expires: {record.expires_at}")
    print(f"Expired? {record.is_expired()}")

# List all sessions (including expired)
all_sessions = store.list_sessions()

# Clean up expired sessions
removed = store.cleanup_expired()
print(f"Removed {removed} expired sessions")

SessionRecord¶

Each session is stored as a SessionRecord dataclass:

Key methods:

Session Lifecycle¶

stateDiagram-v2
    [*] --> Created: POST /sessions
    Created --> Active: Session in use
    Active --> Active: Send messages
    Active --> Expired: TTL exceeded (7 days)
    Active --> Closed: POST /sessions/{id}/close
    Expired --> Recreated: Auto-recovery on next message
    Recreated --> Active
    Closed --> [*]
    Expired --> [*]: Manual cleanup

Expiry Handling¶

Sessions expire after 7 days (or the TTL specified by the seller). Expiry is handled at two levels:

Error Handling¶

The SessionManager raises RuntimeError on failures:

try:
    session_id = await manager.create_session(seller_url)
except RuntimeError as e:
    print(f"Session creation failed: {e}")

try:
    response = await manager.send_message(
        seller_url, session_id, {"type": "inquiry", "content": "Hello"},
    )
except RuntimeError as e:
    print(f"Message failed: {e}")

Related¶

• Session Management Guide --- Practical patterns, negotiation flows, multi-seller strategies, and best practices
• Seller Sessions API --- Seller-side session endpoints (POST /sessions, GET /sessions, etc.)
• Authentication --- Buyer identity setup for session creation
• Media Kit Discovery --- Browse seller inventory before starting a session
• Bookings --- Campaign booking workflow