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: str | None = None, limit: int | None = None) -> SyncPaginator[AgentSession]

List chat sessions for an agent, a page at a time as you iterate.

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

Parameters

  • agent_id (str): Agent (workflow) id.
  • state (str | None, optional): Filter, default active (live + idle + paused). Other values: live, idle, paused, ended, all.
  • limit (int | None, optional): The most sessions to yield.

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) -> AgentSession

Pause an active session (resume with resume).

resume​

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

Resume a paused session.

Other​

end​

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

End a session (idempotent). The conversation is kept.

The recorded reason is user_ended when the session's own user ends it and admin_ended when the agent's manager ends someone else's.

Parameters

  • agent_id (str): Agent (workflow) id.
  • session_id (str): Target session id.

transfer​

transfer(agent_id: str, session_id: str, target_agent_id: str) -> AgentSession

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: int | None = None, allow_per_session_model_override: bool = False) -> dict[str, Any]

Write the agent's session policy (owner/admin only); returns the agent's config.

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: str | None = None, streaming_session_id: str | None = None) -> AgentSession

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

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

Parameters

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

Returns

  • AgentSession: The active AgentSession.

Raises

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