A Session encapsulates a singular execution instance of your workflow, bringing together all agents, LLMs, actions, etc., under one umbrella. Consequently, it is imperative for each event to be associated with a session. The AgentOps dashboard provides detailed insights at the session level, including costs, token counts, errors, and more.

There must be an active session in order to use AgentOps.

Only one session can be active a single time.



Sessions possess the following attributes:

  • ID: A unique identifier for the session.
  • Project ID: Identifies the project associated with the session, determined by the API Key used.
  • Starting Timestamp: Marks the beginning of the session.
  • Ending Timestamp: Indicates when the session concludes.
  • End State: Signifies the success or failure of the session.

Optionally, sessions may include:

  • End State Reason: Explains why the session ended, whether due to an error or a user-triggered interrupt (SIGINT).
  • Tags: Tags allow for the categorization and later retrieval of sessions.
  • Host Environment: Automatically gathers basic information about the system on which the session ran.
  • Video: If applicable, an optional video recording of the session.

Starting a Session

When you call agentops.init(), a session is automatically started. Calling agentops.init(auto_start_session=False) will initialize the AgentOps SDK but not start a session.

To start a session later, call agentops.start_session() (reference)

Ending a Session

If a process ends without any call to agentops, it will show in the dashboard as Indeterminate. To end with a state, call agentops.end_session() (reference)

Inherited Sessions

When working with multiple agents running in different processes, it’s possible to initialize AgentOps or start a session with an existing session_id.

agentops.init(inherited_session_id=<id>) agentops.start_session(inherited_session_id=<id>)

You can retrieve the current session_id by assigning the returned value from init() or start_session()

import agentops
session_id = agentops.init()
# pass session_id to the other process

# -- other process --
session_id = retrieve_session_id()

Both processes will now contribute data to the same session.

The AgentOps SDK Client

More info for the curious

Under the hood, agentops.init() sets up a Client object with various configuration options like your API key, worker thread options for when to send out batches of events, etc. Whenever you start a new session, these configuration options will automatically be applied. You can also apply different configuration options when you start a new session by passing in a Configuration object.