Documentation

Quick Start

Get Guardy running in 5 minutes. Track sessions, detect issues automatically, and get AI-powered fixes.

Prerequisites

Python 3.9+ or Node.js 18+
A Guardy account (sign up free)
An API key from your organization settings

Step 1: Install the SDK

Python

  pip install guardy

  # For LangChain automatic tracking
  pip install guardy langchain-core

TypeScript

  npm install @guardy/sdk
  # or
  pnpm add @guardy/sdk

Step 2: Initialize & Track Sessions

Initialize the client with your API key, then create sessions to track your agent runs.

import guardy

# Configure with your API key (from Settings > API Keys)
guardy.configure(api_key="guardy_live_xxx")

# Simple API: begin/finish pattern
interaction = guardy.begin(
    user_id="user_12345",           # Required: tracks by user
    event="support_request",        # Event type (becomes agent name)
    input="Help me reset my password",
    convo_id="conv_789"             # Optional: group related events
)

# Your agent logic runs here...
response = your_agent.run(user_input)

# Finish with outcome and metrics
interaction.finish(
    output=response,
    success=True,
    estimated_cost=0.023,           # Track costs
    custom_metrics={
        "satisfaction": 4.5,
        "resolution_time": 45
    }
)

Step 3: Track Events

Track key events in your agent: LLM calls, tool usage, and decisions.

Option A: LangChain Auto-Tracking (Recommended)

If you use LangChain, our callback handler automatically tracks everything:

from guardy import GuardyClient
from guardy.langchain import GuardyCallbackHandler
from langchain.agents import AgentExecutor

# Initialize
client = GuardyClient(api_key="guardy_live_xxx")
session_id = client.create_session(
    name="Customer Support",
    agent_name="support-agent",
    user_id="user_123"
)

# Create callback handler - tracks everything automatically
handler = GuardyCallbackHandler(client, session_id)

# Add to your agent
result = agent_executor.invoke(
    {"input": "User's question"},
    {"callbacks": [handler]}  # Just add this!
)

# After completion, get usage stats
print(f"Cost: ${handler.total_cost:.4f}")
print(f"Tokens: {handler.total_tokens}")

Option B: Manual Event Tracking

For custom agents, manually track events:

# Track tool calls
client.track_tool_call(
    session_id=session_id,
    tool_name="search_knowledge_base",
    tool_input={"query": "password reset"},
    tool_output={"results": ["KB-001", "KB-002"]},
    reasoning="User needs password help"
)

# Track agent decisions
client.track_decision(
    session_id=session_id,
    reasoning="Will search KB before escalating",
    alternatives=["escalate_to_human", "ask_clarifying_question"],
    confidence=0.92
)

# Complete session with metrics
client.complete_session(
    session_id=session_id,
    success=True,
    estimated_cost=0.045,
    prompt_tokens=1500,
    completion_tokens=500
)

Step 4: View in Dashboard

Once sessions are tracked, open the Guardy dashboard to see your data:

Sessions

See all agent interactions with full event timelines. Click any session to replay what happened.

Agents

View metrics per agent: success rate, latency, cost. Identify regressions quickly.

Signals

Automatically detected issues across all sessions. Click to see AI diagnosis.

Codebase

Connect GitHub and chat with AI to fix issues directly in your code.

Complete Example

Here's a production-ready example with LangChain:

from guardy import GuardyClient
from guardy.langchain import GuardyCallbackHandler
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_react_agent

# Initialize Guardy
client = GuardyClient(api_key="guardy_live_xxx")

# Your agent setup
llm = ChatOpenAI(model="gpt-4o", temperature=0)
tools = [search_kb, create_ticket, send_email]
agent = create_react_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)

def handle_request(user_input: str, user_id: str) -> str:
    """Handle request with full Guardy tracking."""

    # Create session
    session_id = client.create_session(
        name=f"Support: {user_input[:40]}...",
        agent_name="customer-support",
        user_id=user_id
    )

    # Create handler for automatic tracking
    handler = GuardyCallbackHandler(
        client,
        session_id,
        verbose=True  # Prints tracking info
    )

    try:
        result = executor.invoke(
            {"input": user_input},
            {"callbacks": [handler]}
        )

        # Complete with real metrics from handler
        client.complete_session(
            session_id=session_id,
            success=True,
            estimated_cost=handler.total_cost,
            prompt_tokens=handler.total_prompt_tokens,
            completion_tokens=handler.total_completion_tokens
        )

        return result["output"]

    except Exception as e:
        client.complete_session(
            session_id=session_id,
            success=False,
            failure_reason=str(e)
        )
        raise

# Use it
response = handle_request(
    "I can't log into my account",
    user_id="user_12345"
)

Next Steps

Sessions & Events

Deep dive into session tracking and event types.

Code Integration

Connect GitHub and fix issues in your codebase.

Python SDK Reference

Complete API reference for all methods.

LangChain Integration

Automatic tracking for LangChain agents.