monkai-trace 0.2.11

Official Python SDK for MonkAI - Track and analyze your AI agent conversations

MonkAI Trace - Python SDK

Official Python client for MonkAI - Monitor, analyze, and optimize your AI agents.

Features

• 📤 Upload conversation records with full token segmentation
• 📊 Track 4 token types: input, output, process, memory (always present in API)
• 📁 Upload from JSON files (supports your existing data)
• 🔄 Batch processing with automatic chunking and improved error handling
• 🛡️ Graceful optional dependencies - Import without dependencies, error only on use
• 🌐 HTTP REST API - Language-agnostic tracing for any runtime (Deno, Go, Node.js, etc.)
• 👤 External User Tracking - Identify end-users from WhatsApp, Teams, Telegram, etc.
• 🔌 Framework Integrations:
  • ✅ MonkAI Agent - Native framework with automatic tracking
  • ✅ LangChain - Full callback handler support (v0.2+)
  • ✅ OpenAI Agents - RunHooks integration (updated for latest API)
  • ✅ Python Logging - Standard logging handler with custom_object metadata

Installation

pip install monkai-trace

For framework integrations:

# MonkAI Agent (Native Framework)
pip install monkai-trace monkai-agent

# LangChain
pip install monkai-trace langchain

# OpenAI Agents
pip install monkai-trace openai-agents-python

Quick Start

LangChain Integration

Automatically track LangChain agents:

from langchain.agents import initialize_agent, load_tools
from langchain.llms import OpenAI
from monkai_trace.integrations.langchain import MonkAICallbackHandler

# Create callback handler
handler = MonkAICallbackHandler(
    tracer_token="tk_your_token",
    namespace="my-agents"
)

# Add to your agent
llm = OpenAI(temperature=0)
tools = load_tools(["serpapi"], llm=llm)
agent = initialize_agent(tools, llm, callbacks=[handler])

# Automatically tracked!
agent.run("What is the weather in Tokyo?")

Basic Usage

from monkai_trace import MonkAIClient

# Initialize client
client = MonkAIClient(tracer_token="tk_your_token")

# Upload a conversation
client.upload_record(
    namespace="customer-support",
    agent="support-bot",
    messages=[
        {"role": "user", "content": "Hello"},
        {"role": "assistant", "content": "Hi! How can I help?"}
    ],
    input_tokens=5,
    output_tokens=10,
    process_tokens=100,
    memory_tokens=20
)

External User Tracking (WhatsApp, Teams, etc.)

Track conversations from external channels with user identification:

from monkai_trace import MonkAIClient

client = MonkAIClient(tracer_token="tk_your_token")

# Track WhatsApp conversation
client.upload_record(
    namespace="customer-support",
    agent="support-bot",
    messages=[{"role": "user", "content": "Oi!"}],
    external_user_id="[phone]",    # WhatsApp number
    external_user_channel="whatsapp",      # Channel: whatsapp, teams, telegram, web, etc.
    session_id="session-123"
)

# Track Microsoft Teams conversation
client.upload_record(
    namespace="enterprise-support",
    agent="it-helpdesk",
    messages=[{"role": "user", "content": "Help with VPN"}],
    external_user_id="[e-mail]",
    external_user_channel="teams"
)

The dashboard displays the channel and end-user ID in conversation details.

### MonkAI Agent Framework (Native)

```python
from monkai_agent import Agent
from monkai_trace.integrations.monkai_agent import MonkAIAgentHooks

# Create tracking hooks
hooks = MonkAIAgentHooks(
    tracer_token="tk_your_token",
    namespace="my-namespace"
)

# Create agent with automatic tracking
agent = Agent(
    name="Support Bot",
    instructions="You are a helpful assistant",
    hooks=hooks
)

# Run agent - automatically tracked!
result = agent.run("Help me with my order")

OpenAI Agents Integration

from agents import Agent, WebSearchTool
from monkai_trace.integrations.openai_agents import MonkAIRunHooks

# Create tracking hooks (batch_size=1 recommended for real-time monitoring)
hooks = MonkAIRunHooks(
    tracer_token="tk_your_token",
    namespace="my-agent",
    batch_size=1  # v0.2.10+: Upload immediately
)

# Create agent with web search
agent = Agent(
    name="Assistant",
    instructions="You are helpful",
    tools=[WebSearchTool()]
)

# ✅ RECOMMENDED: Use run_with_tracking() for internal tools capture
result = await MonkAIRunHooks.run_with_tracking(agent, "Hello!", hooks)
# Captures: user message, web_search_call with sources, assistant response

# OR explicit capture (for custom flows):
hooks.set_user_input("Hello!")
result = await Runner.run(agent, "Hello!", hooks=hooks)

# ✅ v0.2.10: Internal tools (web_search, file_search) now properly captured!

HTTP REST API (Language-Agnostic)

For non-Python runtimes or when you prefer direct HTTP calls:

import requests

MONKAI_API = "https://lpvbvnqrozlwalnkvrgk.supabase.co/functions/v1/monkai-api"
TOKEN = "tk_your_token"

# Create session
session = requests.post(
    f"{MONKAI_API}/sessions/create",
    headers={"tracer_token": TOKEN, "Content-Type": "application/json"},
    json={"namespace": "my-agent", "user_id": "user123"}
).json()

# Trace LLM call
requests.post(
    f"{MONKAI_API}/traces/llm",
    headers={"tracer_token": TOKEN, "Content-Type": "application/json"},
    json={
        "session_id": session["session_id"],
        "model": "gpt-4",
        "input": {"messages": [{"role": "user", "content": "Hello"}]},
        "output": {"content": "Hi!", "usage": {"prompt_tokens": 5, "completion_tokens": 3}}
    }
)

See HTTP REST API Guide for complete documentation.

Upload from JSON Files

# Upload conversation records
client.upload_records_from_json("records.json")

# Upload logs
client.upload_logs_from_json("logs.json", namespace="my-agent")

📚 Practical Examples

Learn by example! Check out our comprehensive examples:

Session Management

• Basic Sessions - Automatic session creation and timeout
• Multi-User - WhatsApp bot with concurrent users
• Custom Timeouts - Configure for your use case

OpenAI Agents

• Basic Integration - Get started quickly
• Multi-Agent - Advanced handoff patterns

HTTP REST API

• Basic Usage - Direct API calls without SDK
• Async Client - High-performance async tracing
• OpenAI + HTTP - Trace OpenAI calls via REST

Run any example:

python examples/session_management_basic.py

See examples/README.md for full list and use case guide.

---

Session Management

MonkAI automatically manages user sessions with configurable timeouts:

• Default timeout: 2 minutes of inactivity
• Automatic session renewal: Active conversations continue in same session
• Multi-user support: Each user gets isolated sessions
• WhatsApp integration: Use user_whatsapp or user_id for user identification

hooks = MonkAIRunHooks(
    tracer_token="tk_your_token",
    namespace="support",
    inactivity_timeout=120  # 2 minutos
)
hooks.set_user_id("customer-12345")

See Session Management Guide for details.

Token Segmentation

MonkAI helps you understand your LLM costs by tracking 4 token types:

• Input: User queries and prompts
• Output: Agent responses and completions
• Process: System prompts, instructions, tool definitions
• Memory: Conversation history and context

client.upload_record(
    namespace="analytics",
    agent="data-agent",
    messages={"role": "user", "content": "Analyze this"},
    input_tokens=15,      # User query
    output_tokens=200,    # Agent response
    process_tokens=500,   # System prompt + tools
    memory_tokens=100     # Previous conversation
)

Documentation

• Quick Start Guide
• HTTP REST API Guide ⭐ NEW
• Session Management Guide
• MonkAI Agent Integration
• LangChain Integration
• OpenAI Agents Integration
• Logging Integration
• JSON Upload Guide
• API Reference

Examples

See the examples/ directory for:

• monkai_agent_example.py - MonkAI Agent framework integration
• langchain_example.py - LangChain integration
• langchain_conversational.py - LangChain with memory
• openai_agents_example.py - OpenAI Agents integration
• multi_agent_handoff.py - Multi-agent tracking
• logging_example.py - Python logging integration (scripts)
• service_logging_example.py - Python logging for long-running services
• send_json_files.py - Upload from JSON files
• http_rest_basic.py - HTTP REST API basic usage ⭐ NEW
• http_rest_async.py - Async HTTP REST client ⭐ NEW
• http_rest_openai.py - OpenAI + HTTP REST tracing ⭐ NEW

Development

# Clone repository
git clone https://github.com/monkai/monkai-trace-python
cd monkai-trace-python

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking
mypy monkai_trace

Requirements

• Python 3.8+
• requests >= 2.31.0
• pydantic >= 2.0.0
• monkai-agent (optional, for MonkAI Agent integration)
• langchain (optional, for LangChain integration)
• openai-agents-python (optional, for OpenAI Agents integration)

License

MIT License - see LICENSE file.

Support

• Documentation
• GitHub Issues
• Discord Community

Contributing

Contributions welcome! Please read our Contributing Guide first.