Skip to main content

Agent Sessions

Agent Sessions track a single user's live chat with one agent, with idle/duration/concurrency policy. The agent runtime upserts a session each turn; use this resource to list, inspect, end, pause, resume, or transfer sessions.

Access it as client.sessions on a Strongly client, or the same path on AsyncStrongly with await. All methods exist on both with identical signatures.

Quick start​

from strongly import Strongly

client = Strongly()

# List (auto-paginates as you iterate)  # filters: state
for agent in client.sessions.list():
    print(agent.id)

# Retrieve one by id
item = client.sessions.retrieve("<id>")

Methods​

Core​

list​

list(agent_id: str, *, state: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> List[AgentSession]

List chat sessions for an agent.

The owner/admin sees every user's rows; a non-owner with read access sees only their own.

Args: agent_id: Agent (workflow) id. state: Filter, default active (live + idle + paused). Other values: live, idle, paused, ended, all. limit: Max rows to return. offset: Pagination offset.

Returns: A list of AgentSession.

retrieve​

retrieve(agent_id: str, session_id: str) -> AgentSession

Retrieve a single agent session by id.

Lifecycle & actions​

pause​

pause(agent_id: str, session_id: str) -> Dict[str, Any]

Pause an active session (resume with resume).

resume​

resume(agent_id: str, session_id: str) -> Dict[str, Any]

Resume a paused session.

Other​

end​

end(agent_id: str, session_id: str, *, reason: Optional[str] = None) -> Dict[str, Any]

End a session (idempotent).

Args: agent_id: Agent (workflow) id. session_id: Target session id. reason: Defaults to user_ended; admins ending another user's session are recorded as admin_ended automatically.

transfer​

transfer(agent_id: str, session_id: str, target_agent_id: str) -> Dict[str, Any]

Hand the session off to another agent.

Ends the source session with endedReason='transfer' and stamps transferredTo. The target agent gets its own upsert on the user's next turn there.

update_session_policy​

update_session_policy(agent_id: str, *, idle_timeout_seconds: int, max_session_duration_seconds: int, auto_archive_after_days: int, max_concurrent_sessions_per_user: Optional[int] = None, allow_per_session_model_override: bool = False) -> Dict[str, Any]

Write a session policy onto the agent's brain (owner/admin only).

max_concurrent_sessions_per_user=None means unlimited.

upsert_from_activity​

upsert_from_activity(agent_id: str, thread_id: str, *, transport: str = "text", model_override: Optional[str] = None, streaming_session_id: Optional[str] = None) -> AgentSession

Runtime activity touch; the agent worker calls this on every turn.

Idempotently upserts the session row, refreshes lastActivityAt, transitions idle -&gt; live, and enforces maxConcurrentSessionsPerUser on first touch.

Args: agent_id: Agent (workflow) id. thread_id: agent_threads._id this session represents. transport: text (default) or streaming. model_override: Optional per-session model id (only honored when the brain allows it). streaming_session_id: Streaming gateway session id, if any.

Returns: The active AgentSession.

Raises: RateLimitError: When the user is at the concurrent-session cap (429). APIError: 410 when the session exceeded maxSessionDurationSeconds.