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.
pip install pisamafrompisamaimportanalyzeresult=analyze("trace.json") # also accepts dicts and JSON stringsforissueinresult.issues:
print(f"[{issue.type}] {issue.summary} (severity: {issue.severity})")
print(f" Fix: {issue.recommendation}")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])Works in Cursor, Claude Desktop, and Windsurf. No API key is needed:
{
"mcpServers": {
"pisama": { "command": "pisama", "args": ["mcp-server"] }
}
}The base pisama install has zero-cost heuristic detection covered. Two extras
add opt-in functionality on top.
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]"importpisama.autopisama.auto.init(api_key="ps_...")
# All subsequent LLM calls are automatically tracedimportanthropicclient=anthropic.Anthropic()
response=client.messages.create(...) # traced automaticallyThis 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.
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]"frompisama.agentsimportpre_tool_use_hook, post_tool_use_hookagent.hooks.pre_tool_use=pre_tool_use_hookagent.hooks.post_tool_use=post_tool_use_hookActive self-check is available the same way:
frompisama.agentsimportcheckresult=awaitcheck(
output="The server is healthy based on the metrics.",
context={"query": "Is auth-service down?", "sources": [...]},
)
ifnotresult["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.
Core detectors, gated per platform (n8n, LangGraph, Dify, OpenClaw and others). A representative selection:
| Detector | What It Catches |
|---|---|
loop | Infinite loops, retry storms, stuck patterns |
coordination | Deadlocked handoffs, message storms |
hallucination | Factual errors, fabricated tool results |
injection | Prompt injection, jailbreak attempts |
corruption | State corruption, type drift |
persona_drift | Persona drift, role confusion |
derailment | Task deviation, goal drift |
context | Context neglect, ignored instructions |
specification | Output vs. requirement mismatch |
communication | Inter-agent message breakdown |
decomposition | Poor task breakdown, circular dependencies |
workflow | Unreachable nodes, missing error handling |
completion | Premature completion, unfinished work |
withholding | Suppressed findings, hidden errors |
convergence | Metric plateau, regression, thrashing |
overflow | Context window exhaustion |
propagation | Silent error propagation across steps |
citation | Fabricated citations and source misattribution |
routing | Inputs misrouted to the wrong specialist agent |
mcp_protocol | MCP tool-communication failures |
MIT
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.