DEV Community

Cover image for Watch your CrewAI agents in real-time with PiQrypt Vigil
PiQrypt
PiQrypt

Posted on

Watch your CrewAI agents in real-time with PiQrypt Vigil

#crewai #python #ai #monitoring

You've added cryptographic audit trails to your crew (part 1)
and co-signed the handoffs between agents (part 2).

You now have tamper-evident history. But that's retrospective — you find out
something went wrong after the fact, when you run verify_chain().

Vigil is the real-time layer. It watches your agents while they run and raises
alerts the moment behavioural anomalies appear in the chain.

What Vigil is

Vigil is a local HTTP dashboard that launches on http://localhost:8421.
No external dependency. No data leaves your machine. It reads the same
AISS event chains your agents are writing and computes a VRS
(Verifiable Risk Score) in real time.

One command:

pip install piqrypt
Enter fullscreen mode Exit fullscreen mode

Vigil is included. To start it:

from vigil import start_vigil
start_vigil()
# Dashboard running at http://localhost:8421
Enter fullscreen mode Exit fullscreen mode

Or from the CLI:

piqrypt vigil start
Enter fullscreen mode Exit fullscreen mode

What VRS measures

VRS is a composite risk score — a number between 0 and 1, where 1 means
the chain is healthy and 0 means it's compromised. It's computed across
five cryptographic dimensions:

  • Integrity — are all hashes in the chain consistent?
  • Verified interactions — are A2A handoffs co-signed as expected?
  • Diversity — is the event type distribution normal, or is the agent doing something anomalous?
  • Finalization — are events being properly closed?
  • Rotation health — if the agent rotated its key, is the PCP continuity intact?

Critically: VRS is deterministic. No ML, no probabilistic scoring, no model
that could drift. Given the same chain, any third party running the same
verification gets the same score.

A full CrewAI setup with Vigil 

from crewai import Crew, Task
from piqrypt.bridges.crewai import AuditedAgent as Agent
from vigil import start_vigil

# Start Vigil before the crew runs
start_vigil()  # → http://localhost:8421

researcher = Agent(
    role="Researcher",
    goal="Find competitive pricing data",
    backstory="Expert at finding and analyzing market data.",
    agent_name="researcher_01"
)

writer = Agent(
    role="Writer",
    goal="Produce a pricing analysis report",
    backstory="Turns raw data into clear executive summaries.",
    agent_name="writer_01"
)

research_task = Task(
    description="Research competitor pricing for product X",
    agent=researcher
)

write_task = Task(
    description="Write a pricing analysis based on the research",
    agent=writer
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task]
)

result = crew.kickoff()
# While the crew runs, Vigil shows VRS and chain health per agent in real time
Enter fullscreen mode Exit fullscreen mode

Open http://localhost:8421. You'll see a dashboard per agent — event count,
VRS, chain health, and a SOC-style timeline of events as they're stamped.

What a CRITICAL alert looks like

If researcher_01's VRS drops below the critical threshold, Vigil raises an
alert:
[CRITICAL] researcher_01 — chain anomaly detected
VRS: 0.21 (threshold: 0.30)
Event #34: previous_hash mismatch
Affected events: 34 → end of chain

This means: someone (or something) modified event 34 after it was written.
Every subsequent hash is now invalid. The chain is compromised from that
point forward.

Vigil alerts. It never acts. The human decides what to do — that's the
design principle. Automated blocking without human decision is not in scope.

A real example: the PixelFlow agency

The PiQrypt repo includes a runnable demo with a digital content agency —
three CrewAI agents running on Claude Haiku, all monitored live in Vigil.

# From repo root
.\demos\start_families.ps1 pixelflow
# Opens Vigil automatically at http://localhost:8421
Enter fullscreen mode Exit fullscreen mode

Three agents, three distinct behavioural profiles:

  • pixelflow_content (Content Creator) — watch profile, TSI drift signal. Runs 3 content sessions per day. Vigil tracks the drift in event diversity over time.
  • pixelflow_seo (SEO Analyst) — safe profile, A2C concentration signal. 88% of its interactions go to pixelflow_content. Vigil flags this concentration pattern.
  • pixelflow_scheduler (Social Scheduler) — alert profile, temporal sync signal. Shares the same Claude Haiku backend as the other two — Vigil detects the timing correlation as a CRITICAL anomaly.

All three interact with external peers: anthropic_api, google_search_console,
instagram_api, twitter_api, analytics_ga4. Every interaction is
hash-chained. Every A2A handoff between agents carries a co-signed
interaction_hash in both chains.

The demo runs in loop mode, injecting events every 5 seconds. Vigil
recalculates VRS in real time. You can watch the pixelflow_scheduler
trust score degrade as the temporal sync pattern accumulates — without
touching a single line of your crew definition.

Full demo code: github.com/piqrypt/piqrypt/demos

Checking chain integrity programmatically

You don't have to use the dashboard. You can verify a chain directly:

import piqrypt as aiss
from aiss.exceptions import InvalidChainError

events = aiss.load_events("researcher_01")

try:
    aiss.verify_chain(events)
    print(f"Chain intact — {len(events)} events verified")
except InvalidChainError as e:
    print(f"Chain compromised: {e}")
Enter fullscreen mode Exit fullscreen mode

verify_chain() is binary — it returns cleanly if the chain is intact,
or raises InvalidChainError the moment a broken link is found. No score,
no partial result. The failure message tells you which link broke and why.

The VRS score with thresholds (CRITICAL below 0.30, healthy above 0.70)
is what Vigil computes continuously from the live chain and displays in
the dashboard. These are two different tools for two different moments:
verify_chain() is a point-in-time integrity check you call explicitly;
Vigil is the continuous watch that alerts you before you think to check.

Standard vs Pro

The Vigil included in pip install piqrypt (standard tier) gives you:

  • Full dashboard UI
  • VRS with 7-day history
  • CRITICAL alerts
  • Up to 2 bridge types monitored
  • Chain health per agent

Vigil Pro adds 90-day VRS history, all alert levels (WARNING, INFO, DEBUG),
unlimited bridge types, and TrustGate integration — the governance layer
that intercepts agent actions before execution and routes to a human when
policy requires it.

For most development and staging use cases, the standard tier is enough.

The full picture

Three articles, one integration pattern:

Part 1 — drop-in bridge, 3 lines, every agent action is now
Ed25519-signed and hash-chained.

Part 2 — A2A co-signing, the handoffs between agents carry
cryptographic proof that neither side can deny.

Part 3 — Vigil, real-time monitoring of chain health and behavioural
anomalies while the crew runs.

Together: your CrewAI crew has tamper-evident history, non-repudiable
inter-agent accountability, and live anomaly detection. None of it requires
a server, an account, or sending data anywhere.

Part 1: How I added cryptographic audit trails to any CrewAI crew in 3 lines

Part 2: Multi-agent accountability: who co-signs the handoff between your CrewAI agents?

Top comments (0)