Choose Your Path¶

Pisama meets you at three different levels. Pick the one that matches what you have today, so you paste the right snippet the first time.

You want to...	Path	Needs
Check a trace locally, no signup	Offline SDK	`pip install pisama`
Send traces to a dashboard, get ML and LLM-judge detection plus self-healing	Hosted platform	An API key
Monitor an agent you already run on n8n, Dify, LangGraph, OpenClaw, Claude Code, or Managed Agents	Framework integration	A connector

Offline SDK¶

The fastest way to see Pisama work. Everything runs on your machine, no account, no network calls, $0 per trace. You get the 32 heuristic detectors (loop, repetition, derailment, hallucination overlap, and more). You do not get the dashboard, the ML or LLM-judge tiers, or self-healing.

pip install pisama
cat > trace.json <<'EOF'
{
  "trace_id": "demo-loop-001",
  "spans": [
    {"name": "Read", "kind": "tool", "input_data": {"path": "config.yaml"}},
    {"name": "Read", "kind": "tool", "input_data": {"path": "config.yaml"}},
    {"name": "Read", "kind": "tool", "input_data": {"path": "config.yaml"}},
    {"name": "Read", "kind": "tool", "input_data": {"path": "config.yaml"}},
    {"name": "Read", "kind": "tool", "input_data": {"path": "config.yaml"}},
    {"name": "Read", "kind": "tool", "input_data": {"path": "config.yaml"}},
    {"name": "Read", "kind": "tool", "input_data": {"path": "config.yaml"}},
    {"name": "Read", "kind": "tool", "input_data": {"path": "config.yaml"}}
  ]
}
EOF

import pisama

result = pisama.analyze("trace.json")
for issue in result.issues:
    print(f"[{issue.type}] {issue.summary} (severity {issue.severity})")

Start here: SDK Quickstart. To add Pisama to an existing app with one line and no manual trace building, see Auto-Instrumentation.

Hosted platform¶

Send your traces to api.pisama.ai (or your own deployment) and get the full tiered detection stack, a dashboard, calibration on your own traces, and server-side self-healing. This is the path for teams that want history, collaboration, and the higher-precision detectors.

Python, using your API key:

from pisama import Client

client = Client()  # reads PISAMA_API_KEY from the environment
result = client.ingest("trace.json")
for d in result.detections:
    print(f"[{d.type}] {d.summary} (severity {d.severity})")

TypeScript, using the Vercel AI SDK middleware:

import { observe } from "@pisama/sdk";
const model = observe(yourModel); // traces export to the platform automatically

Prefer to run the whole platform yourself? See Quickstart with Docker. For the underlying REST contract, see the API Reference and Authentication. For a feature-by-feature comparison of what pip install gives you versus the platform, see OSS vs Cloud.

Framework integration¶

Already running agents on a platform? Connect it directly and Pisama ingests executions as they happen, no trace building on your side. Each connector has a real backend with live connection status on the Integrations page.

For mapping a framework's output into a trace by hand, the Cookbook has per-framework recipes.