Quickstart - PandaProbe

The PandaProbe Harness wraps any PandaProbe-instrumented agent in a self-healing envelope: it evaluates every completed turn, posts a diagnostic notice when quality degrades, and gives your agent the tools to analyze its own failures and write — and prove — its own operating rules.

Before you begin, make sure you have:

A PandaProbe account. Sign up at app.pandaprobe.com.
A PandaProbe API key + project name.
The pandaprobe CLI installed and authenticated — the harness reaches the platform exclusively through it.
An agent traced with the PandaProbe SDK, so its sessions produce scoreable traces.

Install the package

pip install pandaprobe-harness

uv add pandaprobe-harness

The core has zero runtime dependencies. Framework adapters are optional extras, e.g. pip install "pandaprobe-harness[langgraph]".

Install and authenticate the CLI

curl -fsSL https://cli.pandaprobe.com/install.sh | sh
export PANDAPROBE_API_KEY="your-api-key"
export PANDAPROBE_PROJECT_NAME="your-project-name"

Every platform call the harness makes — running evaluations, polling scores, inspecting traces — shells out to pandaprobe. It never talks to the REST API directly.

Pick a workspace root

The harness maintains its diagnostic workspace (mailbox, journal, rules, eval cases) on disk. The default is /harness; point it anywhere writable:

export HARNESS_ROOT="./harness"

Wire the harness into your agent loop

Any custom loop integrates in a handful of lines — no adapter required:

from pandaprobe_harness import Harness
from pandaprobe_harness.agent_tools.native import as_anthropic_tools

harness = Harness.create()          # provisions the workspace, wires everything,
                                    # runs the startup health check

# 1. The harness preamble: learned rules + the standing self-diagnostic
#    protocol + a "N pending notices" banner when something is wrong.
system_prompt = harness.system_context() + MY_PROMPT

# 2. The self-diagnostic toolset (14 operations) alongside your own tools.
specs, dispatch = as_anthropic_tools(harness.toolset)
tools = my_tools + specs

# 3. Delimit turns — the harness evaluates each completed turn.
async def one_turn(session_id: str, user_input: str) -> str:
    async with harness.turn(session_id):
        return await my_agent_step(system_prompt, tools, user_input)

Using LangGraph, CrewAI, or another supported framework? A Harness.for_<framework>() factory wires turn detection for you — see Framework adapters.

Watch a healing cycle

Nothing else is required — the loop is fully automatic:

A turn finishes and its session scores breach (e.g. agent_reliability drops below 0.5).
The harness posts a diagnostic notice to the workspace mailbox and the system context grows a ⚠ HARNESS: 1 pending diagnostic notice(s) banner.
Guided by the standing protocol, your agent pulls the notice, inspects the flagged traces, and records a mitigation rule — which enters as an unproven candidate.
The harness validates the candidate automatically (by replaying the captured failure, or by watching the next live sessions) and promotes it to an active rule — or retires it.
The validated rule re-enters the system prompt on every future run.

Inspect what happened at any time:

harness.mailbox.pending()                    # open notices
harness.rules.active()                       # validated rules
harness.journal.recent()                     # the cross-run event log

Try it offline first

The repository ships runnable, fully-offline demos — no credentials, no network:

git clone https://github.com/chirpz-ai/pandaprobe-harness && cd pandaprobe-harness
uv sync --group dev
uv run python examples/offline_self_heal.py       # the pull loop, end to end
uv run python examples/closed_loop_self_heal.py   # candidate → validate → promote → regression

What’s next?

Concepts

What self-healing means here, and the ideas behind the closed loop

How it works

The full pipeline, the workspace on disk, and one healing cycle in detail

Framework adapters

LangGraph, LangChain, DeepAgents, CrewAI, Claude Agent SDK, OpenAI Agents

​Try it offline first

​What’s next?

Concepts

How it works

Framework adapters

Try it offline first

What’s next?