agnost 0.1.9

Python SDK for tracking AI conversations and events

Agnost Conversation SDK

Python SDK for tracking AI conversations and events. Monitor your AI agent interactions, track user conversations, and gain insights into how your AI applications are performing.

Installation

pip install agnost

Basic Usage

import agnost

# Initialize with your write key
agnost.init("your-write-key")

# Track an AI interaction
agnost.track_ai(
    user_id="user_123",
    event="chat_completion",
    input="What is the weather?",
    output="The weather is sunny.",
    agent_name="weather-agent"
)

API Reference

init(write_key, **config)

Initialize the SDK with your write key.

agnost.init("your-write-key")

# With custom configuration
agnost.init(
    "your-write-key",
    endpoint="https://api.agnost.ai",
    debug=True
)

track_ai(user_id, event, ...)

Record an AI interaction event.

event_id = agnost.track_ai(
    user_id="user_123",         # Required: User identifier
    event="chat_completion",     # Required: Event name
    input="What is the weather?",
    output="The weather is sunny.",
    agent_name="weather-agent",
    convo_id="conv_abc",         # Group related events
    properties={"temperature": "0.7"},
    latency=1500                 # Execution time in ms
)

Parameter	Type	Required	Description
user_id	str	Yes	User identifier
event	str	Yes	Event name
input	str	No	Input text/prompt
output	str	No	Output/response text
agent_name	str	No	Agent name (e.g., "weather-agent", "support-bot")
convo_id	str	No	Conversation ID for grouping
properties	dict	No	Additional event properties
timestamp	datetime	No	Event timestamp (defaults to now)
success	bool	No	Whether successful (default: True)
latency	int	No	Execution time in milliseconds

identify(user_id, traits)

Associate user characteristics with a user ID.

agnost.identify("user_123", {
    "name": "John Doe",
    "email": "[e-mail]",
    "age": 30,
    "plan": "paid"
})

begin(user_id, event, ...)

Begin a partial interaction for deferred completion. Use this when the output is not immediately available.

interaction = agnost.begin(
    user_id="user_123",
    event="chat_completion",
    agent_name="weather-agent"
)

interaction.set_input("What is the weather?")
interaction.set_property("temperature", "0.7")

# ... do async work ...

interaction.finish(
    output="The weather is sunny.",
    latency=1500
)

Interaction Methods:

Method	Description
set_input(text)	Set the input text
set_properties(dict)	Set multiple properties
set_property(key, value)	Set a single property
finish(output, success, latency)	Complete the interaction

flush()

Manually flush all queued events.

agnost.flush()

shutdown()

Shutdown the SDK and flush remaining events.

agnost.shutdown()

set_debug_logs(enabled)

Enable or disable debug logging.

agnost.set_debug_logs(True)  # See queued events

Configuration

You can customize the SDK behavior using the configuration object:

import agnost_conversation as agnost
from agnost_conversation import ConversationConfig

# Create a custom configuration
config = ConversationConfig(
    endpoint="https://api.agnost.ai",
    debug=False
)

# Apply the configuration
agnost.init("your-write-key", config=config)

Configuration Options

Option	Type	Default	Description
endpoint	str	"https://api.agnost.ai"	API endpoint URL
debug	bool	False	Enable debug logging

Advanced Usage

Conversation Tracking

Group related events using convo_id:

convo_id = "conv_" + str(uuid.uuid4())

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

# Follow-up message
agnost.track_ai(
    user_id="user_123",
    event="chat_completion",
    input="What's the weather?",
    output="The weather is sunny.",
    agent_name="support-bot",
    convo_id=convo_id
)

Direct Client Instantiation

For multiple clients or advanced use cases:

from agnost_conversation import ConversationClient

client = ConversationClient()
client.init("your-write-key")

client.track_ai(
    user_id="user_123",
    event="chat_completion",
    output="Hello!",
    agent_name="greeting-bot"
)

client.shutdown()

Error Handling

# Track failed interactions
agnost.track_ai(
    user_id="user_123",
    event="chat_completion",
    input="Generate an image",
    success=False,
    agent_name="image-agent",
    properties={"error": "Rate limit exceeded"}
)

Contact

For support or questions, contact the founders: [e-mail]