Session Management

This section covers all CLI commands for managing agent sessions on Agent Cloud. Sessions represent individual instances of your agent running in rooms.

Session Commands

Control individual agent sessions - start agents in rooms and stop running sessions.

Start

Start an agent session in a room.

Usage

videosdk agent session start [OPTIONS]

Options

Option	Short	Description	Default
--version-id	-v	Version ID to use	Latest version
--room-id	-r	Room ID to join (creates new room if not provided)	Auto-created
--agent-id	-a	Agent ID	From videosdk.yaml

Example Output

$ videosdk agent session start -v ver123 -r room-abc

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Starting Session
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⠋ Starting Session...

✓ Session started successfully
  Room ID    room-abc

ℹ Useful commands:
  View logs: videosdk agent version logs
  Stop session: videosdk agent session stop -r room-abc

Examples

# Start with specific version and room
videosdk agent session start -v ver123 -r room-abc

# Start with specific version (creates new room)
videosdk agent session start -v ver123

# Start with latest version in existing room
videosdk agent session start -r room-abc

# Start with latest version (creates new room)
videosdk agent session start

Stop

Stop an agent session.

Usage

videosdk agent session stop [OPTIONS]

Options

Option	Short	Description	Required
--room-id	-r	Room ID of session	Yes (or --session-id)
--session-id	-s	Session ID to stop	Yes (or --room-id)

note

Either --room-id or --session-id must be provided.

Example Output

$ videosdk agent session stop -r room-abc

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Stopping Session
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⠋ Ending Session...

✓ Session ended successfully

Examples

# Stop by room ID
videosdk agent session stop -r room-abc

# Stop by session ID
videosdk agent session stop -s session-123

Sessions List

View and filter all sessions for your agent.

List

List all sessions for an agent.

Usage

videosdk agent sessions list [OPTIONS]

Options

Option	Short	Description	Default
--agent-id		Agent ID	From videosdk.yaml
--version-id	-v	Filter by Version ID	None
--room-id		Filter by Room ID	None
--session-id		Filter by Session ID	None
--page		Page number	1
--per-page		Items per page	10
--sort		Sort order: 1 (oldest first) or -1 (newest first)	-1

Example Output

$ videosdk agent sessions list

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Listing Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Agent ID        abc123xyz
  Deployment ID   dep-456

+------------+----------+---------------+---------+----------+
| Session ID | Room ID  | Deployment ID | Status  | Duration |
+------------+----------+---------------+---------+----------+
| sess-001   | room-abc | dep-456       | running | 5m 30s   |
| sess-002   | room-xyz | dep-456       | ended   | 12m 45s  |
| sess-003   | room-123 | dep-456       | ended   | 3m 15s   |
+------------+----------+---------------+---------+----------+

Examples

# List all sessions
videosdk agent sessions list

# List sessions for specific agent
videosdk agent sessions list --agent-id abc123

# Filter by version
videosdk agent sessions list --version-id ver123

# Filter by room
videosdk agent sessions list --room-id room-abc

# Paginated listing
videosdk agent sessions list --page 2 --per-page 20

# Sort oldest first
videosdk agent sessions list --sort 1

Quick Reference

Command	Description
videosdk agent session start	Start an agent in a room
videosdk agent session stop	Stop an agent session
videosdk agent sessions list	List all sessions

Workflow Example

Here's a typical workflow for managing agent sessions:

# 1. Start a session with your deployed version
videosdk agent session start -v ver123

# 2. Check running sessions
videosdk agent sessions list

# 3. View logs for debugging
videosdk agent logs -v ver123

# 4. Stop the session when done
videosdk agent session stop -r room-abc