Fix documentation issues: deprecated session references, multi-turn guidance, ADK clarifications

docs/v1/concepts/decorators.mdx

@@ -13,7 +13,11 @@ description: "Seemingly magic tools that can be added to functions and classes f
 
 AgentOps provides a set of decorators that allow you to easily instrument your code for tracing and monitoring AI agent workflows. These decorators create spans (units of work) that are organized hierarchically to track different types of operations.
 
-## `@session`
+## `@session` (Deprecated)
+
+<Warning>
+The `@session` decorator is deprecated in favor of `@trace`. Please use `@trace` for new implementations. See the [v2 documentation](/v2/concepts/decorators) for current best practices.
+</Warning>
 
 The `@session` decorator creates a session span, which serves as the root for all other spans. No spans can exist without a session at the top.
 
@@ -148,4 +152,4 @@ The decorators provide several additional features:
 4. **Custom Attributes**: You can add custom attributes to spans using the decorator parameters.
 
 <script type="module" src="/scripts/github_stars.js"></script>
-<script type="module" src="/scripts/adjust_api_dynamically.js"></script>
+<script type="module" src="/scripts/adjust_api_dynamically.js"></script>

docs/v1/concepts/sessions.mdx

@@ -1,8 +1,12 @@
 ---
-title: Sessions
-description: Detailed breakdown of initializing AgentOps and managing sessions.
+title: Sessions (Deprecated)
+description: Detailed breakdown of initializing AgentOps and managing sessions - DEPRECATED: Use Traces instead
 ---
 
+<Warning>
+Sessions are deprecated in favor of Traces. Please refer to the [v2 Traces documentation](/v2/concepts/traces) for current best practices. The session concept has been replaced with the more flexible trace system.
+</Warning>
+
 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.

docs/v2/concepts/decorators.mdx

@@ -8,7 +8,7 @@ AgentOps provides the following decorators:
 
 | Decorator | Purpose | Creates |
 |-----------|---------|---------|
-| `@session` | Track an entire user interaction | SESSION span |
+| `@trace` | Track an entire user interaction | TRACE span |
 | `@agent` | Track agent classes and their lifecycle | AGENT span |
 | `@operation` | Track discrete operations performed by agents | OPERATION span |
 | `@workflow` | Track a sequence of operations | WORKFLOW span |
@@ -21,7 +21,7 @@ AgentOps provides the following decorators:
 The decorators create spans that form a hierarchy:
 
 ```
-SESSION
+TRACE
   ├── AGENT
   │     ├── OPERATION or TASK
   │     │     ├── LLM
@@ -34,18 +34,18 @@ SESSION
 
 ## Using Decorators
 
-### @session
+### @trace
 
-The `@session` decorator tracks an entire user interaction from start to finish:
+The `@trace` decorator tracks an entire user interaction from start to finish:
 
 ```python
-from agentops.sdk.decorators import session
+from agentops.sdk.decorators import trace
 import agentops
 
 # Initialize AgentOps
 agentops.init(api_key="YOUR_API_KEY")
 
-@session
+@trace
 def answer_question(question):
     # Create and use agents
     weather_agent = WeatherAgent()
@@ -55,7 +55,7 @@ def answer_question(question):
     return result
 ```
 
-Each `@session` function call creates a new session span that contains all the agents, operations, and workflows used during that interaction.
+Each `@trace` function call creates a new trace span that contains all the agents, operations, and workflows used during that interaction.
 
 ### @agent
 
@@ -287,13 +287,13 @@ Common attributes include:
 Here's a complete example using all the decorators together:
 
 ```python
-from agentops.sdk.decorators import session, agent, operation, workflow, task
+from agentops.sdk.decorators import trace, agent, operation, workflow, task
 import agentops
 
 # Initialize AgentOps
 agentops.init(api_key="YOUR_API_KEY")
 
-@session
+@trace
 def assist_user(query):
     # Create the main assistant
     assistant = Assistant()
@@ -350,7 +350,7 @@ assist_user("What is the capital of France?")
 ```
 
 In this example:
-1. The `@session` decorator wraps the entire interaction
+1. The `@trace` decorator wraps the entire interaction
 2. The `@agent` decorator defines multiple agent classes
 3. The `@workflow` decorator creates a workflow that coordinates agents
 4. The `@operation` and `@task` decorators track individual operations
@@ -360,7 +360,7 @@ Note that LLM and TOOL spans are automatically created when you use compatible L
 
 ## Best Practices
 
-- **Use @session for top-level functions** that represent complete user interactions
+- **Use @trace for top-level functions** that represent complete user interactions
 - **Apply @agent to classes** that represent distinct components of your system
 - **Use @operation for significant functions** that represent complete units of work
 - **Use @task for smaller functions** that are part of larger operations
@@ -382,4 +382,4 @@ This visualization helps you understand the flow and performance of your agent s
 
 <script type="module" src="/scripts/github_stars.js"></script>
 <script type="module" src="/scripts/scroll-img-fadein-animation.js"></script>
-<script type="module" src="/scripts/button_heartbeat_animation.js"></script>
+<script type="module" src="/scripts/button_heartbeat_animation.js"></script>

docs/v2/concepts/spans.mdx

@@ -85,9 +85,9 @@ There are several ways to create spans in AgentOps:
 The recommended way to create spans is using decorators:
 
 ```python
-from agentops.sdk.decorators import agent, operation, session, workflow, task
+from agentops.sdk.decorators import agent, operation, trace, workflow, task
 
-@session
+@trace
 def my_workflow():
     agent_instance = MyAgent()
     return agent_instance.perform_task()
@@ -140,4 +140,4 @@ All recorded spans are visible in the AgentOps dashboard:
 
 <script type="module" src="/scripts/github_stars.js"></script>
 <script type="module" src="/scripts/scroll-img-fadein-animation.js"></script>
-<script type="module" src="/scripts/button_heartbeat_animation.js"></script>
+<script type="module" src="/scripts/button_heartbeat_animation.js"></script>

docs/v2/concepts/traces.mdx

@@ -270,6 +270,125 @@ The AgentOps dashboard provides several views for analyzing your traces:
 - **Leverage context managers** for automatic trace lifecycle management
 - **Set appropriate end states** to track success/failure rates
 
+## Multi-Turn Conversations
+
+For applications that handle multiple user interactions within a single logical session (like chatbots or conversational agents), you can group multiple requests and responses into a single trace using manual trace control.
+
+### Basic Multi-Turn Pattern
+
+```python
+import agentops
+from agentops.sdk.decorators import operation
+
+# Initialize without auto-starting a trace
+agentops.init("your-api-key", auto_start_session=False)
+
+# Start a trace for the entire conversation
+conversation_trace = agentops.start_trace(
+    "customer_conversation", 
+    tags=["chatbot", "customer-service"]
+)
+
+@operation
+def process_user_message(message, conversation_context):
+    # Process individual message within the conversation trace
+    response = generate_response(message, conversation_context)
+    return response
+
+# Simulate multiple turns in conversation
+conversation_context = {}
+messages = [
+    "Hello, I need help with my order",
+    "My order number is 12345", 
+    "When will it be delivered?"
+]
+
+try:
+    for message in messages:
+        response = process_user_message(message, conversation_context)
+        conversation_context['last_response'] = response
+        print(f"User: {message}")
+        print(f"Bot: {response}")
+
+    agentops.end_trace(conversation_trace, "Success")
+except Exception as e:
+    agentops.end_trace(conversation_trace, "Error")
+```
+
+### Advanced Multi-Turn with Metadata Updates
+
+You can track conversation progress and context using trace metadata:
+
+```python
+import agentops
+
+agentops.init("your-api-key", auto_start_session=False)
+
+def handle_conversation(user_id, conversation_id):
+    # Start trace for entire conversation
+    trace = agentops.start_trace(
+        f"conversation_{conversation_id}",
+        tags=["multi-turn", "customer-service", f"user_{user_id}"]
+    )
+
+    turn_count = 0
+
+    try:
+        while True:  # Conversation loop
+            user_input = input("User: ")
+            if user_input.lower() in ['quit', 'exit', 'bye']:
+                break
+
+            turn_count += 1
+
+            # Update trace metadata with conversation progress
+            agentops.update_trace_metadata({
+                "conversation_turn": turn_count,
+                "conversation_stage": "active",
+                "user_id": user_id,
+                "last_user_input": user_input[:50]  # Truncated for privacy
+            })
+
+            # Process the message (your agent logic here)
+            response = process_message(user_input)
+            print(f"Bot: {response}")
+
+            # Update metadata with response info
+            agentops.update_trace_metadata({
+                "last_response_length": len(response),
+                "total_turns": turn_count
+            })
+
+        # Final metadata update
+        agentops.update_trace_metadata({
+            "conversation_stage": "completed",
+            "completion_reason": "user_ended",
+            "total_turns": turn_count
+        })
+
+        agentops.end_trace(trace, "Success")
+
+    except Exception as e:
+        agentops.update_trace_metadata({
+            "conversation_stage": "error",
+            "error_turn": turn_count,
+            "error_message": str(e)
+        })
+        agentops.end_trace(trace, "Error")
+
+# Example usage
+handle_conversation("user_123", "conv_456")
+```
+
+### Best Practices for Multi-Turn Conversations
+
+- **Use a single trace per conversation**: Group all related turns under one trace for better analysis
+- **Update metadata progressively**: Track conversation state, turn count, and context changes
+- **Use meaningful trace names**: Include conversation or session identifiers
+- **Tag appropriately**: Use tags to categorize conversation types, user segments, etc.
+- **Handle errors gracefully**: Ensure traces are properly ended even if conversations are interrupted
+- **Consider conversation boundaries**: Start new traces for logically separate conversations
+
 <script type="module" src="/scripts/github_stars.js"></script>
 <script type="module" src="/scripts/scroll-img-fadein-animation.js"></script>
 <script type="module" src="/scripts/button_heartbeat_animation.js"></script>

docs/v2/examples/google_adk.mdx

@@ -279,7 +279,34 @@ except Exception as e:
 ```
 
 
+## Preventing Duplicate Traces
+
+AgentOps automatically handles ADK integration to prevent duplicate telemetry. The AgentOps ADK instrumentor:
+
+1. **Disables ADK's built-in telemetry** to prevent duplicate spans
+2. **Creates AgentOps spans** that mirror ADK's telemetry structure  
+3. **Properly extracts LLM messages and tool calls** for the AgentOps dashboard
+
+If you're seeing duplicate traces, ensure you're:
+- Using `auto_start_session=False` when manually managing traces with ADK
+- Not manually creating additional telemetry alongside ADK's automatic instrumentation
+- Using the latest version of both AgentOps and Google ADK
+
+### Troubleshooting Duplicate Traces
+
+```python
+# ✅ Correct: Let AgentOps handle ADK instrumentation
+agentops.init(AGENTOPS_API_KEY, auto_start_session=False)
+trace = agentops.start_trace("adk-workflow")
+# Your ADK code here - AgentOps will automatically capture spans
+
+# ❌ Incorrect: Don't manually create spans for ADK operations
+# This can cause duplicates
+```
+
+The ADK instrumentor in AgentOps specifically prevents duplicate spans by patching ADK's telemetry system. If you encounter issues, check that you're not mixing manual span creation with ADK's automatic instrumentation.
+
 <script type="module" src="/scripts/github_stars.js"></script>
 <script type="module" src="/scripts/scroll-img-fadein-animation.js"></script>
 <script type="module" src="/scripts/button_heartbeat_animation.js"></script>
-<script type="module" src="/scripts/adjust_api_dynamically.js"></script>
+<script type="module" src="/scripts/adjust_api_dynamically.js"></script>

docs/v2/quickstart.mdx

@@ -76,6 +76,49 @@ After adding the two lines and ensuring your API key is set up:
 3.  Visit your [AgentOps Dashboard](https://app.agentops.ai/traces) to observe your agent's operations!
 
 
+## From Simple to Advanced: Customizing Your AgentOps Integration
+
+The two-line setup gets you started quickly, but AgentOps offers powerful customization options as your needs grow:
+
+**Level 1: Basic Setup (2 lines)**
+```python
+import agentops
+agentops.init("your-api-key")  # Automatic instrumentation
+```
+
+**Level 2: Custom Configuration**
+```python
+import agentops
+agentops.init(
+    "your-api-key",
+    default_tags=["production", "v2.1"],
+    auto_start_session=False,  # Manual trace control
+    max_wait_time=10000
+)
+```
+
+**Level 3: Manual Trace Management**
+```python
+import agentops
+agentops.init("your-api-key", auto_start_session=False)
+
+trace = agentops.start_trace("custom-workflow", tags=["user-123"])
+# Your code here
+agentops.end_trace(trace, "Success")
+```
+
+**Level 4: Decorator-Based Instrumentation**
+```python
+from agentops.sdk.decorators import trace, agent, operation
+
+@trace
+def my_workflow():
+    agent = MyAgent()
+    return agent.process()
+```
+
+Each level builds on the previous one, allowing you to add sophistication as needed.
+
 ## Beyond Automatic Instrumentation: Decorators
 
 While AgentOps automatically instruments many popular libraries, you can gain finer-grained control and track custom parts of your code using our powerful decorators. This allows you to define specific operations, group logic under named agents, track tool usage with costs, and create custom traces.