Content
# AgentOps Black Box
**Investigate every agent action. Block risky ones before they land.**
AgentOps Black Box is a guardrail and forensic timeline for AI agents. It records agent tool calls, scores risky operations, blocks or pauses dangerous commands, and produces evidence-cited incident reports that can be exported to Splunk.
Built for the **Splunk Agentic Ops Hackathon** under the **Platform & Developer Experience** track.
Repository: https://github.com/prabhakaran-jm/agentops-black-box
---
## Why this matters
AI agents are starting to run operational tasks—deploying services, changing configs, installing dependencies, and invoking shell commands. When something breaks, teams need to know **what the agent did before the incident**, not guess from logs scattered across systems.
Splunk is the natural system of record for operational evidence. This project turns agent actions into **searchable, auditable evidence**: every tool call scored, every risky command flagged or blocked, every finding cited by `event_id`.
## What it does
- Records agent tool calls and simulated shell commands
- Scores risk using `policy.json` (regex rules, cumulative score, strictest decision)
- Runs in **blackbox** mode (observe all) or **guardrail** mode (block/pause risky actions)
- Stores evidence locally as append-only JSONL
- Optionally exports the same events to Splunk HEC (`index=agentops`, `sourcetype=agentops:agent`)
- Generates incident reports with event-ID citations via the local investigator
- Provides Splunk saved searches and a Simple XML dashboard
**Stack:** Python 3.11, stdlib-first, minimal dependencies (`requests`, `python-dotenv`, `pytest`).
## Where the AI fits
AgentOps Black Box is **not** the AI model or agent itself. It is the **observability, guardrail, and forensic layer** that wraps around AI agents' tool calls.
The demo uses a scripted deploy agent so the hackathon workflow is deterministic and safe to run on any machine. In production, the same `BlackBoxObserver` context manager can wrap tool calls from any agent framework:
- LangChain tool nodes
- Claude / Anthropic tool use
- OpenAI function calling
- Custom Python agents
- CI/CD automation bots
The project targets the **Platform & Developer Experience** track: it makes agent actions **observable, searchable, and governable** by routing every tool call through a scoring-and-logging layer and forwarding structured evidence to Splunk.
No live LLM API calls are made in the core SDK. Splunk MCP investigator and demo console are optional layers (see [Splunk MCP](#splunk-mcp-investigator) and [Demo console](#demo-console)).
## Demo story
An AI deploy agent patches checkout config and attempts a risky Kubernetes rollout restart.
- In **blackbox** mode, AgentOps records the action and later reconstructs the incident—including a `checkout_degradation` event linked to the restart.
- In **guardrail** mode, the same risky action is blocked before simulated execution and a prevention system event is logged.
Run the demo and investigator below to see the full timeline and cited report.
## Architecture
See also [architecture.md](architecture.md), [architecture.svg](architecture.svg), and [architecture.mmd](architecture.mmd).
**Local path:**
```
Demo Agent → BlackBoxObserver → RiskScorer → EventStore (JSONL) → Local Investigator → Report
↓
Optional Splunk HEC
```
**Optional Splunk path:**
```
HEC → index=agentops → saved searches / dashboard → Splunk MCP investigator
↓
demo_api → demo-ui (browser console)
```
## For judges (5-minute path)
| Step | Command / link |
|------|----------------|
| 1. Tests | `python -m pytest` |
| 2. End-to-end demo | `python scripts/validate_demo.py` |
| 3. Blackbox vs guardrail | `python examples/test_agent.py --mode blackbox --fresh` then `--mode guardrail` |
| 4. JSONL investigator | `python -m investigator.investigator --session latest --output /tmp/report.md` |
| 5. Splunk MCP investigator | Configure `SPLUNK_MCP_*` in `.env` → [docs/mcp-setup.md](docs/mcp-setup.md) → `python -m investigator.splunk_mcp --session latest` |
| 6. Demo console | **Terminal A (repo root):** `python -m demo_api` — **Terminal B:** `cd demo-ui && npm run dev` → http://localhost:5173 |
| 7. Framework hook | `python examples/wrap_tool_call.py` |
| 8. Policy insights | `python scripts/policy_insights_from_splunk.py` (JSONL) or `--source mcp` after HEC export |
Optional Splunk AI: [docs/ai-assistant-demo.md](docs/ai-assistant-demo.md). Hosted summary: `python -m investigator.investigator --enrich-summary` (set `SPLUNK_AI_DRY_RUN=0` + `SPLUNK_MGMT_*` for live `| ai`).
## Quickstart
Clone and enter the repo, then run:
```bash
git clone https://github.com/prabhakaran-jm/agentops-black-box.git
cd agentops-black-box
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m pytest
python examples/test_agent.py --mode blackbox --fresh
python -m investigator.investigator --events sample_data/events.jsonl --session latest --output sample_data/example_report.md
sed -n '1,80p' sample_data/example_report.md
python examples/test_agent.py --mode guardrail
```
**PowerShell:**
```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m pytest
python examples/test_agent.py --mode blackbox --fresh
python -m investigator.investigator --events sample_data/events.jsonl --session latest --output sample_data/example_report.md
Get-Content sample_data/example_report.md -TotalCount 80
python examples/test_agent.py --mode guardrail
```
One-command validation (runs the same checks):
```bash
python scripts/validate_demo.py
```
Copy `.env.example` to `.env` only if you plan to send events to Splunk (`AGENTOPS_DRY_RUN=0`).
## Local demo modes
| Mode | Behavior |
|------|----------|
| **blackbox** | Score and log every action; always run simulated `execute_fn`; set `would_block` when decision is BLOCKED/FLAGGED; record incidents after risky restarts |
| **guardrail** | Block `BLOCKED` decisions and hold `FLAGGED` for approval; never call `execute_fn` for blocked/pending actions |
> **Blackbox vs guardrail:** Blackbox mode **observes and records only** — it does not enforce. A risky
> action can show `decision=BLOCKED` alongside `result_status=executed` because the decision was
> *scored* but not *prevented*. Guardrail mode enforces the decision: `execute_fn` never runs for
> BLOCKED or FLAGGED actions.
```bash
python examples/test_agent.py --mode blackbox --fresh
python examples/test_agent.py --mode guardrail
python examples/approve.py --events sample_data/events.jsonl \
--session-id <session_id> --event-id <event_id> \
--decision APPROVED --reason "Approved after review"
```
All commands in the demo are **simulated strings**—no subprocess, no real shell execution.
## Optional Splunk HEC export
The local demo works **without Splunk**. JSONL remains the source of truth on your machine.
> **Default mode is dry-run.** Live Splunk export requires `AGENTOPS_DRY_RUN=0` and a valid HEC token — see `.env.example`.
1. Create Splunk index `agentops`.
2. Enable HTTP Event Collector (HEC) and create a token (port **8088**).
3. Set in `.env`:
- `SPLUNK_HEC_URL=https://your-splunk:8088`
- `SPLUNK_HEC_TOKEN=your-token`
- `AGENTOPS_DRY_RUN=0`
4. Run the demo; events append to JSONL and post to Splunk.
With `AGENTOPS_DRY_RUN=1` (default), the HEC client dry-runs locally and makes no network calls.
## Prove it in Splunk
This is the **live Splunk proof path**. The local JSONL demo remains available if Splunk is not configured.
1. Create index `agentops`
2. Enable HTTP Event Collector
3. Copy `.env.example` to `.env`
4. Set:
- `SPLUNK_HEC_URL`
- `SPLUNK_HEC_TOKEN`
- `SPLUNK_INDEX=agentops`
- `SPLUNK_SOURCETYPE=agentops:agent`
- `AGENTOPS_DRY_RUN=0`
5. Run:
```bash
python examples/test_agent.py --mode blackbox --fresh
python scripts/export_demo_to_splunk.py --events sample_data/events.jsonl
```
6. In Splunk Search, run:
```spl
index=agentops sourcetype=agentops:agent
| table _time event_id session_id agent_id event_type command decision risk_score risk_level result_status policy_rule
| sort _time
```
See also [scripts/splunk_smoke_search.spl](scripts/splunk_smoke_search.spl) for copy-paste SPL queries and [docs/splunk-proof.md](docs/splunk-proof.md) for the live-ingestion proof path.
## Splunk dashboard assets
Import-ready artifacts in [splunk/](splunk/):
- [splunk/saved_searches.conf](splunk/saved_searches.conf)
- [splunk/dashboard.xml](splunk/dashboard.xml)
- [splunk/README.md](splunk/README.md) — index setup, HEC env vars, import steps
```spl
index=agentops sourcetype=agentops:agent
```
## Project structure
```
agentops-black-box/
README.md
architecture.md
architecture.png
policy.json
agentops_bb/ # Core library (scorer, store, HEC, observer)
examples/ # Demo agent + approval helper
investigator/ # JSONL + Splunk MCP investigators, shared analysis
demo_api/ # FastAPI backend for demo console
demo-ui/ # React SPA demo console
sample_data/ # Demo JSONL + example_report.md
splunk/ # Saved searches + dashboard
scripts/ # validate_demo.py, export_demo_to_splunk.py
tests/
```
## Splunk MCP investigator
Query `index=agentops` via Splunk MCP Server and produce the same cited report as the JSONL investigator:
```bash
# Configure SPLUNK_MCP_URL and SPLUNK_MCP_TOKEN in .env (see .env.example)
python -m investigator.splunk_mcp --session latest --output /tmp/mcp_report.md
```
See [docs/mcp-setup.md](docs/mcp-setup.md).
## Demo console
Browser UI for session timelines, incident reports, blackbox vs guardrail comparison, and Splunk proof links.
**Terminal 1 — API (from repository root, not `demo-ui/`):**
```bash
cd agentops-black-box # repo root — required so Python finds demo_api/
pip install -r requirements.txt
python -m demo_api
# or: ./scripts/start_demo_api.sh
# or: uvicorn demo_api.main:app --reload --port 8000 # only when cwd is repo root
```
**Terminal 2 — UI:**
```bash
cd demo-ui
npm install
npm run dev
```
Open http://localhost:5173 (proxies `/api` to port 8000). If you see **Request failed** or `ECONNREFUSED`, the API is not running on port 8000 — start Terminal 1 first.
## Splunk AI capabilities
| Capability | Status | How |
|------------|--------|-----|
| HEC ingestion | Supported | `agentops_bb.hec_client`, `scripts/export_demo_to_splunk.py` |
| Saved searches + dashboard | Supported | `splunk/saved_searches.conf`, `splunk/dashboard.xml` |
| MCP investigator | Supported | `python -m investigator.splunk_mcp` |
| Splunk AI Assistant | Documented | [docs/ai-assistant-demo.md](docs/ai-assistant-demo.md) |
| Hosted models (summary enrich) | Optional | `--enrich-summary` / API `?enrich=1` via Splunk `\| ai` (`SPLUNK_MGMT_*`, `SPLUNK_AI_DRY_RUN=0`) |
## Validation
```bash
python -m pytest
python scripts/validate_demo.py
```
Or step by step:
```bash
python examples/test_agent.py --mode blackbox --fresh
python -m investigator.investigator --events sample_data/events.jsonl --session latest --output sample_data/example_report.md
python examples/test_agent.py --mode guardrail
```
## Safety
**Dangerous operations are simulated.** The project never invokes shell commands directly and never executes `rm`, `kubectl`, `curl`, or other risky commands on the host. The demo agent logs command strings and uses harmless lambda functions for simulated output only.
Guardrails enforce at the SDK/wrapper layer. Agent tool calls must route through `BlackBoxObserver`. This MVP is not an OS sandbox or kernel-level security control.
## Roadmap
- Approval UI for flagged actions (beyond demo console)
- CI/CD deploy event ingestion
- Policy recommendations from Splunk searches
## License
MIT — see [LICENSE](LICENSE).
