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

​
Installation

Install the SDK using pip or uv: 
pip install 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.

​
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?

​
Need Help?