Run your first air trace in 5 minutes

Why run air before you have an incident

Most teams reach for forensics after something breaks. By then, the trace is incomplete, the reasoning is gone, and the on-call engineer is stitching together logs from five systems at 2am. The teams that recover fast are the ones that were already writing a signed record of every agent decision before the incident.

Project AIR™ is the forensic reconstruction layer for AI agents. The air CLI ingests an agent trace, runs detectors across two public OWASP taxonomies (all 10 OWASP Top 10 for Agentic Applications categories from ASI01 through ASI10; plus 3 OWASP Top 10 for LLM Applications categories: LLM01, LLM04, LLM06), plus 1 AIR-native forensic-chain-integrity check, and outputs a timeline you can hand to security, legal, or insurance. The airsdk Python package is what writes the trace in the first place, as a chain of AgDR (AI Decision Record) entries, each with a BLAKE3 content hash and an Ed25519 signature.

This guide walks through five steps that take roughly one minute each. The prerequisite is one LangChain agent you can run once. That is it.

Step 1: Install

pip install projectair

One package installs both the air CLI and the airsdk Python library. No torch, no heavy model downloads, no GPU. The CLI works on any trace file the SDK emits, and the SDK is a standard LangChain callback handler. If your agent runs today, this installs clean alongside it.

Step 2: Wire the AgDR callback into your agent

Add the callback handler to your LangChain AgentExecutor. Every tool call, every model response, every intermediate reasoning step becomes an AgDR entry, signed and chained to the previous one:

from airsdk import AIRCallbackHandler
from langchain.agents import AgentExecutor

handler = AIRCallbackHandler(key="...")
agent = AgentExecutor(callbacks=[handler], ...)

The handler is drop-in. You do not need to restructure your agent, your prompts, or your tool definitions. The signing key can be a local Ed25519 key pair you generate once, or a key ID that points at a cloud KMS if you already have one. Your existing LangChain agent behavior does not change. What changes is that every step now has a cryptographic receipt.

Step 3: Run your agent once

Run your agent the way you always do. A single conversation, a scripted test, a short session, any of it is enough to produce a trace file. The handler writes AgDR entries as the run progresses, so if the agent crashes mid-run you still get a partial, valid chain up to the point of failure. Partial evidence is still evidence.

The output is a structured log file, by default named after the run. We will use my-app.log in the next step.

Step 4: Run air trace

air trace my-app.log

The CLI walks the signed chain, verifies each hash and signature, and runs the trace against the OWASP Top 10 for Agentic Applications detection set. You get a console report that looks like this:

[AIR v0.1] Analyzing 247 agent steps across 3 conversations...

  ASI01 Agent Goal Hijack detected at step 47
  ASI02 Tool Misuse detected at step 51

[Export] forensic-report.json | forensic-report.pdf | forensic-report.siem

Each finding ties back to a specific step in the signed chain. ASI01 (Agent Goal Hijack) flags steps where the agent's behavior drifted from the task it was given. ASI02 (Tool Misuse) flags steps where the agent invoked a tool in a way the threat model says it should not. The mapping is to the OWASP Top 10 for Agentic Applications 2026, the same taxonomy your security team is already standardizing on.

If nothing triggers, the run is clean. You still have a signed record that says so, timestamped, reproducible, and auditable.

Step 5: Export the forensic report

The same scan emits three export formats out of the box:

forensic-report.json. The full decision chain with every AgDR entry, every hash, every signature, and every detection. This is the canonical evidence artifact. Any downstream tool can consume it.

forensic-report.pdf. A human-readable incident summary with the timeline, detections, and verification status. This is what legal, insurance, and executive stakeholders actually read.

forensic-report.siem. A normalized event stream ready for ingestion by your SIEM. Findings become alerts, the decision chain becomes queryable events, and your SOC analysts see agent incidents alongside the rest of your security telemetry.

Five minutes in, you have a signed forensic record, ASI detections against OWASP Top 10 for Agentic Applications, and three export formats that plug into the tools security, legal, and the SOC already use. None of that existed before you installed projectair.

What comes next

The OSS path is enough to get a signed record of every agent run, detect ASI violations, and export evidence packs. That is the floor. The ceiling is AIR Cloud: the hosted incident response layer where the forensic record streams into a real-time dashboard, incident workflows and alerting fire on detection, and the compliance engine projects the same chain into EU AI Act Article 72 exports, California SB 53 incident reports, SOC 2 evidence, and insurance carrier formats.

Before any of that, the question is the record. If your agent ran today and something went wrong tomorrow, could you prove what happened? Five minutes from now, the answer is yes.