AI Agent Integration

AI Agent Integration

Using Ocular with AI coding agents and automation tools.

---

Why Ocular + AI Agent?

Ocular's --json output mode makes it ideal for programmatic consumption by AI agents. The combination enables:

• Automated performance analysis — Agent captures traffic, identifies slow queries, N+1 patterns, cache misses
• Code-to-behavior correlation — Agent sees what the ORM actually sends vs. what the code implies
• CI regression detection — Compare query counts before/after a PR
• Debugging assistance — Agent can observe live traffic while a user reproduces an issue

---

CLI JSON Mode

The primary integration point:

ocular proxy mysql --json 2>/dev/null

Each line is a JSON object:

{
  "timestamp": "2026-05-28T10:30:45Z",
  "component": "mysql",
  "protocol": "mysql",
  "command": "SELECT * FROM users WHERE id = 42",
  "full_command": "SELECT * FROM users WHERE id = 42",
  "response": "ResultSet (1 rows, 5 cols)",
  "response_detail": "...",
  "latency_ms": 3.73,
  "process": null,
  "src": "127.0.0.1:54321",
  "dest": "127.0.0.1:3306",
  "system": false
}

---

Integration Patterns

Pattern 1: On-Demand Diagnostic

Agent starts Ocular, captures traffic for a fixed duration, then analyzes:

# Start proxy, capture for 30 seconds
timeout 30 ocular proxy mysql --json --raw > /tmp/ocular-events.jsonl 2>/dev/null

# Agent analyzes the captured events
cat /tmp/ocular-events.jsonl | python3 -c "
import json, sys
from collections import Counter

events = [json.loads(line) for line in sys.stdin]
commands = Counter(e['command'].split()[0] for e in events)
slow = [e for e in events if e['latency_ms'] > 100]

print(f'Total events: {len(events)}')
print(f'Command distribution: {dict(commands.most_common(10))}')
print(f'Slow queries (>100ms): {len(slow)}')
for e in slow[:5]:
    print(f'  {e[\"latency_ms\"]}ms: {e[\"command\"][:80]}')
"

Pattern 2: CI Regression Check

Compare query behavior before and after a change:

# Baseline (main branch)
git checkout main
ocular proxy mysql --json --raw > baseline.jsonl &
pytest --db-port=13306
kill %1

# PR branch
git checkout feature-branch
ocular proxy mysql --json --raw > pr.jsonl &
pytest --db-port=13306
kill %1

# Compare
echo "Baseline queries: $(wc -l < baseline.jsonl)"
echo "PR queries: $(wc -l < pr.jsonl)"

Pattern 3: Hermes Agent Skill

For Hermes Agent users, Ocular can be integrated as a diagnostic skill:

## Workflow
1. Agent calls `ocular proxy <proto> --json --raw` with a timeout
2. Agent parses the JSONL output
3. Agent identifies patterns: N+1 queries, slow queries, cache misses
4. Agent correlates with codebase to suggest fixes

---

What Ocular Can and Cannot Do for Agents

Can do:

• Capture all middleware traffic as structured JSON events
• Identify N+1 query patterns (same query repeated with different params)
• Find slow queries (>100ms threshold)
• Analyze Redis cache hit/miss ratios
• Count queries per type (SELECT/INSERT/UPDATE/DELETE)
• Detect connection patterns

Cannot do (currently):

• Correlate events to specific code locations (no trace ID / span ID)
• Capture HTTPS/TLS traffic (only unencrypted middleware protocols)
• Track request causality across concurrent connections
• Provide application-level context (which API endpoint triggered the queries)

---

Limitations and Honest Assessment

Ocular is a data-layer observability tool, not a full APM. For AI agents, its sweet spot is:

• Database query analysis — N+1, slow queries, full table scans
• Cache behavior — Redis hit rates, key patterns
• Message queue inspection — RabbitMQ/Kafka message flow

It does not replace tools like LangSmith or Langfuse for LLM-specific observability (prompt/response capture, token usage, agent traces). Those operate at a different layer (HTTP/API level) that Ocular doesn't cover.

The most compelling use case is automated DBA-like analysis: the agent acts as a junior DBA that watches traffic and flags performance anti-patterns.