pisama-agent-sdk

ATIF trace adapters and real-time failure detection hooks for agent runtimes, including the Claude Agent SDK, OpenHands, and Harbor-compatible evaluation flows.

Part of the Pisama platform for single-agent, multi-agent, and sub-agent failure detection.

Requires Python 3.10 or newer. Python 3.10 through 3.13 are tested.

As of 0.4.0, this package is a thin, permanent compatibility shim. The implementation now lives in pisama.agents (part of the pisama base package, installed automatically as a dependency); every module here re-exports its pisama.agents equivalent under the original import path. Every API below works exactly as documented, unchanged, and this package stays fully supported for existing installs. New features and fixes land in pisama.agents, not here, so for new projects we recommend installing it directly: pip install "pisama[agents]" gets you the same module, one package instead of two.

Install

pip install pisama-agent-sdk

New projects: install the extra directly instead, same module, one less package to track.

pip install "pisama[agents]"

Then from pisama.agents import ... in place of from pisama_agent_sdk import .... Both stay in sync (this package re-exports pisama.agents by reference); pick whichever import path suits your project. Everything below uses the pisama_agent_sdk import path for existing users; swap in pisama.agents if you installed the extra.

Quick Start

Passive Monitoring (hooks)

Add two lines to your Claude Agent SDK setup:

from pisama_agent_sdk 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

Every tool call is now checked for failure patterns in real-time (<100ms). If a loop or other issue is detected, the hook returns a blocking signal to stop the agent.

Active Self-Check

Let the agent verify its own output:

from pisama_agent_sdk 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"]:
    # result["issues"] describes what went wrong
    print(result["issues"])

Custom Tool for Claude Agent SDK

Give the agent a tool it can call to self-check:

from pisama_agent_sdk import create_check_tool
from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    custom_tools=[create_check_tool()],
)

Configuration

from pisama_agent_sdk import configure_bridge, BridgeConfig

configure_bridge(BridgeConfig(
    fail_open=True,           # Allow execution if detection errors (default: True)
    detection_timeout_ms=80,  # Max detection time per hook (default: 80)
))

Tool Matchers

Control which tools get checked:

from pisama_agent_sdk import PreToolUseHook, HookMatcher

# Only check file and shell tools
matcher = HookMatcher(
    tool_name_pattern=r"^(Read|Write|Edit|Glob|Grep|Bash|bash|shell)$"
)
hook = PreToolUseHook(matcher=matcher)
agent.hooks.pre_tool_use = hook

Built-in matchers: ALL_TOOLS, FILE_TOOLS, SHELL_TOOLS, DANGEROUS_COMMANDS, AGENT_TOOLS.

How It Works

1. Your agent makes a tool call
2. pre_tool_use_hook converts the call into a Pisama Span
3. Registered detectors run against the span + recent session context
4. If a failure is detected (e.g., 5th consecutive Read of the same file), the hook returns a blocking result
5. The agent receives the block signal and adjusts its behavior

Detection runs entirely locally using pisama-core detectors. No network calls unless you configure a remote endpoint.

Evaluator Mode

Use Pisama as an evaluator in multi-agent harnesses:

from pisama_agent_sdk import PisamaEvaluator

evaluator = PisamaEvaluator(endpoint="https://your-pisama-instance/api/v1")
result = await evaluator.evaluate(trace_data)
print(result.passed, result.failures)

Requires pip install pisama-agent-sdk[evaluator].

License

MIT