Pisama

Find and fix failures in AI agent systems. No LLM calls required.

Pisama ships heuristic detectors that apply across frameworks including n8n, LangGraph, Dify and OpenClaw, with per-platform gating (for example coordination runs only on multi-agent platforms). They run locally with zero LLM cost on the heuristic tier.

Install

pip install pisama

Related MCP server: Agent Analytics MCP Server

Usage

from pisama import analyze

result = analyze("trace.json")  # also accepts dicts and JSON strings

for issue in result.issues:
    print(f"[{issue.type}] {issue.summary} (severity: {issue.severity})")
    print(f"  Fix: {issue.recommendation}")

CLI

pisama analyze trace.json          # Analyze a trace
pisama watch python my_agent.py    # Watch a live agent (pip install "pisama[auto]")
pisama replay <trace-id>           # Re-run detection on stored traces
pisama smoke-test --last 50        # Batch test recent traces
pisama detectors                   # List all core detectors
pisama mcp-server                  # Start MCP server (pip install pisama[mcp])

MCP Server

Works in Cursor, Claude Desktop, and Windsurf. No API key is needed:

{
  "mcpServers": {
    "pisama": { "command": "pisama", "args": ["mcp-server"] }
  }
}

Optional extras

The base pisama install has zero-cost heuristic detection covered. Two extras add opt-in functionality on top.

Auto-instrumentation: pisama[auto]

Zero-code tracing for LLM calls. init() patches supported clients (Anthropic, OpenAI) so every call after it emits an OTEL trace Pisama can analyze, no manual instrumentation needed.

pip install "pisama[auto]"

import pisama.auto

pisama.auto.init(api_key="ps_...")

# All subsequent LLM calls are automatically traced
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(...)  # traced automatically

This used to require the standalone pisama-auto package. That package still works and stays fully supported for existing installs; pisama[auto] is the same code, folded into the base package so there is one less dependency to track. New projects should install it this way.

Agent hooks and tools: pisama[agents]

Real-time hooks, tools, and self-check utilities for agent runtimes (built for the Claude Agent SDK), wired to Pisama's detection infrastructure for in-loop failure prevention rather than after-the-fact analysis.

pip install "pisama[agents]"

from pisama.agents import pre_tool_use_hook, post_tool_use_hook

agent.hooks.pre_tool_use = pre_tool_use_hook
agent.hooks.post_tool_use = post_tool_use_hook

Active self-check is available the same way:

from pisama.agents import check

result = await check(
    output="The server is healthy based on the metrics.",
    context={"query": "Is auth-service down?", "sources": [...]},
)
if not result["passed"]:
    ...  # revise output based on result["issues"]

This used to require the standalone pisama-agent-sdk package. That package still works and stays fully supported for existing installs; pisama[agents] is the recommended path for new projects, one package instead of two.

Detectors

Core detectors, gated per platform (n8n, LangGraph, Dify, OpenClaw and others). A representative selection:

Links

• Documentation

• GitHub

• Platform

License

MIT

Source boundary

This repository is the public source for the MIT-licensed pisama Python package. It does not contain the Pisama Cloud backend, dashboard, calibration data, managed detection tiers, or paid automation.