agent-health

v0.2.1

Published

2 months ago

Static, evidence-backed health checks for AI agent projects

0High
0Medium
0Low

joy7758

ai agent health check evidence static-analysis langchain crewai badge cli

🧬 Agent Immune

Agent Immune health status

Give your AI Agent an Immune System.

Agent Immune turns static repository signals into an explainable health assessment for AI agent projects.

Run one command to see health, trend, lifecycle stage, and a concrete Problem / Cause / Fix diagnosis:

npx agent-health .

Agent Immune analyzes repository files and metadata. It does not observe runtime behavior or establish that an agent is reliable, correct, safe, compliant, or ready for deployment.

Try the demo

From a checkout of this repository, run the deterministic example. It requires Node.js 20.19 or newer, but no API key or configuration:

git clone https://github.com/joy7758/agent-health.git
cd agent-health
npx agent-health examples/demo-agent

Expected output:

🧬 Agent Immune — agent-immune-demo-agent v1.0.0

Health: 76/100 (good)     Trend: — first check     Stage: birth

┌──────────────┬───────┬────────────┐
│ Dimension    │ Score │ Trend      │
├──────────────┼───────┼────────────┤
│ Identity     │    85 │ → stable   │
│ Execution    │   100 │ → stable   │
│ Evidence     │    30 │ → stable   │
│ Boundary     │   100 │ → stable   │
│ Adaptation   │    75 │ → stable   │
└──────────────┴───────┴────────────┘

Diagnosis
  Problem: Evidence Health score below acceptable (30)
  Cause:   Evidence Health is 30/100; one or more expected repository signals were not detected.
  Fix:     Add logging (winston, pino, structlog, loguru) to track agent behavior

📊 Current assessment · No recorded history · Badge: Health Checked

The scan is read-only and does not run the demo agent.

Install

Install it in an agent project:

npm install --save-dev agent-health
npx agent-health .

Or run a one-time assessment without adding a dependency:

npx agent-health .

The default status view is read-only. Record an assessment only when you want to update local health history and generate report and evidence artifacts:

npx agent-health check .

Features

Unified status: health score, trend, lifecycle stage, and five dimensions in one command.
Explainable diagnosis: connects a detected Problem to its static Cause and a concrete Fix.
Health memory and trends: records explicit checks and derives change over time.
Lifecycle detection: derives birth, growth, maturity, adaptation, recovery, or evolution views from current and recorded signals.
Evidence references: produces Agent Evidence Object (AEO) artifacts with integrity checks for selected scan-time inputs.
Recommendations: prioritizes actions supported by the signals that were actually detected.
CLI and TypeScript API: supports terminal workflows, automation, custom scorers, JSON output, and generated SVG badges.

What it measures

| Dimension | Weight | Static signals | |---|---:|---| | Identity | 20% | name, version, maintainer, framework, documentation | | Execution | 25% | tests, CI, entry points, dependencies, run instructions | | Evidence | 25% | logging, error handling, change history, trace/audit files | | Boundary | 15% | secret exclusions, lockfiles, configuration, security policy | | Adaptation | 15% | dependencies, configuration, framework and extension patterns |

Scores are transparent heuristics over files and project metadata. A low score is an engineering prompt, not a judgment about the agent's intelligence or behavior.

Commands

# Read-only current view (default)
agent-health .
agent-health status . [--json] [--verbose] [--no-color]

# Record a check and write reports/evidence
agent-health check . [--json] [--output <dir>]
agent-health check . --no-report

# Inspect derived views
agent-health history . [--json]
agent-health trend . [--json]
agent-health lifecycle . [--json]
agent-health state . [--json]
agent-health recommend . [--json]

# Artifact utilities
agent-health badge .
agent-health verify ./agent-health-evidence.json
agent-health comment --report ./agent-health-report.json

A normal check writes:

.agent-health/history/history.jsonl;
agent-health-report.md;
agent-health-report.json;
agent-health-badge.svg;
agent-health-evidence.json.

TypeScript API

import {
  scanProject,
  calculateHealth,
  buildAgentEvidenceObject,
  generateRecommendations,
} from 'agent-health';

const metadata = await scanProject('.');
const health = calculateHealth(metadata);
const recommendations = generateRecommendations(health);
const evidence = await buildAgentEvidenceObject(metadata, health);

Custom health scorers can implement Scorer and register through ScorerRegistry. The complete machine-readable surface is listed in agent-health.manifest.json.

Health badge

Generate a static repository health badge:

agent-health badge . \
  --output docs/agent-immune-health.svg \
  --label "agent immune"

Embed it in GitHub Markdown:

![Agent Immune health status](./docs/agent-immune-health.svg)

The badge is an assessment summary, not a safety, correctness, compliance, or deployment certification.

Evidence boundary

Each recorded assessment creates an Agent Evidence Object (AEO). Its SHA-256 hash lets agent-health verify detect mutation of the AEO after generation. The AEO also records hashes for selected manifests, documentation, security/configuration files, and detected CI workflows.

Important limits:

not every scanned file is hashed;
verify checks AEO self-integrity and does not re-scan the live project;
selected file hashes describe scan-time state only;
the AEO is not a reliability, safety, security, or compliance certificate.

The legacy machine value evidence-verified means all five dimension scores are at least 70. Human-facing output calls this Health Threshold Met; it does not imply independent verification.

See Product Boundary and the bundled AEO schema.

Roadmap

The roadmap is intentionally focused on the open-source Agent Immune product:

Now — v0.2.0: public CLI and TypeScript API, five-dimension assessment, health memory, trends, lifecycle views, diagnosis, recommendations, badges, and evidence artifacts.
Next — v0.2.x: improve documentation, examples, static-signal precision, packaging validation, and contributor experience based on public feedback.
Future candidates: evaluated separately from the current product and adopted only with clear user evidence.

Runtime systems, MCP Server, OpenTelemetry integration, Agent Registry, reputation systems, TITMAS standard development, and Digital Biosphere research are outside the current product boundary and are not promised by this roadmap.

Public release

Development

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

See AGENTS.md for the agent-readable repository map, documentation status for normative versus historical material, and RELEASE_STATUS.md for verified distribution state.

Community documents:

License

MIT