DEV Community: Krishna shakula

I built an open-source browser agent that turns any website into structured JSON

Krishna shakula — Thu, 18 Jun 2026 02:30:28 +0000

I built an open-source browser agent that turns any website into structured JSON

Most web scraping tools still think the internet is made of clean HTML.

It is not.

The modern web is made of:

JavaScript-heavy pages
login-ish flows
dropdowns
old government forms
pricing pages with no API
websites that change their DOM every week
pages where the useful data is behind clicks, tabs, filters, and forms

So I built Browsewright:

Give an LLM a URL and a goal. It drives a real Chrome browser, completes the task, and returns structured data instead of raw HTML.

GitHub: https://github.com/krishnashakula/browsewright

pip install browsewright

Then run:

bw "https://stripe.com" "what does this company do and who is it for"

Instead of writing selectors, XPath, browser scripts, retry logic, and extraction code, you give it intent.

Browsewright figures out the path.

The idea

Playwright automates a browser you script.

Browsewright is the browser that scripts itself.

With traditional browser automation, you write code like:

page.goto(url)
page.click("#pricing")
page.wait_for_selector(".plans")
page.locator(".price-card").all()

That works until the website changes.

Browsewright flips the model.

You say:

bw "https://example.com/pricing" "extract all plans, prices, limits, and billing options as JSON"

The LLM reads the page, decides what matters, drives the browser only when needed, and returns structured output.

Why I built it

I kept seeing the same problem in AI agents, lead enrichment systems, market research tools, and n8n-style automations:

The LLM is smart enough to understand the task.

But it cannot reliably operate the web.

Most systems stop at one of these layers:

Fetch raw HTML
Convert the page to Markdown
Ask the LLM to summarize it
Hope the answer is useful

That is fine for simple pages.

But real business workflows need action:

Fill this form
Find pricing
Search this registry
Compare competitors
Track stock availability
Extract lead data
Monitor brand mentions
Submit a query
Return clean JSON

That is not just scraping.

That is browser work.

What Browsewright does

Browsewright is an open-source Python tool that lets an LLM operate a real browser.

It can:

read a page
decide what to click
fill forms
submit forms
extract structured JSON
use cheaper shortcuts before launching Chrome
run locally with your own API key
expose itself as an MCP server for AI assistants

Install:

pip install browsewright

Use it from the CLI:

bw "https://news.ycombinator.com" "what is the top story right now"

Use JSON mode:

bw "https://example.com" "find the pricing plans" --json

Debug visually:

bw "https://example.com" "debug this page" --no-headless --verbose

Use it in Python:

import asyncio
from browsewright import search

res = asyncio.run(
    search(
        "https://stripe.com",
        "what does this company do and who is it for?"
    )
)

print(res.answer)
print(res.stage)
print(res.tokens_total)
print(res.elapsed_s)

It does not just read the web. It acts on the web.

Most AI scraping tools can summarize a page.

Browsewright can operate a page.

Example:

bw-tasks form \
  "https://registers.maryland.gov/RowNetWeb/Estates/frmEstateSearch2.aspx" \
  --profile examples/sample_profile.json

That is not a clean JSON API.

That is not a modern developer-friendly endpoint.

It is an old form-based website.

Browsewright can inspect the form, understand the fields, map a profile to the inputs, choose valid dropdown options, submit the form, and extract results.

No selectors.

No XPath.

No custom script for that one website.

Just intent.

The cheap path comes first

One design goal was simple:

Do not launch a browser unless you actually need a browser.

A lot of sites can be answered from cheaper paths:

public APIs
RSS feeds
JSON endpoints
public archives
static content

So Browsewright tries a pre-flight pipeline first.

Only if that fails does it spin up Chrome.

That makes it useful for workflows where cost matters.

In my benchmark, Browsewright extracted data from 50 real websites for about 4.7 cents total.

Reproduce it:

python examples/batch_test.py

Built-in workflows

Browsewright ships with task commands for common business automation use cases.

1. Competitor watch

bw-tasks watch "https://competitor.com/pricing"

Use this to monitor pricing pages, feature pages, changelogs, positioning, and landing pages.

2. Lead enrichment

bw-tasks enrich "https://company.com"

Returns CRM-style fields and a personalized first line for outreach.

Example output:

{
  "company_name": "ExampleCo",
  "industry": "AI SaaS",
  "icp_fit_score_1_to_10": 8,
  "personalized_cold_email_first_line": "I noticed your team is expanding into enterprise AI workflows..."
}

3. Agentic form fill

bw-tasks form "https://example.com/form" --profile profile.json

Useful for authorized internal workflows, testing, research forms, and repetitive manual data-entry tasks.

4. Price and stock tracking

bw-tasks track "https://store.com/product"

Track product availability, price movement, and page changes.

5. Brand monitoring

bw-tasks brand "Browsewright" "https://site1.com" "https://site2.com"

Collect mentions, sentiment, and summaries across selected URLs.

Works with MCP

Browsewright can also run as an MCP tool.

Install with MCP support:

pip install "browsewright[mcp]"

Add it to your MCP client:

{
  "mcpServers": {
    "browsewright": {
      "command": "bw-mcp"
    }
  }
}

Now your AI assistant gets a tool like:

read_page(url, goal)

That means an AI assistant can research the web with a real browser instead of only guessing from static text.

Why structured JSON matters

A summary is nice.

JSON is useful.

For automation, you usually need data that can go into another system:

a CRM
a spreadsheet
a database
Slack
n8n
Make
Zapier
a vector database
an internal dashboard
another AI agent

Browsewright has a core structured extraction primitive:

import asyncio
from browsewright import extract_structured

schema = {
    "headline": "string",
    "open_roles": [
        {
            "title": "string",
            "team": "string",
            "location": "string"
        }
    ]
}

data = asyncio.run(
    extract_structured(
        "https://example.com/careers",
        schema,
        instruction="Extract the page headline and every open job posting."
    )
)

print(data["open_roles"])

This is the part I care about most:

Not “AI browsed a website.”

More like:

AI turned a messy website into a reliable automation input.

Where this is useful

Browsewright is useful when you need web data but the site does not give you a clean API.

Examples:

AI agents

Give your agent the ability to inspect pages, fill forms, and return structured output.

n8n workflows

Use Browsewright as the browser/research layer, then pass JSON into the rest of your workflow.

Sales automation

Enrich leads from company websites, pricing pages, career pages, and recent announcements.

Market research

Extract competitor positioning, product pages, integrations, pricing, and messaging.

Recruiting

Extract job listings from company career pages into clean structured data.

Monitoring

Track changes on important URLs and alert when something changes.

Internal operations

Automate repetitive browser tasks on systems where you are authorized to operate.

A simple n8n-style flow

Here is the kind of workflow Browsewright is designed for:

Schedule trigger
   ↓
Run Browsewright on competitor pricing page
   ↓
Extract structured JSON
   ↓
Compare with previous snapshot
   ↓
If changed, send Slack alert
   ↓
Save result to database

The browser is only one piece.

The output is what makes the automation useful.

Important note on responsible use

Browsewright is designed for authorized research, your own properties, internal automation, and websites where automated access is allowed.

Use polite mode.

Respect robots.txt.

Respect rate limits.

Respect terms of service.

Do not use browser automation to abuse websites, bypass rules, collect private data, or violate laws.

The best use case is not “scrape everything.”

The best use case is:

Replace repetitive manual browser work with reliable, transparent, authorized automation.

How it compares conceptually

Tool type	Good at	Weakness
HTTP scraper	Fast static extraction	Breaks on JS, forms, interaction
Browser script	Precise automation	Requires selectors and maintenance
Search API	Quick answers	Limited action, limited page control
LLM summarizer	Natural language answers	Often not structured or repeatable
Browsewright	Intent → browser action → JSON	Best for tasks where browser interaction matters

Browsewright is not trying to replace every scraper.

It is for the cases where plain scraping is too brittle and full manual browser scripting is too much work.

Try it

Install:

pip install browsewright

Run:

bw "https://example.com" "find the pricing and return the plans as JSON"

Clone:

git clone https://github.com/krishnashakula/browsewright
cd browsewright
pip install -e .

Use MCP:

pip install "browsewright[mcp]"

GitHub:

https://github.com/krishnashakula/browsewright

What I want feedback on

I am looking for feedback from developers building:

AI agents
scraping systems
research agents
n8n workflows
sales automation
market intelligence tools
browser automation tools
MCP servers

Especially:

What websites should I test next?
What built-in tasks should Browsewright support?
What MCP workflows would make this more useful?
What would make you trust browser-agent output in production?
What should the API look like for teams using this at scale?

If this saves you from writing one more fragile scraper, please star the repo.

GitHub: https://github.com/krishnashakula/browsewright

The web was built for humans.

Browsewright lets agents use it like humans — and return data like machines.

IRAS: Building a Production-Grade Autonomous Incident Response Agent

Krishna shakula — Fri, 08 May 2026 02:14:50 +0000

IRAS: Building a Production-Grade Autonomous Incident Response Agent

Incident response at 3 AM is brutal. Your on-call engineer is woken up, scrambles to understand what's broken, manually triages the issue, performs root cause analysis, and then—if they're lucky—can finally propose a fix. This process typically takes 30+ minutes and burns out your team.

We built IRAS to automate this entire workflow. When an alert fires, IRAS triages the incident, performs RCA, generates a remediation plan, and drafts a post-mortem—all within 2 minutes. Your engineer reviews and approves the fix. That's it.

The Problem

Incident response is repetitive and exhausting:

Alert fires → on-call engineer wakes up
Manual triage → what's the severity? what's affected?
Root cause analysis → why did this happen?
Remediation planning → what's the fix?
Post-mortem → document what happened and why
Execution → apply the fix
Follow-up → prevent recurrence

Steps 2-5 are highly repetitive and can be automated. IRAS handles all of them.

The Solution: IRAS

IRAS is an autonomous AI agent built on Claude, LangGraph, and FastAPI. It follows a deterministic workflow:

Alert → Triage → RCA → Remediation → Post-mortem → Human Approval → Execution

Key Features

1. Fully Autonomous with Human Approval Gates

The agent makes decisions at each step (triage severity, identify root cause, propose fix)
Human approval is required before any remediation is executed
Safety-first design: no auto-remediation without review

2. Sub-2-Minute End-to-End Handling

Alert ingestion to remediation proposal in <120 seconds
Reduces on-call burden significantly
Enables faster incident resolution

3. Production-Grade Reliability

99% test coverage with 292 passing tests
Comprehensive logging and observability
Deterministic workflow with structured outputs

4. Zero External Service Dependencies

Mock clients for Slack and PagerDuty included
No vendor lock-in
Runs entirely on your infrastructure

5. Automatic Post-Mortem Generation

Generates incident narratives automatically
Includes root cause, impact, and remediation details
Reduces post-incident documentation burden

Architecture

Tech Stack

FastAPI: REST API for alert ingestion and workflow orchestration
LangGraph: Multi-step agentic workflow with state management
Pydantic AI: Type-safe agent definitions and structured outputs
Claude: Core reasoning engine for triage, RCA, and remediation
Pytest: Comprehensive test suite with 99% coverage

Workflow Design

The agent follows a multi-step workflow:

Alert Ingestion: Receives alert from monitoring system (Prometheus, DataDog, etc.)
Incident Triage: Analyzes alert to determine severity, affected services, and impact
Root Cause Analysis: Investigates logs, metrics, and system state to identify root cause
Remediation Planning: Generates a step-by-step fix based on the root cause
Post-Mortem Generation: Drafts incident narrative with timeline and learnings
Human Approval: On-call engineer reviews and approves the proposed fix
Execution: Applies the remediation (if approved)

Each step uses Claude with structured outputs (Pydantic) to ensure reliability and parseability.

Human-in-the-Loop Safety

No auto-remediation happens without human approval. The workflow is designed to:

Provide clear, actionable recommendations
Enable quick review and approval
Maintain human control and oversight
Reduce on-call burden without sacrificing safety

Testing and Reliability

IRAS includes 292 passing tests with 99% code coverage. Testing covers:

Unit tests: Individual agent steps (triage, RCA, remediation)
Integration tests: Full workflow end-to-end
Mock clients: Slack and PagerDuty mocked for testing without external dependencies
Edge cases: Handling of incomplete data, ambiguous root causes, etc.

The test suite ensures the agent behaves predictably and reliably in production.

Getting Started

Prerequisites

Python 3.11+
Docker (optional, for containerized deployment)
Anthropic API key (for Claude access)

Quick Start

# Clone the repo
git clone https://github.com/krishnashakula/IRAS.git
cd IRAS

# Install dependencies
pip install -r requirements.txt

# Set your Anthropic API key
export ANTHROPIC_API_KEY="your-key-here"

# Run the agent
python -m iras.main

That's it. No complex setup, no vendor lock-in.

Docker Deployment

docker build -t iras .
docker run -e ANTHROPIC_API_KEY="your-key-here" iras

Real-World Impact

In simulated production scenarios, IRAS:

Reduces on-call burden by 80%+: Eliminates manual triage and RCA
Accelerates incident resolution: Sub-2-minute response time
Improves post-mortem quality: Automatic, comprehensive incident narratives
Maintains safety: Human approval gates ensure control

Design Decisions

Why LangGraph?

LangGraph provides deterministic, multi-step workflows with state management. Unlike simple prompt chains, LangGraph enables:

Clear decision points and branching logic
State persistence across steps
Easy debugging and observability
Integration with human approval gates

Why Pydantic AI?

Structured outputs are critical for reliability. Pydantic AI ensures:

Type-safe agent definitions
Guaranteed parseability of agent responses
Validation at each step
Easy integration with downstream systems

Why Mock Clients?

Zero external dependencies means:

No Slack/PagerDuty API rate limits during testing
Deterministic test behavior
Faster test execution
Easier local development

Limitations and Future Work

Current Limitations:

Requires well-structured alert data (severity, service, description)
RCA quality depends on available logs and metrics
Remediation proposals are suggestions, not guaranteed fixes

Future Enhancements:

Multi-model support (GPT-4, Gemini, etc.)
Custom remediation playbooks
Integration with more monitoring systems
Feedback loops to improve RCA accuracy

Contributing

IRAS is open-source and welcomes contributions. Areas for improvement:

Additional test coverage
Performance optimizations
New integrations (monitoring systems, incident management platforms)
Documentation and examples

See the GitHub repo for contribution guidelines.

Conclusion

Incident response doesn't have to be painful. IRAS automates the repetitive parts while keeping humans in control. With 99% test coverage, zero external dependencies, and a production-grade stack, it's ready for real-world use.

If you're tired of 3 AM incident response, give IRAS a try. Your on-call engineer will thank you.

Get started: https://github.com/krishnashakula/IRAS

Have feedback or ideas? Open an issue or PR on GitHub. Let's make incident response less painful for everyone.

IRAS: Building an Autonomous AI Agent for Incident Response

Krishna shakula — Fri, 08 May 2026 02:13:33 +0000

IRAS: Building an Autonomous AI Agent for Incident Response

Incident response is broken. When alerts fire at 3 AM, on-call engineers wake up to handle routine triage, root cause analysis, and remediation planning—work that doesn't require human judgment, just time and attention. IRAS solves this by automating the entire incident response workflow with an autonomous AI agent that keeps humans in control.

The Problem

Most on-call incidents follow a predictable pattern:

Alert fires
Engineer wakes up, triages the alert
Engineer investigates root cause
Engineer creates a remediation plan
Engineer executes the plan
Engineer writes a post-mortem

For routine incidents (disk full, memory leak, failed job retry), steps 1-4 don't require human judgment. They require pattern matching and analysis—exactly what AI is good at. Yet engineers still get paged.

The Solution: IRAS

IRAS is an autonomous AI agent built on production-grade technology:

FastAPI for HTTP endpoints
LangGraph for multi-step agentic workflows
Pydantic AI for structured outputs and validation
Claude (Anthropic) for reasoning and analysis
Python for the entire stack

How It Works

When an alert fires, IRAS executes a fully autonomous workflow:

Alert → Triage → RCA → Remediation Plan → Post-Mortem → Human Approval

Each step is handled by Claude with structured outputs validated by Pydantic. The entire workflow is orchestrated by LangGraph as a state machine with approval gates.

Key metric: Sub-2-minute incident resolution from alert to remediation plan.

Human-in-the-Loop Control

IRAS doesn't execute remediation automatically. Every step requires human approval:

Triage approval: Confirm the incident classification
RCA approval: Confirm the root cause analysis
Remediation approval: Approve the remediation plan before execution
Post-mortem approval: Review the generated post-mortem

AI does the heavy lifting. Humans stay in control.

Production-Grade Reliability

IRAS isn't a prototype. It's built for production:

99% test coverage with 292 passing tests
Zero external test dependencies—mock clients included for local development
Integrated observability: Logging, PagerDuty, Slack support
Fallback mock clients: Test without external services
Docker-ready: Run locally or in production

Testing Strategy

The test suite includes:

Unit tests for each workflow step
Integration tests for the full incident response workflow
Mock PagerDuty and Slack clients for isolated testing
No external service dependencies

Run the full test suite locally:

pytest --cov=iras --cov-report=html

Getting Started

IRAS only requires an Anthropic API key:

git clone https://github.com/krishnashakula/IRAS
cd IRAS
export ANTHROPIC_API_KEY=your_key_here
docker-compose up

The mock clients are enabled by default, so you can test the full workflow without PagerDuty or Slack.

Architecture

IRAS is structured as a LangGraph state machine:

from langgraph.graph import StateGraph

# Define incident state
class IncidentState(TypedDict):
    alert: Alert
    triage: TriageResult
    rca: RCAResult
    remediation_plan: RemediationPlan
    post_mortem: PostMortem
    approvals: Dict[str, bool]

# Build workflow
graph = StateGraph(IncidentState)
graph.add_node("triage", triage_node)
graph.add_node("rca", rca_node)
graph.add_node("remediation", remediation_node)
graph.add_node("post_mortem", post_mortem_node)

# Add approval gates
graph.add_edge("triage", "approval_triage")
graph.add_edge("approval_triage", "rca")
# ... more edges

Each node uses Claude for analysis and Pydantic AI for structured outputs.

Real-World Impact

Reduces MTTR

Mean Time To Resolution drops dramatically. Routine incidents get analyzed in 2 minutes instead of 30 minutes.

Eliminates Routine Wake-Ups

On-call engineers stop getting paged for incidents that don't require human judgment. Only serious incidents or approval decisions wake them up.

Maintains Human Control

Every action requires human approval. AI is a tool, not a replacement.

Comprehensive Post-Mortems

Automatic post-mortem generation means every incident gets documented, even routine ones.

Integration

IRAS integrates with:

PagerDuty: Fetch alerts, update incident status
Slack: Send notifications, get approvals
Mock clients: Test without external services

Why This Matters

Incident response is a solved problem for routine incidents. The analysis is predictable. The remediation is known. The only variable is human approval. IRAS automates the predictable parts and keeps humans in control of the decisions.

For on-call engineers, this means:

Fewer 3 AM wake-ups
Faster incident resolution
Better post-mortems
More time for strategic work

Open Source

IRAS is open source and production-ready. Check it out: https://github.com/krishnashakula/IRAS

Built with Python, FastAPI, LangGraph, Pydantic AI, and Claude. 99% test coverage. Zero external test dependencies. Only requires an Anthropic API key.

Start automating your incident response today.

How I Built an AI Agent That Handles On-Call Incidents and Pauses for Human Approval Before Touching Production

Krishna shakula — Sun, 03 May 2026 20:54:37 +0000

The Problem

It's 3 AM. PagerDuty fires.

You drag yourself to your laptop. Open Grafana. Squint at a spike. Switch to Kibana, filter logs, grep for errors. Cross-reference a recent deployment. Form a hypothesis. Write a Slack message explaining what you found. Wait for someone to approve your fix. Apply it. Verify it worked. Then spend an hour writing a post-mortem that goes into a folder nobody opens.

You do this for every incident. Every single time.

I've been that engineer. So I built IRAS an Intelligent Incident Response Agent System that handles the full first-response lifecycle automatically, and only wakes you up to press Approve.

Here's the architecture, the interesting engineering problems, and the decisions I'd make again (and the ones I wouldn't).

What IRAS Does

When an alert fires, IRAS:

Ingests the alert from any monitoring system Prometheus AlertManager, PagerDuty, Datadog, or a raw JSON webhook
Triages severity (P0–P3) and identifies affected services using Claude Haiku
Gathers context error logs from Elasticsearch/Loki, metrics from Prometheus, recent deployments from GitHub
Runs root-cause analysis with Claude Sonnet, retrying with broader context if confidence is below threshold
Generates a step-by-step remediation plan with rollback commands for every step
Pauses and waits for human approval via Slack or REST API
Applies the fix if approved, or escalates to PagerDuty if rejected/timed out
Writes a structured post-mortem timeline, root cause, resolution, action items stored in PostgreSQL and posted to Slack

Total response time from alert to post-mortem: under 2 minutes.

Here's what that looks like in practice:

Alert: "High error rate on payment-service http_error_rate: 45% (threshold: 5%)"

[10:30:01] ▶ Incident ingested
[10:30:02] ▶ P1 · payment-service · ~5,000 users affected · confidence: 0.9
[10:30:04] ▶ DB connection errors in logs, deployment 2m before alert
[10:30:07] ▶ Root cause: DB connection pool exhausted after canary deploy · confidence: 0.88 ✓
[10:30:09] ▶ 3-step remediation plan ready · low risk · rollback commands included
[10:30:09] ▶ Approval request sent to #incidents  [Approve] [Reject]

  ... engineer reviews and clicks Approve (1m 35s later) ...

[10:31:44] ▶ Step 1/3 increase DB_POOL_SIZE from 10 to 50
[10:31:45] ▶ Step 2/3 rolling restart payment-service pods
[10:31:45] ▶ Step 3/3 verify error rate dropped below 2%
[10:31:46] ▶ Post-mortem written and posted to #incidents
[10:31:46] ▶ Resolved · total response time: 1m 45s

The Architecture

IRAS is a 9-node LangGraph state machine with a FastAPI layer on top.

Alert → Ingest → Triage → Context → RCA → Plan → [YOU ⏸] → Apply → Post-mortem
                              ↑         ↓
                              └── retry if confidence < 0.7

The full system overview:

Alert Sources (PagerDuty / Prometheus / Datadog / any webhook)
        ↓
FastAPI (POST /webhook/alert)
        ↓
LangGraph State Machine
  ├── ingestion        — validate, stamp UUID + timestamp
  ├── triage           — Claude Haiku: P0–P3, affected services
  ├── context_gathering — Claude Haiku + tool calls: logs, metrics, deployments
  ├── rca              — Claude Sonnet: root cause + confidence score
  │       ↓ confidence < 0.7? loop back to context_gathering
  ├── generate_plan    — Claude Sonnet: remediation steps + rollback commands
  ├── approval         — interrupt() ⏸ human-in-the-loop
  │       ↓ approved → apply_remediation
  │       ↓ rejected → escalation
  ├── apply_remediation — execute steps, rollback on failure
  ├── escalation       — PagerDuty trigger + Slack alert
  └── postmortem       — Claude Sonnet: structured post-mortem → PostgreSQL + Slack

Now let me walk through the interesting engineering decisions.

Part 1: The Durable Interrupt Pattern

This is the most technically interesting part of IRAS, and the main reason I chose LangGraph over simpler frameworks.

The problem with polling

The naive approach to human-in-the-loop approval is polling. When the agent needs approval, it writes a flag to a database, sends a Slack message, and then polls in a loop:

# The naive approach DON'T do this
async def approval_node(state):
    await slack.send_approval_message(state["plan"])

    while True:
        decision = await db.get_decision(state["incident_id"])
        if decision is not None:
            return decision
        await asyncio.sleep(5)  # poll every 5 seconds

This breaks the moment the server restarts. The coroutine is gone. The incident is orphaned. The on-call engineer is staring at a dead Slack message with no way to resume.

LangGraph's interrupt() genuine suspension

LangGraph's interrupt() is fundamentally different. It doesn't poll. It doesn't sleep. It genuinely suspends graph execution, serializes the entire state to the checkpointer (PostgreSQL in our case), and returns control to the caller.

# src/iras/graph/nodes/approval.py

from langgraph.types import interrupt, Command
from ..state import IncidentState

async def approval_node(state: IncidentState) -> dict:
    """
    Pauses graph execution and waits for human decision.
    State is checkpointed to PostgreSQL survives server restarts.
    """
    human_decision = interrupt({
        "message": "Remediation plan ready for approval",
        "incident_id": state["incident_id"],
        "severity": state["triage_result"].severity,
        "plan": state["remediation_plan"].model_dump(),
    })

    # Execution resumes HERE after Command(resume=...) is sent
    return {"human_approved": human_decision["approved"]}

When interrupt() is called:

The graph state is serialized to PostgreSQL via AsyncPostgresSaver
The coroutine is suspended
The FastAPI endpoint returns 202 Accepted with the incident_id
The server can restart. The process can crash. The incident is safe.

When the engineer hits POST /incidents/{id}/approve:

# src/iras/api/routes/approval.py

@router.post("/incidents/{incident_id}/approve")
async def approve_incident(incident_id: str, graph=Depends(get_graph)):
    """Resume the paused graph with an approval decision."""
    await graph.ainvoke(
        Command(resume={"approved": True}),
        config={"configurable": {"thread_id": incident_id}}
    )
    return {"incident_id": incident_id, "decision": "approved", "status": "resumed"}

LangGraph reconstructs the graph state from the PostgreSQL checkpoint using thread_id, injects the Command(resume=...), and execution continues exactly where it left off same state, same node, no re-running prior stages.

The checkpointer setup

# src/iras/graph/checkpointer.py

from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
import asyncio

_checkpointer: AsyncPostgresSaver | None = None
_lock = asyncio.Lock()

async def get_checkpointer(postgres_url: str) -> AsyncPostgresSaver:
    """Singleton with asyncio.Lock to prevent double-initialization."""
    global _checkpointer

    async with _lock:
        if _checkpointer is None:
            _checkpointer = AsyncPostgresSaver.from_conn_string(postgres_url)
            await _checkpointer.setup()  # creates checkpoint tables

    return _checkpointer

The singleton + asyncio.Lock() pattern is important here. Without it, multiple concurrent requests during startup can race to initialize the checkpointer, resulting in duplicate table creation attempts.

Timeout monitoring without in-memory state

Because all state is in PostgreSQL, the approval timeout monitor doesn't need in-memory state either:

# src/iras/api/background.py

async def monitor_approval_timeouts(graph, settings):
    """
    Runs as a background task. Queries PostgreSQL for interrupted
    threads that have exceeded their SLA window.
    No in-memory state required survives restarts cleanly.
    """
    while True:
        await asyncio.sleep(60)  # check every minute

        interrupted_incidents = await get_interrupted_incidents()

        for incident in interrupted_incidents:
            timeout = get_timeout_for_severity(incident.severity, settings)
            elapsed = datetime.utcnow() - incident.interrupted_at

            if elapsed > timeout:
                # Escalate by resuming with approved=False
                await graph.ainvoke(
                    Command(resume={"approved": False, "reason": "timeout"}),
                    config={"configurable": {"thread_id": incident.incident_id}}
                )

P0 incidents escalate after 15 minutes. P1–P3 after 2 hours. Configurable via environment variables.

Part 2: Typed Agent Outputs with Pydantic AI

Most AI agent code I've seen looks like this:

response = await llm.generate(prompt)
text = response.content
# Now parse the text... somehow
severity = re.search(r"severity: (P\d)", text).group(1)
confidence = float(re.search(r"confidence: ([\d.]+)", text).group(1))

This is fragile. The model output format drifts. Regex breaks. You get None at 3 AM when you least want it.

IRAS uses Pydantic AI to get strongly-typed, validated outputs directly from every agent. Here's the triage agent:

# src/iras/models/incident.py

from pydantic import BaseModel, Field
from enum import Enum

class Severity(str, Enum):
    P0 = "P0"
    P1 = "P1"
    P2 = "P2"
    P3 = "P3"

class TriageResult(BaseModel):
    severity: Severity
    affected_services: list[str]
    estimated_users_affected: int
    confidence: float = Field(ge=0.0, le=1.0)
    reasoning: str

# src/iras/agents/triage.py

from pydantic_ai import Agent
from ..models.incident import TriageResult

triage_agent = Agent(
    model="claude-haiku-4-5",
    result_type=TriageResult,  # Pydantic AI validates and parses this automatically
    system_prompt="""
    You are a production incident triage specialist.
    Classify the incident severity, identify affected services,
    estimate user impact, and provide a confidence score.

    Severity guide:
    - P0: Complete service outage, all users affected
    - P1: Major degradation, >20% of users affected  
    - P2: Partial degradation, <20% of users affected
    - P3: Warning or informational, no user impact
    """
)

async def run_triage(alert_payload: dict) -> TriageResult:
    result = await triage_agent.run(str(alert_payload))
    return result.data  # TriageResult fully validated, type-safe

Every stage follows this pattern. The RCA agent returns a RootCauseHypothesis. The remediation agent returns a RemediationPlan. The post-mortem agent returns a PostMortem. The rest of the graph code is just Python no parsing, no regex, no json.loads() on LLM output.

# src/iras/models/incident.py (continued)

class RootCauseHypothesis(BaseModel):
    primary_cause: str
    contributing_factors: list[str]
    evidence: list[str]          # specific log lines or metric values
    confidence: float = Field(ge=0.0, le=1.0)
    recommended_investigation: str

class RemediationStep(BaseModel):
    action: str
    rollback_command: str
    risk_level: Literal["low", "medium", "high"]
    estimated_duration_seconds: int

class RemediationPlan(BaseModel):
    steps: list[RemediationStep]
    overall_risk: Literal["low", "medium", "high"]
    reversible: bool
    requires_human_approval: bool
    estimated_total_duration_seconds: int

class PostMortem(BaseModel):
    incident_id: str
    severity: Severity
    timeline: list[str]
    root_cause_summary: str
    resolution_summary: str
    action_items: list[str]
    total_duration_minutes: float
    resolved: bool

Model selection per agent

Each agent instantiates its own model. This matters:

# Fast and cheap for classification tasks
triage_agent = Agent(model="claude-haiku-4-5", result_type=TriageResult, ...)
context_agent = Agent(model="claude-haiku-4-5", result_type=ContextBundle, ...)

# Slower and more capable for deep reasoning
rca_agent = Agent(model="claude-sonnet-4-5", result_type=RootCauseHypothesis, ...)
remediation_agent = Agent(model="claude-sonnet-4-5", result_type=RemediationPlan, ...)
postmortem_agent = Agent(model="claude-sonnet-4-5", result_type=PostMortem, ...)

Haiku costs roughly 20x less than Sonnet and is fast enough for triage and context gathering. Sonnet is worth the cost for RCA and remediation planning these are the decisions that affect production.

Part 3: The Confidence-Gated RCA Retry Loop

Root cause analysis is genuinely hard. The first attempt often doesn't have enough evidence. IRAS handles this with a confidence-gated retry loop baked into the LangGraph conditional edges:

# src/iras/graph/nodes/rca.py

async def rca_node(state: IncidentState) -> IncidentState:
    hypothesis = await run_rca(
        context=state["context_bundle"],
        alert=state["alert_payload"],
        attempt=state.get("rca_attempts", 0)
    )

    return {
        **state,
        "rca_hypothesis": hypothesis,
        "rca_attempts": state.get("rca_attempts", 0) + 1,
    }

def should_retry_rca(state: IncidentState) -> str:
    """Conditional edge: decides what happens after RCA."""
    hypothesis = state["rca_hypothesis"]
    attempts = state.get("rca_attempts", 0)
    max_attempts = state["settings"].rca_max_attempts
    threshold = state["settings"].rca_confidence_threshold

    if hypothesis.confidence >= threshold:
        return "generate_plan"          # confidence is good, proceed
    elif attempts < max_attempts:
        return "context_gathering"      # loop back for more evidence
    else:
        return "escalation"             # exhausted retries, escalate

# src/iras/graph/builder.py

graph.add_conditional_edges(
    "rca",
    should_retry_rca,
    {
        "generate_plan": "generate_plan",
        "context_gathering": "context_gathering",
        "escalation": "escalation",
    }
)

On retry, the context agent widens its evidence window pulling a longer log time range and more deployment history. This typically lifts confidence from 0.5–0.6 to above 0.7 on the second attempt.

Default thresholds: confidence >= 0.7 to proceed, max 3 RCA attempts before auto-escalation.

Part 4: We Don't Trust the Model

This is the part I'm most proud of and that I think most AI agent projects get wrong.

When you're building an agent that can modify production systems, the model's output isn't just text it's an instruction set. You need to treat it like untrusted input.

Safety invariants enforced in code

Two rules apply to every remediation plan, regardless of what the model returns:

# src/iras/graph/nodes/generate_plan.py

async def generate_plan_node(state: IncidentState) -> IncidentState:
    plan = await run_remediation_agent(
        hypothesis=state["rca_hypothesis"],
        context=state["context_bundle"],
    )

    # SAFETY RULE 1: Any high-risk step forces human approval.
    # The model cannot classify all steps as "low" to bypass this.
    if any(step.risk_level == "high" for step in plan.steps):
        plan.requires_human_approval = True

    # SAFETY RULE 2: Any step without a rollback command marks
    # the plan as irreversible and forces human approval.
    if any(not step.rollback_command.strip() for step in plan.steps):
        plan.reversible = False
        plan.requires_human_approval = True

    return {**state, "remediation_plan": plan}

These are not prompts. They're not suggestions. They run on every plan output, unconditionally.

Adversarial test scenarios

The stress test suite includes 47 scenarios specifically designed to test model misbehavior:

# tests/stress/test_adversarial.py

class TestAdversarialModelOutputs:

    async def test_model_lies_about_risk_level(self, graph, mock_claude):
        """Model claims all steps are low-risk to bypass approval."""
        mock_claude.remediation_returns(RemediationPlan(
            steps=[
                RemediationStep(
                    action="delete all pods",
                    rollback_command="",         # empty rollback
                    risk_level="low",            # model lying
                    estimated_duration_seconds=5,
                )
            ],
            overall_risk="low",
            reversible=True,
            requires_human_approval=False,       # model bypassing approval
        ))

        result = await graph.ainvoke(make_incident_state())

        # Safety invariants caught it
        assert result["remediation_plan"].requires_human_approval is True
        assert result["remediation_plan"].reversible is False

    async def test_all_context_tools_fail(self, graph, mock_tools):
        """All external integrations return errors simultaneously."""
        mock_tools.logs.raises(ConnectionError("Elasticsearch down"))
        mock_tools.metrics.raises(ConnectionError("Prometheus down"))
        mock_tools.deployments.raises(ConnectionError("GitHub API rate limited"))

        # Should degrade gracefully, not crash
        result = await graph.ainvoke(make_incident_state())
        assert result["status"] != "crashed"
        assert result["context_bundle"] is not None  # empty but valid

    async def test_twenty_concurrent_incidents(self, graph):
        """No state contamination between concurrent incident graphs."""
        incidents = [make_incident_state(f"incident-{i}") for i in range(20)]
        results = await asyncio.gather(*[
            graph.ainvoke(state) for state in incidents
        ])

        # Every incident has its own isolated state
        incident_ids = [r["incident_id"] for r in results]
        assert len(set(incident_ids)) == 20  # all unique

292 tests total, 99% coverage. The test suite takes about 30 seconds to run.

Part 5: The Context Gathering Agent (Tool Calls)

The context agent uses Claude Haiku with tool calling to gather evidence from three sources simultaneously:

# src/iras/agents/context_gathering.py

from pydantic_ai import Agent
from pydantic_ai.tools import Tool
from ..models.incident import ContextBundle
from ..deps import ContextDeps

context_agent = Agent(
    model="claude-haiku-4-5",
    result_type=ContextBundle,
    deps_type=ContextDeps,
    system_prompt="""
    You are an SRE context gathering specialist.
    Use the available tools to collect evidence about the incident.
    Fetch logs, metrics, and deployment history for the affected service.
    Bundle all evidence into a structured ContextBundle.
    """
)

@context_agent.tool
async def fetch_logs(ctx, service: str, time_range_minutes: int = 30) -> list[str]:
    """Fetch recent error and warning logs for a service."""
    return await ctx.deps.log_client.get_logs(
        service=service,
        time_range_minutes=time_range_minutes,
        levels=["ERROR", "WARN"],
    )

@context_agent.tool
async def fetch_metrics(ctx, service: str) -> dict:
    """Fetch current metrics vs 7-day baseline for a service."""
    return await ctx.deps.metrics_client.get_comparison(
        service=service,
        metrics=["error_rate", "latency_p99", "request_rate", "cpu_usage"],
    )

@context_agent.tool
async def fetch_deployments(ctx, service: str, hours: int = 24) -> list[dict]:
    """Fetch recent deployments for a service from GitHub."""
    return await ctx.deps.deployment_client.get_recent(
        service=service,
        hours=hours,
    )

Each tool has a Mock*Client fallback. If ELASTICSEARCH_BASE_URL isn't set, a mock client returns realistic fake data. This means the full graph runs end-to-end with only two environment variables: ANTHROPIC_API_KEY and POSTGRES_URL.

Dependency injection

Tool clients are injected via ContextDeps, making them swappable in tests:

# src/iras/agents/deps.py

from dataclasses import dataclass
from ..tools.log_fetcher import LogClient, MockLogClient
from ..tools.metrics import MetricsClient, MockMetricsClient
from ..tools.deployment import DeploymentClient, MockDeploymentClient

@dataclass
class ContextDeps:
    log_client: LogClient | MockLogClient
    metrics_client: MetricsClient | MockMetricsClient
    deployment_client: DeploymentClient | MockDeploymentClient

def make_context_deps(settings) -> ContextDeps:
    """Returns real or mock clients based on environment config."""
    return ContextDeps(
        log_client=LogClient(settings.elasticsearch_url) 
                   if settings.elasticsearch_url 
                   else MockLogClient(),
        metrics_client=MetricsClient(settings.prometheus_url)
                       if settings.prometheus_url
                       else MockMetricsClient(),
        deployment_client=DeploymentClient(settings.github_token)
                          if settings.github_token
                          else MockDeploymentClient(),
    )

Part 6: The LangGraph State Machine

The full graph wiring:

# src/iras/graph/builder.py

from langgraph.graph import StateGraph, START, END
from .state import IncidentState
from .nodes import (
    ingestion, triage, context_gathering, rca,
    generate_plan, approval, apply_remediation,
    escalation, postmortem
)

def build_graph(checkpointer) -> CompiledGraph:
    builder = StateGraph(IncidentState)

    # Add nodes
    builder.add_node("ingestion", ingestion.run)
    builder.add_node("triage", triage.run)
    builder.add_node("context_gathering", context_gathering.run)
    builder.add_node("rca", rca.run)
    builder.add_node("generate_plan", generate_plan.run)
    builder.add_node("approval", approval.run)
    builder.add_node("apply_remediation", apply_remediation.run)
    builder.add_node("escalation", escalation.run)
    builder.add_node("postmortem", postmortem.run)

    # Linear edges
    builder.add_edge(START, "ingestion")
    builder.add_edge("ingestion", "triage")
    builder.add_edge("triage", "context_gathering")
    builder.add_edge("context_gathering", "rca")

    # Confidence-gated RCA retry loop
    builder.add_conditional_edges(
        "rca",
        should_retry_rca,
        {
            "generate_plan": "generate_plan",
            "context_gathering": "context_gathering",
            "escalation": "escalation",
        }
    )

    # Human approval branch
    builder.add_edge("generate_plan", "approval")
    builder.add_conditional_edges(
        "approval",
        lambda state: "apply_remediation" if state["human_approved"] else "escalation",
        {
            "apply_remediation": "apply_remediation",
            "escalation": "escalation",
        }
    )

    # Both paths converge at postmortem
    builder.add_edge("apply_remediation", "postmortem")
    builder.add_edge("escalation", "postmortem")
    builder.add_edge("postmortem", END)

    return builder.compile(
        checkpointer=checkpointer,
        interrupt_before=["approval"],  # pause before the approval node
    )

One important detail: interrupt_before=["approval"] tells LangGraph to checkpoint state before entering the approval node, not inside it. This means the plan is fully generated and the Slack message is sent before the graph suspends.

Running It

Only two things required:

git clone https://github.com/krishnashakula/IRAS.git && cd IRAS

# Start Postgres
docker run -d --name iras-postgres \
  -e POSTGRES_USER=iras -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=iras \
  -p 5432:5432 postgres:16

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

cp .env.example .env
# Set ANTHROPIC_API_KEY and POSTGRES_URL

python run.py

Then fire a test alert:

curl -X POST http://localhost:8000/webhook/alert \
  -H "Content-Type: application/json" \
  -d '{
    "title": "High error rate on payment-service",
    "timestamp": "2026-05-03T10:30:00Z",
    "service": "payment-service",
    "error_rate": 0.45
  }'

# {"incident_id": "550e8400-...", "status": "processing"}

# Approve the plan (or wait for the Slack message if configured)
curl -X POST http://localhost:8000/incidents/550e8400-.../approve

What I'd Do Differently

1. Start with MemorySaver, not PostgreSQL

For local development and prototyping, LangGraph's MemorySaver (in-memory checkpointer) is much faster to set up. I spent time early on getting Postgres running when I didn't need durability yet. Start with MemorySaver, switch to AsyncPostgresSaver when you're ready for production.

2. Separate trace IDs from thread IDs

IRAS uses the same UUID for the HTTP response incident_id, the LangGraph thread_id, and the database primary key. Convenient, but it creates coupling. If you ever want to re-run an incident or fork a graph for testing, you'll want these to be different.

3. Add streaming earlier

The graph produces intermediate outputs (triage result, context bundle, etc.) as it runs. Currently these are only visible via LangSmith traces. Adding Server-Sent Events to stream node outputs to a UI would make the "watching it work" experience much better.

Key Takeaways

LangGraph's interrupt() is not a workaround it's a first-class primitive for durable human-in-the-loop workflows. If you're building agents that need human approval in production, this is the pattern.
Pydantic AI's typed outputs eliminate an entire class of bugs. Parsing LLM output with regex or manual JSON extraction is fragile. Defining your output schema as a Pydantic model and letting the framework handle parsing is strictly better.
Safety invariants belong in code, not prompts. Prompting the model to be safe is not enough when the output drives production changes. Enforce your invariants programmatically, after the model responds.
Mock clients everywhere. If every external integration falls back to a mock, the full system is testable with zero infrastructure. This pays for itself immediately in CI speed and developer experience.