Getting Started

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

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.

Installation

Install the SDK using pip or uv:

pip install agnost

uv add agnost

Quick Start

Initialize the SDK

Import and initialize with your organization ID from the Agnost AI dashboard:

import agnost

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

For customization options and advanced configuration, see the Configuration Guide.

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:

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:

# 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:

# 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:

agnost.identify("user_123", {
    "name": "John Doe",
    "email": "[email protected]",
    "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():

# 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:

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:

# 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:

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": "[email protected]",
    "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 [email protected].",
    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
Explore the Configuration Guide for advanced options
Check out the Python SDK Guide for detailed examples

Need Help?

Contact us at [email protected]
Book a call for personalized support

Conversation SDKs

OpenTelemetry

MCP Servers

Integrations

Installation

Quick Start

Initialize the SDK

Track AI Interactions

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

Identify Users

Custom Properties

Manual Latency Tracking

Cleanup

Complete Example

What’s Next?

Need Help?

​Installation

​Quick Start

​Initialize the SDK

​Track AI Interactions

​Primary Method: begin() and end()

​Identify Users

​Custom Properties

​Manual Latency Tracking

​Cleanup

​Complete Example

​What’s Next?

​Need Help?

Installation

Quick Start

Initialize the SDK

Track AI Interactions

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

Identify Users

Custom Properties

Manual Latency Tracking

Cleanup

Complete Example

What’s Next?

Need Help?