> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentops.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> An in-depth exploration of the foundational elements and operational dynamics of AgentOps, highlighting its architecture and constituent components.

## The AgentOps SDK Client

### Principles

The AgentOps SDK works to provide as much functionality with as little developer implementation as possible. We accomplish this with a few principles.

* Auto-Instrumenting
  * After calling `agentops.init()` we automatically look for installed LLM providers and auto-instrument their calls. This allows us to capture calls between your code and the provider to collect data for your dashboard.
* Decorators
  * With [Decorators](/v1/concepts/decorators), the SDK can add tracing to your existing functions and classes to create hierarchical spans for monitoring and analysis.
* Process monitoring
  * The SDK establishes a couple process monitors that allow us to understand the state and health of your agents.

### Sessions

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.

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.

### Session Management

AgentOps can exist in one of two states:

<CardGroup cols={2}>
  <Card title="Single Session" icon="hand-point-up" iconType="solid" color="#2bd600">
    * • Only one session exists at a time. All agent usage is synchronous.
    * • Use cases: Scripting, development, local machine use (browser extensions, web client, etc)
  </Card>

  <Card title="Concurrent Traces" icon="hand-peace" iconType="solid" color="#2bd600">
    * • REST server
    * • Asynchronous agents
    * • Multiple concurrent workflows
  </Card>
</CardGroup>

AgentOps supports both single and multiple concurrent traces (sessions) seamlessly. You can use either the modern trace-based API or the legacy session functions for backwards compatibility.

The modern approach uses `start_trace()` and `end_trace()` with automatic instrumentation, while legacy session functions remain available. Multiple concurrent traces work without any special mode switching or restrictions.

<CodeGroup>
  ```python single trace theme={null}
  import agentops
  agentops.init()
  trace_context = agentops.start_trace("my_workflow")
  # Your agent logic here
  agentops.end_trace(trace_context, "Success")
  ```

  ```python concurrent traces theme={null}
  import agentops
  agentops.init(auto_start_session=False)
  trace_1 = agentops.start_trace("workflow_1")
  trace_2 = agentops.start_trace("workflow_2")

  # Work with both traces concurrently
  agentops.end_trace(trace_1, "Success")
  agentops.end_trace(trace_2, "Success")
  ```

  ```python using decorators theme={null}
  import agentops

  @agentops.trace
  def my_workflow():
      # Your agent logic here
      pass

  my_workflow()
  ```
</CodeGroup>

For more documentation on using multiple concurrent traces, please see [Concurrent Traces](/v1/usage/multiple-sessions) and [FastAPI Example](/v1/examples/fastapi).

### LLMs, Tools, and Operations (Spans)

Within AgentOps, **LLMs**, **Tools**, and **Operations** are categorized as **Spans**, executed by Agents. Agents primarily initiate LLM calls, potentially leading to API/Tool calls, while Operations encompass any other significant procedures, such as executing functions, taking screenshots, etc.

All spans share the following characteristics:

* **ID**: A unique identifier.
* **Session ID**: The session to which the span belongs.
* **Agent ID**: Identifies the agent responsible for the span.
* **Parameters**: The inputs provided to the span.
* **Returns**: The outputs or results of the span.
* **Starting Timestamp**: The time at which the span began.
* **Ending Timestamp**: The time at which the span concluded.

Additionally, each span type has its own specific properties:

**LLMs**:

* **Model**: The specific LLM model used.
* **Prompt Messages**: The initial prompts sent to the model.
* **Completion Messages**: The responses received from the model.
* **Prompt Tokens**: The number of tokens used in the prompts.
* **Completion Tokens**: The number of tokens in the model's responses.
* **Cost**: The cost incurred by the span.
* **Thread ID**: Associates the span with a specific thread for execution tracking.

**Tools**:

* **Logs**: Records of the tool's operation, including any outputs and errors.

**Operations**:

* **Operation Type**: Specifies the nature of the operation (e.g., function execution, screenshot).
* **Logs**: Detailed records of the operation's execution, including parameters and outcomes.

### Errors

Errors are an inevitable aspect of operational processes. AgentOps comprehensively documents errors related to Spans, providing a wealth of information for troubleshooting.

* **Error Type**: The span type (LLM, Tool, or Operation) the error is associated with.
* **Error Code**: A specific code identifying the error.
* **Details**: A detailed description of the error.
* **Logs/Stack Trace**: Logs or stack traces capturing the error context.
* **Timestamp**: The exact time the error occurred.

### Agents

An **Agent** is an autonomous entity with its own memory and capabilities. In multi-agent frameworks, agents act as team members, each with specialized skills and responsibilities, such as project management, software development, and quality assurance, coordinating and communicating to achieve collective goals.

Agents are characterized by:

* **ID**: A unique identifier for the agent.
* **Session ID**: Links the agent to its associated session.
* **Name**: A user-defined name for easy identification of the agent.

Optionally, agents may also have:

* **Logs**: Textual records of the tasks performed by the agent.

**Note**: For spans not specifically assigned to an agent, AgentOps will automatically create and assign a default agent.

### Threads

*Details coming soon.*

<script type="module" src="/scripts/github_stars.js" />

<script type="module" src="/scripts/adjust_api_dynamically.js" />