agnost-ai_skill

Overview

This skill provides a practical guide and API/SDK reference for implementing data ingestion into Agnost AI analytics. It covers Conversation SDK usage for tracking AI interactions and the MCP SDK for Model Context Protocol server analytics. Includes code examples for Python and TypeScript, plus direct HTTP endpoints for custom integrations.

How this skill works

Initialize the Conversation or MCP SDK with your org ID and optional endpoint. Use begin()/end() to capture interaction lifecycle data and automatic latency, or use track() for one-shot events. For MCP servers, enable automatic tool and request tracking via the MCP SDK integrations. You can also call the capture-session and capture-event endpoints directly for custom pipelines.

When to use it

• Building AI chatbots or agents where you need conversation telemetry and latency metrics
• Instrumenting an MCP server to capture tool calls, inputs, and outputs for analytics
• Sending events from backend services that don’t use an SDK via direct HTTP API
• Enriching user profiles and grouping events using conversation_id for session analysis
• Implementing reliable shutdown and flush logic to avoid lost telemetry

Best practices

• Initialize the SDK at application startup with agnost.init(org_id) and optional endpoint/debug settings
• Use begin()/end() to auto-calculate latency and handle success/failure consistently
• Group related interactions with conversation_id to build session-level analytics
• Call flush() and shutdown() during graceful termination or register shutdown handlers
• Handle exceptions by ending interactions with success=false and including error details

Example use cases

• Track user-visible AI conversations in a chat widget and measure model latency per request
• Add MCP server tracking to log tool invocation args and results for debugging and usage metrics
• Send batched events from a serverless function using direct capture-event API calls
• Identify users with metadata to correlate usage by plan, company, or feature flags
• Monitor production agent performance by capturing tokens, model names, and success rates