Skip to main content
This guide shows how to integrate Agnost AI analytics with your Python AI applications to track conversations, events, and user interactions.

​
Step 1: Install the SDK

pip install agnost

​
Step 2: Initialize the SDK

Import and initialize the SDK with your organization ID: 
import agnost

# Initialize with your organization ID
agnost.init("your-org-id")
You can find your organization ID in your Agnost AI dashboard.

​
Step 3: 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: 
# Start tracking an interaction with input
interaction = agnost.begin(
    user_id="user_123",
    agent_name="weather-agent",  # Defaults to "default" if not provided
    input="What is the weather?"
)

# ... perform AI processing ...

# Complete the interaction with output
# ✨ Latency is automatically calculated!
interaction.end(output="The weather is sunny.")
You can also set the input later if needed: 
interaction = agnost.begin(
    user_id="user_123",
    agent_name="weather-agent"
)
interaction.set_input("What is the weather?")
interaction.end(output="The weather is sunny.")

​
Alternative: track() for Simple Cases

For simple cases where input and output are immediately available, use the track() method: 
# Track a simple interaction
agnost.track(
    user_id="user_123",
    input="What is the weather?",
    output="The weather is sunny.",
    agent_name="weather-agent"
)

# agent_name defaults to "default" if not provided
agnost.track(
    user_id="user_123",
    input="Hello",
    output="Hi there!"
    # agent_name will be "default"
)

​
Track with Conversation Grouping

Group related messages using conversation_id: 
import uuid

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

# First message
agnost.track(
    user_id="user_123",
    input="Hello!",
    output="Hi there! How can I help?",
    agent_name="support-bot",
    conversation_id=conversation_id
)

# Follow-up message in the same conversation
agnost.track(
    user_id="user_123",
    input="What's the weather?",
    output="The weather is sunny.",
    agent_name="support-bot",
    conversation_id=conversation_id
)

​
Step 4: Track User Properties

Associate user characteristics with events: 
# Identify user traits
agnost.identify("user_123", {
    "name": "John Doe",
    "email": "[email protected]",
    "plan": "premium",
    "signup_date": "2024-01-15"
})

# Track events with additional properties
agnost.track(
    user_id="user_123",
    input="Generate a report",
    output="Here's your sales report...",
    agent_name="analytics-agent",
    properties={
        "model": "gpt-4",
        "temperature": 0.7,
        "tokens": 1500
    },
    latency=2300  # Execution time in milliseconds
)

​
Advanced Features

​
Adding Properties with begin() and end()

You can add custom properties to track model parameters, metadata, or any other information: 
# Start tracking an interaction with input
interaction = agnost.begin(
    user_id="user_123",
    agent_name="weather-agent",
    input="What is the weather?"
)

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

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

# ... perform async work (API calls, processing, etc.) ...

# Complete the interaction
# ✨ Latency is automatically calculated from begin() to end()!
interaction.end(output="The weather is sunny.")

# Or manually override latency if needed
interaction.end(output="The weather is sunny.", latency=1500)

​
Error Tracking

When tracking failed interactions, set success=False and pass the error message as the output: 
# Using track() for errors
agnost.track(
    user_id="user_123",
    input="Generate an image",
    output="Rate limit exceeded",  # Error message goes in output
    success=False,
    agent_name="image-agent"
)

# Using begin() and end() for errors
interaction = agnost.begin(
    user_id="user_123",
    agent_name="image-agent",
    input="Generate an image"
)

try:
    result = generate_image()
    interaction.end(output=result)
except Exception as e:
    interaction.end(
        output=str(e),  # Error message as output
        success=False
    )

​
Custom Configuration

Configure the SDK with custom settings: 
from agnost import ConversationConfig

# Initialize with custom configuration
agnost.init(
    "your-org-id",
    endpoint="https://api.agnost.ai",
    debug=True  # Enable debug logging
)

​
API Reference

​
track()

Record an AI interaction event.
ParameterTypeRequiredDescription
user_idstrNoUser identifier (default: "")
inputstrNoInput text/prompt
outputstrNoOutput/response text. When success=False, this is treated as the error message
agent_namestrNoAgent identifier (defaults to “default”)
conversation_idstrNoConversation ID for grouping
propertiesdictNoAdditional event properties
timestampdatetimeNoEvent timestamp (defaults to now)
successboolNoWhether successful (default: True). Set to False for errors
latencyintNoExecution time in milliseconds
Note on Error Tracking: When success=False, the output parameter should contain the error message.

​
identify()

Associate user characteristics with a user ID. 
agnost.identify(user_id, traits_dict)

​
begin()

Begin a partial interaction for deferred completion. Returns an Interaction object. Parameters:
  • user_id (str, optional): User identifier (defaults to "")
  • agent_name (str, optional): Agent name (defaults to “default”)
  • input (str, optional): Input text/prompt (can also use set_input() later)
  • conversation_id (str, optional): Conversation ID
  • properties (dict, optional): Initial properties
Interaction Methods:
  • set_input(text) - Set input text (optional if already passed to begin())
  • set_properties(dict) - Set multiple properties
  • set_property(key, value) - Set single property
  • end(output, success, latency) - Complete interaction
    • output - Response text. When success=False, this is the error message
    • success - Whether successful (default: True)
    • latency - Automatically calculated if not provided
# Recommended: Pass input directly
interaction = agnost.begin(
    user_id="user_123",
    agent_name="my-agent",
    input="What is the weather?"
)
interaction.set_property("model", "gpt-4")

# Success case
interaction.end(output="Result")  # latency auto-calculated!

# Error case - output contains error message
interaction.end(output="Error: timeout", success=False)

​
flush()

Manually flush all queued events. 
agnost.flush()

​
shutdown()

Shutdown the SDK and flush remaining events. 
agnost.shutdown()

​
Complete Example

Here’s a complete example of a chatbot with conversation tracking: 
import agnost
import uuid

# Initialize the SDK
agnost.init("your-org-id")

# Identify the user
agnost.identify("user_123", {
    "name": "Alice Smith",
    "email": "[email protected]",
    "plan": "premium"
})

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

# Track the conversation
messages = [
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi! How can I help you today?"},
    {"role": "user", "content": "What's the weather like?"},
    {"role": "assistant", "content": "The weather is sunny and 72°F."}
]

for i in range(0, len(messages), 2):
    user_msg = messages[i]
    assistant_msg = messages[i + 1] if i + 1 < len(messages) else None

    if assistant_msg:
        agnost.track(
            user_id="user_123",
            input=user_msg["content"],
            output=assistant_msg["content"],
            agent_name="chatbot",
            conversation_id=conversation_id,
            properties={"model": "gpt-4"},
            latency=1200
        )

# Shutdown when done
agnost.shutdown()

​
Next Steps