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

# Getting Started

> Track AI conversations and interactions with Agnost AI

Track AI interactions, monitor performance, and analyze conversations in your Python application with the Agnost AI Conversation SDK.

<Note>
  Agnost receives the `input`, `output`, user traits, and metadata you send. For production traffic, use pseudonymous user IDs and redact sensitive data before calling the SDK. See [Data Governance](/data-governance).
</Note>

## Installation

Install the SDK using pip or uv:

<CodeGroup>
  ```bash pip theme={null}
  pip install agnost
  ```

  ```bash uv theme={null}
  uv add agnost
  ```
</CodeGroup>

## Quick Start

### Initialize the SDK

Import and initialize with your organization ID from the [Agnost AI dashboard](https://app.agnost.ai):

```python theme={null}
import agnost

# Initialize with your organization ID
agnost.init("your-org-id")
```

For customization options and advanced configuration, see the [Configuration Guide](/configuration).

### Track AI Interactions

#### Primary Method: `begin()` and `end()`

The recommended way to track AI interactions is using `begin()` to start tracking and `end()` to complete.

**`begin()` Parameters:**

```python theme={null}
interaction = agnost.begin(
    user_id="user_123",        # optional: Identifier for the user (default: "")
    agent_name="weather-agent", # optional: Name of your AI agent (default: "default")
    input="What is the weather?", # optional: Input text or prompt (can also set later)
    conversation_id="conv_123", # optional: ID to group related messages
    properties={"model": "gpt-4"} # optional: Additional metadata as key-value pairs
)
```

All parameters are optional. You can set the input later using `set_input()` if needed.

**`end()`: Success Case:**

When your AI processing completes successfully, call `end()` with the output. Latency is automatically calculated:

```python theme={null}
# Start tracking
interaction = agnost.begin(
    user_id="user_123",
    agent_name="weather-agent",
    input="What is the weather?"
)

# ... perform AI processing ...

# Complete successfully: latency auto-calculated!
interaction.end(output="The weather is sunny and 72°F.")
```

**`end()`: Error Case:**

When your AI processing fails, pass `success=False` and include the error message in the output:

```python theme={null}
# Start tracking
interaction = agnost.begin(
    user_id="user_123",
    agent_name="weather-agent",
    input="What is the weather?"
)

try:
    # ... attempt AI processing ...
    result = call_weather_api()
    interaction.end(output=result)
except Exception as e:
    # Track the failure with error message
    interaction.end(
        output=str(e),  # Error message goes in output
        success=False   # Mark as failed
    )
```

## Identify Users

Associate user characteristics for better analytics:

```python theme={null}
agnost.identify("user_123", {
    "name": "John Doe",
    "email": "john@example.com",
    "plan": "premium",
    "role": "admin"
})
```

Call `identify()` once per user to enrich your analytics with user traits like name, email, plan, or any custom attributes. For production traffic, prefer pseudonymous IDs and non-sensitive traits unless your team has approved sending direct identifiers.

## Custom Properties

Track additional metadata like model parameters, costs, or custom fields using `set_property()` or `set_properties()`:

```python theme={null}
# Start tracking
interaction = agnost.begin(
    user_id="user_123",
    agent_name="analytics-agent",
    input="Generate a report"
)

# Set properties one at a time
interaction.set_property("model", "gpt-4")
interaction.set_property("temperature", 0.7)

# Or set multiple properties at once
interaction.set_properties({
    "tokens": 1500,
    "cost": 0.045
})

interaction.end(output="Here's your sales report...")
```

## Manual Latency Tracking

By default, latency is automatically calculated from `begin()` to `end()`. You can override this if needed:

```python theme={null}
interaction = agnost.begin(
    user_id="user_123",
    agent_name="data-processor",
    input="Process data"
)

# ... processing ...

# Override auto-calculated latency
interaction.end(
    output="Data processed successfully",
    latency=2500  # milliseconds
)
```

## Cleanup

Ensure all events are sent before your application exits:

```python theme={null}
# Manually flush events
agnost.flush()

# Or shutdown completely (flushes and cleans up resources)
agnost.shutdown()
```

## Complete Example

Here's a full example of a chatbot with conversation tracking:

```python theme={null}
import agnost
import uuid
import os

# Initialize
agnost.init(
    org_id=os.getenv("AGNOST_ORG_ID"),
    endpoint="https://api.agnost.ai",
    debug=True
)

# Identify user
user_id = "user_123"
agnost.identify(user_id, {
    "name": "Alice Smith",
    "email": "alice@example.com",
    "plan": "premium"
})

# Create conversation
conversation_id = f"conv_{uuid.uuid4()}"

# First interaction
interaction = agnost.begin(
    user_id=user_id,
    agent_name="support-chatbot",
    input="Hello! I need help with my account.",
    conversation_id=conversation_id
)

# Simulate processing
response = "Hi Alice! I'd be happy to help. What do you need assistance with?"

# Complete with auto-calculated latency
interaction.end(output=response)

# Second interaction
agnost.track(
    user_id=user_id,
    input="I can't log in to my dashboard.",
    output="Let me help you reset your password. I'll send a reset link to alice@example.com.",
    agent_name="support-chatbot",
    conversation_id=conversation_id,
    properties={
        "model": "gpt-4",
        "temperature": 0.7
    }
)

# Cleanup
agnost.shutdown()
```

## What's Next?

* View your analytics in the [Agnost AI dashboard](https://app.agnost.ai)
* Explore the [Configuration Guide](/configuration) for advanced options
* Check out the [Python SDK Guide](/python-conversation) for detailed examples

## Need Help?

* Contact us at [founders@agnost.ai](mailto:founders@agnost.ai)
* [Book a call](https://call.agnost.ai/) for personalized support