VigilAgent Python SDK

Monitor, debug, and optimize your AI agents in real-time.

Website • Docs • GitHub

Installation

pip install vigilagent

Quick Start

from vigilagent import VigilAgent

# Initialize with your API key (find it in Settings)
va = VigilAgent(api_key="your-api-key")

# Log an LLM call with full message replay
va.log_event(
    agent_id="customer-support-agent",
    event_type="llm_call",
    payload={
        "model": "gpt-4o",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What is AI?"},
            {"role": "assistant", "content": "AI stands for Artificial Intelligence..."}
        ]
    },
    tokens_in=25,
    tokens_out=150,
    cost=0.002,
    latency=320
)

Tracing (Group events into sessions)

# Start a trace (a group of related events)
trace = va.start_trace(
    agent_id="customer-support-agent",
    task_description="Summarize a 5-page PDF document"
)

# Log events within the trace
trace.log_event(
    event_type="llm_call",
    payload={"model": "gpt-4o", "messages": [...]},
    tokens_in=500,
    tokens_out=200,
    cost=0.005,
    latency=1200
)

trace.log_event(
    event_type="tool_call",
    payload={"tool_name": "web_search", "query": "latest AI news"}
)

# End the trace
trace.end(status="success")

OpenAI Auto-Instrumentation

from vigilagent import VigilAgent
from openai import OpenAI

va = VigilAgent(api_key="your-api-key")
client = OpenAI()

# Wrap your OpenAI client for automatic logging
wrapped_client = va.wrap_openai(client, agent_id="my-agent")

# Use it exactly like normal — all calls are logged automatically!
response = wrapped_client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Features

• 📊 Real-time monitoring — Track every LLM call, tool invocation, and agent action
• 💰 Cost tracking — Know exactly how much each agent costs per call
• 🔍 Trace Replay — Step through agent execution like a debugger
• ⚡ Low overhead — Async logging, minimal latency impact
• 🔗 OpenAI integration — Auto-instrument with one line of code

License

MIT