DEV Community: Aaron VanSledright

Build a Live Site Monitoring Dashboard in 100 Lines of Python

Aaron VanSledright — Thu, 07 May 2026 17:32:08 +0000

There's a class of internal tool that's perpetually under-built: the "look at this metric across our things" dashboard. Status of the deploy. Score of the SEO audit. Latency of the regional endpoints. We treat these like full-stack projects when they should be one Python file.

This post walks through a 95-line single-file Flask dashboard I built to monitor SEO scores across a list of URLs. The same architecture works for any periodic JSON endpoint — score cards with deltas and sparklines, auto-refresh in the browser, runs anywhere Flask runs.

You can use the live version right now without signing up for anything: https://seoscoreapi.com/demo/dashboard. And the entire source is one downloadable file: /downloads/dashboard.py.

What we're building

A page that:

Polls a list of URLs every N minutes through an external API
Renders one card per URL with score, grade, delta vs. previous poll, category breakdown, and a 30-day sparkline
Highlights cards green/yellow/red based on score movement
Auto-refreshes in the browser via meta tag (no JS framework)
Caches results in memory so the page renders instantly even when the API call is mid-flight

No build step. No webpack. No Redis. No celery. One Python file.

The data source

I'm using SEO Score API because it's what I work on, but the pattern is identical for any JSON API that returns a numeric score per URL plus a timeseries endpoint for history. If you're following along with a different API, swap the two SDK calls (audit() and history()) for whatever your data source provides.

Install:

pip install flask seoscoreapi

The architecture in three pieces

A shared state dict mapping URL → latest result, guarded by a lock.
A background polling thread that walks the URL list, calls the API, and writes into the state dict.
A Flask route that reads the state dict and renders an HTML template.

Every other piece — the sparkline math, the category breakdown, the auto-refresh — is template stuff. The architecture is just three things.

The state dict

state = {url: {"loading": True} for url in URLS}
state_lock = threading.Lock()

That's the entire data model. The dict is keyed by URL; values are whatever the latest poll produced. Initial state is {"loading": True} for each URL, which the template can render as a loading state until the first real poll completes.

The lock is necessary because the background thread writes while the Flask route reads. Both happen on different threads.

The polling function

def refresh_one(url):
    """Run an audit + fetch history for one URL, store result in `state`."""
    try:
        result = audit(url, api_key=API_KEY)
        hist = history(url, api_key=API_KEY, limit=30).get("series", [])
        prev = state.get(url, {}).get("score")
        delta = (result["score"] - prev) if prev is not None else None
        with state_lock:
            state[url] = {
                "score": result["score"],
                "grade": result["grade"],
                "categories": {k: v.get("score") for k, v in result.get("audit", {}).items()},
                "delta": delta,
                "status": status_for(delta),
                "spark": [h["score"] for h in hist[-30:]],
                "fetched_at": datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC"),
                "error": None,
            }
    except Exception as e:
        with state_lock:
            state[url] = {**state.get(url, {}), "error": str(e), "status": "error"}

Two API calls per URL. audit() returns the current score and category breakdown; history() returns the timeseries for the sparkline. The delta is computed by subtracting the previous score (held in the state dict from the last poll) from the new one.

The try/except is intentional. Exceptions during a poll shouldn't kill the thread — they should mark the card as error and let the next poll retry.

The polling loop

def poll_loop():
    while True:
        for url in URLS:
            refresh_one(url)
        time.sleep(POLL_INTERVAL)


threading.Thread(target=poll_loop, daemon=True).start()

A daemon thread that walks the URL list serially and sleeps between cycles. Sequential, not concurrent, on purpose: it's polite to the API and the dashboard's job isn't to hammer.

For a small URL list (< 25 URLs polled every 15 min) one thread is plenty. If you need to monitor hundreds of URLs, swap the inner loop for concurrent.futures.ThreadPoolExecutor(max_workers=10). But check your API's rate limit first.

The Flask route

@app.route("/")
def home():
    with state_lock:
        return render_template_string(TEMPLATE, state=dict(state))

That's it. The route copies the state dict (cheap, ~hundreds of small dicts) under the lock and renders. The page never waits on the API — it always returns whatever the last poll produced. If a poll is in flight, the user sees yesterday's number with yesterday's timestamp; if it's fresh, they see the latest.

The status colors

def status_for(delta):
    if delta is None:
        return "neutral"
    if delta <= -5:
        return "critical"
    if delta < 0:
        return "warning"
    return "ok"

A single function decides the card color. -5 or worse is red, any negative is yellow, anything else is green. The thresholds are arbitrary; tune to your data.

The sparkline

The sparkline is an inline SVG <polyline> with points computed in the Jinja template:

<svg viewBox="0 0 100 30" preserveAspectRatio="none" width="100%">
  <polyline fill="none" stroke="#60a5fa" stroke-width="1.5"
    points="{% for s in data.spark %}{{ loop.index0 * (100 / (data.spark|length - 1)) }},{{ 30 - (s * 0.3) }} {% endfor %}" />
</svg>

Two things make this work:

viewBox="0 0 100 30" plus preserveAspectRatio="none" lets the SVG stretch to whatever width the card is, without distorting the line in any meaningful way.
The y-coordinate 30 - score * 0.3 works because scores are 0–100 and we want them on a 0–30 viewBox. For a different range, normalize the values first or change the multiplier.

That's the whole sparkline. No Chart.js, no D3, no canvas tricks. Inline SVG is underrated for this kind of single-purpose visualization.

The auto-refresh

<meta http-equiv="refresh" content="60">

Yes, a <meta refresh> tag. It works perfectly for this use case and requires zero JavaScript. The browser refreshes the page every 60 seconds; the route reads the latest state dict; you see fresh data.

If you need finer control (e.g., update without losing scroll position) you'd swap this for a small fetch() polling loop. For a hallway-TV dashboard, the meta refresh is fine.

The full file

About 95 lines including the template:

import os
import threading
import time
from datetime import datetime

from flask import Flask, render_template_string
from seoscoreapi import audit, history

API_KEY = os.environ["SEOSCORE_API_KEY"]
URLS = [u.strip() for u in os.environ["DASHBOARD_URLS"].split(",") if u.strip()]
POLL_INTERVAL = int(os.getenv("POLL_INTERVAL_SECONDS", "900"))

app = Flask(__name__)
state = {url: {"loading": True} for url in URLS}
state_lock = threading.Lock()


def status_for(delta):
    if delta is None: return "neutral"
    if delta <= -5: return "critical"
    if delta < 0: return "warning"
    return "ok"


def refresh_one(url):
    try:
        result = audit(url, api_key=API_KEY)
        hist = history(url, api_key=API_KEY, limit=30).get("series", [])
        prev = state.get(url, {}).get("score")
        delta = (result["score"] - prev) if prev is not None else None
        with state_lock:
            state[url] = {
                "score": result["score"],
                "grade": result["grade"],
                "categories": {k: v.get("score") for k, v in result.get("audit", {}).items()},
                "delta": delta,
                "status": status_for(delta),
                "spark": [h["score"] for h in hist[-30:]],
                "fetched_at": datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC"),
                "error": None,
            }
    except Exception as e:
        with state_lock:
            state[url] = {**state.get(url, {}), "error": str(e), "status": "error"}


def poll_loop():
    while True:
        for url in URLS:
            refresh_one(url)
        time.sleep(POLL_INTERVAL)


threading.Thread(target=poll_loop, daemon=True).start()


TEMPLATE = """..."""  # see full source for the HTML


@app.route("/")
def home():
    with state_lock:
        return render_template_string(TEMPLATE, state=dict(state))


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)

The HTML template is roughly 50 lines of Jinja + CSS — readable, no framework, no build step. Grab the full file here.

Running it

export SEOSCORE_API_KEY=sk_your_key_here
export DASHBOARD_URLS="https://yoursite.com,https://yoursite.com/pricing"
python dashboard.py

Open http://localhost:8080. The first poll runs immediately, so within a few seconds the cards populate.

Deploying it

Three lines of Dockerfile:

FROM python:3.12-slim
RUN pip install flask seoscoreapi
COPY dashboard.py /app/dashboard.py
ENV SEOSCORE_API_KEY="" DASHBOARD_URLS=""
CMD python /app/dashboard.py

Drop on Fly.io, Railway, a Pi, a $5 VPS, or a Kubernetes pod. Stateless — just provision env vars and go.

Where to extend it

Three extensions I get asked about, all in 5–10 lines on top of the baseline:

1. Webhook alerts on regression

Add to refresh_one:

if delta is not None and delta <= -5:
    requests.post(SLACK_WEBHOOK, json={
        "text": f":warning: {url} dropped {delta} points to {result['score']}"
    })

2. Per-URL alert thresholds

Replace URLS with a config dict:

URLS = {
    "https://yoursite.com": {"critical_drop": 3, "warning_drop": 1},
    "https://yourblog.com": {"critical_drop": 8, "warning_drop": 4},
}

Then status_for(delta, thresholds) checks the per-URL values.

3. Multi-team views

Add a ?team=growth query param. URLs gain a team field. The route filters:

team = request.args.get("team")
filtered = {u: d for u, d in state.items() if not team or d.get("team") == team}

Same dashboard instance serves every team's view.

What I'd do differently for production

If this dashboard graduated from "office hallway TV" to "monitoring our customer-facing thing", I'd change three things:

Persist state to SQLite. The current dict gets wiped on restart. SQLite adds maybe 10 lines and means the dashboard remembers history across deploys.
Switch sequential polling to a thread pool. For 100+ URLs, sequential is too slow.
Move the meta refresh to a fetch() loop. Avoids losing scroll position on long pages and lets us update without a full reload.

None of these are necessary for the v0. Premature complexity is its own problem.

The takeaway

You don't need a SaaS observability product to know when one of your metrics regresses. A Flask file, an external API, and 30 minutes is enough for most internal monitoring needs. The interesting bits — the polling pattern, the inline SVG sparkline, the meta refresh — are decades-old techniques that still work fine.

The full source: https://seoscoreapi.com/downloads/dashboard.py
The live demo: https://seoscoreapi.com/demo/dashboard

If you build something interesting on top of this, I'd love to see it.

Build a Live Site Monitoring Dashboard in 100 Lines of Python

Aaron VanSledright — Thu, 07 May 2026 17:32:08 +0000

You can use the live version right now without signing up for anything: https://seoscoreapi.com/demo/dashboard. And the entire source is one downloadable file: /downloads/dashboard.py.

What we're building

A page that:

Polls a list of URLs every N minutes through an external API
Renders one card per URL with score, grade, delta vs. previous poll, category breakdown, and a 30-day sparkline
Highlights cards green/yellow/red based on score movement
Auto-refreshes in the browser via meta tag (no JS framework)
Caches results in memory so the page renders instantly even when the API call is mid-flight

No build step. No webpack. No Redis. No celery. One Python file.

The data source

Install:

pip install flask seoscoreapi

The architecture in three pieces

A shared state dict mapping URL → latest result, guarded by a lock.
A background polling thread that walks the URL list, calls the API, and writes into the state dict.
A Flask route that reads the state dict and renders an HTML template.

Every other piece — the sparkline math, the category breakdown, the auto-refresh — is template stuff. The architecture is just three things.

The state dict

state = {url: {"loading": True} for url in URLS}
state_lock = threading.Lock()

The lock is necessary because the background thread writes while the Flask route reads. Both happen on different threads.

The polling function

def refresh_one(url):
    """Run an audit + fetch history for one URL, store result in `state`."""
    try:
        result = audit(url, api_key=API_KEY)
        hist = history(url, api_key=API_KEY, limit=30).get("series", [])
        prev = state.get(url, {}).get("score")
        delta = (result["score"] - prev) if prev is not None else None
        with state_lock:
            state[url] = {
                "score": result["score"],
                "grade": result["grade"],
                "categories": {k: v.get("score") for k, v in result.get("audit", {}).items()},
                "delta": delta,
                "status": status_for(delta),
                "spark": [h["score"] for h in hist[-30:]],
                "fetched_at": datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC"),
                "error": None,
            }
    except Exception as e:
        with state_lock:
            state[url] = {**state.get(url, {}), "error": str(e), "status": "error"}

The try/except is intentional. Exceptions during a poll shouldn't kill the thread — they should mark the card as error and let the next poll retry.

The polling loop

def poll_loop():
    while True:
        for url in URLS:
            refresh_one(url)
        time.sleep(POLL_INTERVAL)


threading.Thread(target=poll_loop, daemon=True).start()

A daemon thread that walks the URL list serially and sleeps between cycles. Sequential, not concurrent, on purpose: it's polite to the API and the dashboard's job isn't to hammer.

The Flask route

@app.route("/")
def home():
    with state_lock:
        return render_template_string(TEMPLATE, state=dict(state))

The status colors

def status_for(delta):
    if delta is None:
        return "neutral"
    if delta <= -5:
        return "critical"
    if delta < 0:
        return "warning"
    return "ok"

A single function decides the card color. -5 or worse is red, any negative is yellow, anything else is green. The thresholds are arbitrary; tune to your data.

The sparkline

The sparkline is an inline SVG <polyline> with points computed in the Jinja template:

<svg viewBox="0 0 100 30" preserveAspectRatio="none" width="100%">
  <polyline fill="none" stroke="#60a5fa" stroke-width="1.5"
    points="{% for s in data.spark %}{{ loop.index0 * (100 / (data.spark|length - 1)) }},{{ 30 - (s * 0.3) }} {% endfor %}" />
</svg>

Two things make this work:

viewBox="0 0 100 30" plus preserveAspectRatio="none" lets the SVG stretch to whatever width the card is, without distorting the line in any meaningful way.
The y-coordinate 30 - score * 0.3 works because scores are 0–100 and we want them on a 0–30 viewBox. For a different range, normalize the values first or change the multiplier.

That's the whole sparkline. No Chart.js, no D3, no canvas tricks. Inline SVG is underrated for this kind of single-purpose visualization.

The auto-refresh

<meta http-equiv="refresh" content="60">

If you need finer control (e.g., update without losing scroll position) you'd swap this for a small fetch() polling loop. For a hallway-TV dashboard, the meta refresh is fine.

The full file

About 95 lines including the template:

import os
import threading
import time
from datetime import datetime

from flask import Flask, render_template_string
from seoscoreapi import audit, history

API_KEY = os.environ["SEOSCORE_API_KEY"]
URLS = [u.strip() for u in os.environ["DASHBOARD_URLS"].split(",") if u.strip()]
POLL_INTERVAL = int(os.getenv("POLL_INTERVAL_SECONDS", "900"))

app = Flask(__name__)
state = {url: {"loading": True} for url in URLS}
state_lock = threading.Lock()


def status_for(delta):
    if delta is None: return "neutral"
    if delta <= -5: return "critical"
    if delta < 0: return "warning"
    return "ok"


def refresh_one(url):
    try:
        result = audit(url, api_key=API_KEY)
        hist = history(url, api_key=API_KEY, limit=30).get("series", [])
        prev = state.get(url, {}).get("score")
        delta = (result["score"] - prev) if prev is not None else None
        with state_lock:
            state[url] = {
                "score": result["score"],
                "grade": result["grade"],
                "categories": {k: v.get("score") for k, v in result.get("audit", {}).items()},
                "delta": delta,
                "status": status_for(delta),
                "spark": [h["score"] for h in hist[-30:]],
                "fetched_at": datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC"),
                "error": None,
            }
    except Exception as e:
        with state_lock:
            state[url] = {**state.get(url, {}), "error": str(e), "status": "error"}


def poll_loop():
    while True:
        for url in URLS:
            refresh_one(url)
        time.sleep(POLL_INTERVAL)


threading.Thread(target=poll_loop, daemon=True).start()


TEMPLATE = """..."""  # see full source for the HTML


@app.route("/")
def home():
    with state_lock:
        return render_template_string(TEMPLATE, state=dict(state))


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)

The HTML template is roughly 50 lines of Jinja + CSS — readable, no framework, no build step. Grab the full file here.

Running it

export SEOSCORE_API_KEY=sk_your_key_here
export DASHBOARD_URLS="https://yoursite.com,https://yoursite.com/pricing"
python dashboard.py

Open http://localhost:8080. The first poll runs immediately, so within a few seconds the cards populate.

Deploying it

Three lines of Dockerfile:

FROM python:3.12-slim
RUN pip install flask seoscoreapi
COPY dashboard.py /app/dashboard.py
ENV SEOSCORE_API_KEY="" DASHBOARD_URLS=""
CMD python /app/dashboard.py

Drop on Fly.io, Railway, a Pi, a $5 VPS, or a Kubernetes pod. Stateless — just provision env vars and go.

Where to extend it

Three extensions I get asked about, all in 5–10 lines on top of the baseline:

1. Webhook alerts on regression

Add to refresh_one:

if delta is not None and delta <= -5:
    requests.post(SLACK_WEBHOOK, json={
        "text": f":warning: {url} dropped {delta} points to {result['score']}"
    })

2. Per-URL alert thresholds

Replace URLS with a config dict:

URLS = {
    "https://yoursite.com": {"critical_drop": 3, "warning_drop": 1},
    "https://yourblog.com": {"critical_drop": 8, "warning_drop": 4},
}

Then status_for(delta, thresholds) checks the per-URL values.

3. Multi-team views

Add a ?team=growth query param. URLs gain a team field. The route filters:

team = request.args.get("team")
filtered = {u: d for u, d in state.items() if not team or d.get("team") == team}

Same dashboard instance serves every team's view.

What I'd do differently for production

If this dashboard graduated from "office hallway TV" to "monitoring our customer-facing thing", I'd change three things:

Persist state to SQLite. The current dict gets wiped on restart. SQLite adds maybe 10 lines and means the dashboard remembers history across deploys.
Switch sequential polling to a thread pool. For 100+ URLs, sequential is too slow.
Move the meta refresh to a fetch() loop. Avoids losing scroll position on long pages and lets us update without a full reload.

None of these are necessary for the v0. Premature complexity is its own problem.

The takeaway

The full source: https://seoscoreapi.com/downloads/dashboard.py
The live demo: https://seoscoreapi.com/demo/dashboard

If you build something interesting on top of this, I'd love to see it.

I built a WordPress Plugin For Generating Images With Nano Banana

Aaron VanSledright — Thu, 19 Mar 2026 16:49:09 +0000

AI is every where. Accept it. Anyway, I had a random thought last night about having a WordPress plugin that allows you to generate images on the fly for your posts. Pictures increase engagement on posts so, what if we just inline Nano Banana directly into Gutenberg?

This morning I built this plugin which is a simple API call to Google’s Gemini AI Studio through a Gutenberg block.

Type your prompt
Choose your model
Hit generate
Insert Simple!

Once the image is inserted into the post it turns the block into a standard image block so its as easy to manage as any other image.

I submitted the plugin to the official WordPress repository but it takes a while to get approved. So, if you want to add it to your own WordPress instance feel free to message me and I’ll give you access to the repository!

I Built an AI-Powered WordPress Hosting Platform — Here's Why

Aaron VanSledright — Fri, 13 Mar 2026 21:14:52 +0000

I'm a cloud architect by day. I've spent 6+ years designing infrastructure on AWS for enterprise clients — the kind of environments where uptime, security, and scalability aren't optional.

But I kept noticing something. The people who needed solid web hosting the most — small business owners, freelancers, entrepreneurs — were stuck choosing between two bad options:

Cheap shared hosting that's slow, insecure, and breaks at the worst possible times
Expensive managed platforms that charge a premium for infrastructure that costs a fraction of the price

So I built something in between.

What It Does

The platform spins up a fully configured WordPress site on its own dedicated AWS infrastructure. No shared servers, no noisy neighbors. Each site gets:

Its own isolated environment running on AWS
SSL certificates configured automatically
AI-generated themes so you're not starting from a blank screen
A site that's ready to go in under a minute

The AI piece isn't a gimmick — it generates a custom WordPress theme based on your business, so you skip the hours of digging through starter themes and tweaking settings before you can even start adding content.

The Architecture (For the Curious)

Under the hood, the platform uses a Golden AMI strategy. Instead of bootstrapping a fresh server every time (installing WordPress, configuring Apache, setting up the database, etc.), I pre-bake all of that into a machine image. When a new site is requested, it launches from that image with everything already in place.

This brings deployment time down to about 30–45 seconds from request to live site.

Each tenant gets:

A dedicated EC2 instance launched from the Golden AMI
MariaDB running locally (keeps costs low and latency minimal)
Let's Encrypt SSL via automated provisioning
Infrastructure managed entirely with Terraform

The AI theme generation runs through Amazon Bedrock (Claude Sonnet), which generates a complete WordPress theme — style.css, template files, functions.php — based on the business type and preferences provided during setup.

Why Not Just Use [Insert Platform Here]?

Fair question. Here's the honest answer:

vs. Shared hosting (Bluehost, GoDaddy, etc.): Those environments pack hundreds of sites onto the same server. Performance degrades, security is shared-risk, and you have zero control. This platform gives each site its own isolated infrastructure.

vs. Managed WordPress (WP Engine, Kinsta, Flywheel): Great products, but they charge $30–$100+/month for what is fundamentally commodity infrastructure with a management layer on top. This platform delivers a comparable experience at a lower price point because the architecture is designed to be cost-efficient from the ground up.

vs. Page builders (Wix, Squarespace): Those aren't WordPress. If you want the flexibility of the WordPress ecosystem — plugins, themes, WooCommerce, full code access — you need actual WordPress hosting. This gives you that without the setup headache.

What I Learned Building It

A few things that might be useful if you're building a similar platform:

Golden AMIs save everything. I originally prototyped with a bootstrap-on-launch approach (user-data scripts installing WordPress, configuring Apache, etc.). It was slow (~5 minutes) and fragile. Pre-baking everything into an AMI cut that to under a minute and eliminated an entire category of deployment failures.

MariaDB on EC2 > Aurora for this use case. Aurora is amazing for multi-tenant databases at scale, but for a platform where each tenant has their own instance, running MariaDB locally is dramatically cheaper and simpler. Per-tenant cost dropped to around $20/month, which makes even the lowest pricing tier profitable.

AI theme generation needs guardrails. The first version would occasionally generate themes with broken PHP or CSS that didn't render correctly. Adding validation steps and a structured prompt template with explicit file-by-file output instructions fixed about 95% of those issues.

Let's Encrypt automation is non-negotiable. Manual SSL setup is a support nightmare. Automating certificate provisioning and renewal during the deployment process eliminated what would have been a constant stream of support tickets.

What's Next

The platform is live and I'm onboarding early users. The roadmap includes:

One-click staging environments — clone your site for testing before pushing changes live
Automated backups with one-click restore
A theme marketplace where AI-generated themes can be saved, shared, and reused
WooCommerce quick-start — pre-configured e-commerce setup with AI-generated product pages

Try It / Get In Touch

If you're interested in checking it out, the platform is running under 45Squared. I'm actively looking for early adopters and feedback.

If you're a developer building something similar, happy to chat architecture — drop a comment or reach out.

I'm Aaron, a cloud architect and the founder of 45Squared. I build tools that make AWS infrastructure accessible to people who shouldn't have to think about infrastructure.

I Replaced My Agent Framework With Markdown Files and 140 Lines of Python

Aaron VanSledright — Wed, 11 Mar 2026 21:58:41 +0000

Every AI agent framework I tried added complexity I didn't need. LangChain, CrewAI, AutoGen — they're powerful, but for deploying a Slack bot that answers questions using a few tools, I was pulling in hundreds of dependencies to do something boto3 already handles natively.

So I built something different: a Terraform module where agent behavior lives in markdown files, tools are plain Python functions, and the entire runtime engine is ~140 lines of code with zero external dependencies.

I open-sourced it: terraform-module-markdown-agent

The Problem With Agent Frameworks

Most agent frameworks want to own your entire stack. You get:

Heavyweight dependencies — hundreds of packages for what amounts to a loop calling an LLM
Framework lock-in — custom decorators, base classes, and abstractions that couple your business logic to the framework
Deployment friction — designed for containers or servers, not serverless
Opaque behavior — hard to debug when the agent does something unexpected because the prompt is buried in framework internals

If you're running agents on AWS Lambda with Bedrock, you already have boto3. The Bedrock Converse API handles tool use natively. The framework is mostly just getting in the way.

The Core Idea: Markdown as Configuration

What if agent behavior was just a markdown file?

---
name: support-agent
version: 1.0.0
description: "Handles customer support queries"
tags: [support, customer]
---

# Support Agent

## When to Use
Activated for all customer-facing support requests.

## Process
1. Greet the customer
2. Use `search_docs` to find relevant documentation
3. If the issue requires escalation, use `create_ticket`
4. Summarize the resolution

## Guardrails
- Never share internal pricing or roadmap details
- Always confirm before creating tickets
- Keep responses under 3 paragraphs

This markdown file is the system prompt. The frontmatter provides metadata for routing. The sections give the LLM structured instructions. You can read it, diff it, review it in a PR — no code changes needed to adjust agent behavior.

How the Runtime Works

The engine is a simple loop:

Load the skill markdown file as the system prompt
Append any shared rules (company context, formatting guidelines)
Call bedrock-runtime.converse() with the user message and tool specs
If the model wants to use a tool, route it to the handler function
Feed the tool result back and loop
Return the final text response

Here's the actual function signature:

from runtime.engine import run_agent

result = run_agent(
    skill_name="support-agent",
    user_input="I can't log in to my account",
    tool_specs=my_tool_specs,
    tool_handler=my_handler,
    history=conversation_history,
)

The full engine handles Bedrock throttling with exponential backoff, safe error messages (no internal details leaked to users), a max-turns safety limit, and S3 or local filesystem skill loading. And it does all of this in ~140 lines using only boto3.

Tools Are Just Functions

No decorators. No base classes. Define a JSON schema for Bedrock's tool spec, write a Python function, register it:

# tools/specs/support.py
SUPPORT_TOOL_SPECS = [
    {
        "toolSpec": {
            "name": "search_docs",
            "description": "Search the knowledge base",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string", "description": "Search query"}
                    },
                    "required": ["query"]
                }
            }
        }
    }
]

# tools/support.py
def search_docs(query: str) -> str:
    # Your actual search logic here
    results = my_search_index.query(query, limit=5)
    return json.dumps(results)

# tools/registry.py
TOOL_HANDLERS = {
    "search_docs": lambda name, inp: search_docs(**inp),
}

That's it. The registry is a dictionary. The spec is JSON. The handler is a function. You can test each piece independently.

Multi-Agent Delegation

A coordinator skill can delegate to specialized sub-skills:

---
name: coordinator
version: 1.0.0
description: Routes requests to specialized agents
---

# Coordinator

## Process
1. Analyze the user's request
2. Delegate to `support-agent` for customer issues
3. Delegate to `ops-agent` for infrastructure questions
4. Handle general conversation directly

The delegate_to_skill tool handles the routing. Recursion depth is limited (default: 3 levels) to prevent infinite loops between skills.

What Terraform Deploys

The module provisions everything you need:

Resource	Purpose
Lambda Function + Layer	Agent runtime
IAM Role	Least-privilege Bedrock + DynamoDB access
API Gateway (optional)	HTTP endpoint for Slack webhooks
DynamoDB Table (optional)	Thread-based conversation memory
EventBridge Rules (optional)	Scheduled agent tasks (cron)

module "agent" {
  source = "github.com/45squaredLLC/terraform-module-markdown-agent"

  name        = "support-agent"
  environment = "prod"

  source_dir       = "${path.module}/src"
  layer_path       = "${path.module}/dist/layer.zip"
  bedrock_model_id = "us.anthropic.claude-sonnet-4-5-20250929-v1:0"

  ssm_parameter_prefixes = ["/support-agent/slack/*"]

  enable_api_gateway  = true
  enable_memory_table = true
}

terraform apply and you have a working agent with an HTTPS endpoint, conversation memory, and IAM policies scoped to exactly what it needs.

Conversation Memory

DynamoDB stores conversation history per Slack thread:

Partition key: THREAD#{thread_id}
Sort key: MSG#{timestamp}#{uuid} (collision-safe)
TTL: Auto-expires after 30 days (configurable)
Cap: 100 messages per thread to stay within context windows

The runtime loads history automatically when processing a message in an existing thread. No session management code needed.

Scheduled Agents

Need an agent that runs on a cron schedule? EventBridge handles it:

scheduled_tasks = [
  {
    name                = "daily-report"
    schedule_expression = "cron(0 13 * * ? *)"
    input = {
      source        = "scheduled"
      task          = "daily-report"
      slack_channel = "C123ABC"
      prompt        = "Generate the daily operations summary"
    }
  }
]

Same agent, same skills, same tools — just triggered by a schedule instead of a Slack message.

Project Structure

src/
├── orchestrator/
│   ├── handler.py        # Lambda entry point
│   └── agent.py          # Wires skills + tools
├── runtime/              # Provided by the module
│   ├── engine.py         # ~140-line Bedrock Converse loop
│   ├── handler.py        # Slack event handling
│   ├── memory.py         # DynamoDB conversation store
│   └── delegation.py     # Skill-to-skill routing
├── skills/
│   ├── coordinator.md    # Entry point skill
│   └── support-agent.md  # Domain skill
├── rules/
│   └── formatting.md     # Shared context
└── tools/
    ├── registry.py       # Tool routing
    ├── specs/
    │   └── support.py    # Tool JSON schemas
    └── support.py        # Tool implementations

Changing agent behavior = editing a markdown file. Adding a tool = writing a function + JSON schema. No framework upgrades, no breaking API changes.

Security

A few things I cared about getting right:

IAM scoping: Policies are locked to the deployment region and specific resource ARNs. Bedrock access is limited to Anthropic models only.
Skill validation: Skill names are regex-validated to prevent path traversal. S3-loaded skills are size-limited to 1MB.
Tool error isolation: Internal errors return only the exception type to the model — no stack traces or secrets leak into responses.
Slack verification: HMAC-SHA256 signature verification runs before any event processing.
SSM least-privilege: Lambda can only read the specific SSM parameter prefixes you declare.

When To Use This (and When Not To)

Good fit:

Slack bots and chat agents on AWS
Agents with a handful of well-defined tools
Teams that want agent behavior in version-controlled markdown
Serverless-first deployments

Look elsewhere if:

You need multi-model orchestration (different LLMs per step)
Your agent requires complex stateful workflows with branching
You're not on AWS or don't want Bedrock

Getting Started

# Clone the example
git clone https://github.com/AIOpsCrew/terraform-module-markdown-agent
cd terraform-module-markdown-agent/examples/slack-bot

# Build the Lambda layer
bash ../../scripts/build_layer.sh .

# Deploy
terraform init
terraform apply

The example includes a working Slack bot with get_time and get_weather tools. Swap the skills and tools for your use case.

The repo is Apache 2.0 licensed. If you're building agents on AWS and tired of fighting frameworks, give it a look: [github.com/AIOpsCrew/terraform-module-markdown-agent(https://github.com/AIOpsCrew/terraform-module-markdown-agent)

Questions or feedback? Drop a comment or open an issue.

How We Cut 500 Unnecessary Contact Center Transfers With a $48 AWS Architecture Change

Aaron VanSledright — Tue, 10 Mar 2026 16:18:21 +0000

Most Amazon Lex failures aren't Lex failures.

They're speech-to-text failures that Lex gets blamed for.

I want to walk through a real production problem we solved recently — a contact center bot that worked perfectly in testing and fell apart the moment real customers picked up the phone.

The Problem

A client was running Amazon Lex as the front line of their customer-facing voice bot. Thousands of calls per month — routing inquiries, collecting account info, resolving common requests without human agents.

In QA: flawless.

In production: chaos.

Callers were phoning in from cars, construction sites, busy restaurants, and airports. Background noise was destroying speech-to-text accuracy. Lex couldn't match the right intent. Callers got stuck in retry loops, gave up, or got dumped to a live agent — exactly the outcome the bot was built to prevent.

The client estimated ~5% of all calls were being unnecessarily transferred to human agents due to noisy transcriptions. At 10,000 calls per month, that's 500 avoidable transfers — each one consuming agent time, increasing wait queues, and frustrating customers.

Why This Happens

The default Amazon Lex architecture bundles speech-to-text (STT) and natural language understanding (NLU) into a single pipeline. You send audio in, Lex gives you an intent back. Clean and simple.

The problem is that Lex's built-in STT isn't optimized for real-world telephony noise. It's designed for reasonably clean audio. The moment you introduce background noise — wind, traffic, restaurant ambience — transcription quality degrades, and bad transcriptions produce wrong intents or no match at all.

Before (default architecture):

Audio → Lex (STT + NLU)
          ↓
   Garbled transcription
          ↓
   Wrong intent matched
          ↓
   Agent transfer ❌

The fix isn't to retrain your bot. The fix is to separate the concerns.

The Solution: Decouple STT From NLU

Amazon Transcribe is purpose-built for telephony audio. It uses a separate acoustic model trained on phone-quality audio with background noise, and it significantly outperforms Lex's built-in STT in noisy environments.

The architecture change is straightforward:

Route audio to Amazon Transcribe instead of Lex directly
Get clean text back from Transcribe
Pass that clean text to Lex via RecognizeText (NLU only — no STT)
Lambda orchestrates the handoff between the two services

After (decoupled architecture):

Audio → Transcribe (STT)
          ↓
      Clean text
          ↓
  Lex RecognizeText (NLU only)
          ↓
   Correct intent matched ✅

The Lambda function sitting in the middle looks roughly like this:

import boto3

transcribe_client = boto3.client('transcribe-streaming')
lex_client = boto3.client('lexv2-runtime')

def process_utterance(audio_stream, session_id, bot_id, bot_alias_id, locale_id):
    # Step 1: Transcribe audio to text
    transcription = transcribe_audio(audio_stream)
    clean_text = transcription['results']['transcripts'][0]['transcript']

    # Step 2: Send clean text to Lex for intent matching
    lex_response = lex_client.recognize_text(
        botId=bot_id,
        botAliasId=bot_alias_id,
        localeId=locale_id,
        sessionId=session_id,
        text=clean_text
    )

    return lex_response

Note: The actual streaming implementation uses StartStreamTranscription for real-time audio — the above is simplified for clarity.

Observability: Don't Ship Blind

One thing we added alongside the architecture change was proper CloudWatch instrumentation. The original setup had almost no visibility into why calls were failing — just that they were.

We added custom metrics for:

Transcription confidence scores per utterance
Intent match rate vs. fallback rate
Utterances that hit the noise threshold and triggered a retry
Transfer rate by hour of day (useful for spotting shift patterns)

This gave the client's ops team actual dashboards to monitor bot health in real time — something they'd never had before.

The Results

Metric	Before	After
Unnecessary agent transfers	~500/month	Near zero
Agent time wasted	$1,000+/month	Recovered
Additional AWS cost	—	~$48/month
Added latency per utterance	—	100–400ms

The 100–400ms latency increase from adding Transcribe in the loop was imperceptible to callers. We monitored it closely for the first two weeks post-deploy and received zero complaints.

What This Pattern Is Good For

This decoupled STT + NLU pattern is worth knowing about any time you're running Lex in environments where:

Callers are mobile (driving, outside, in transit)
Your customer base includes call centers or field workers
You're seeing high fallback/retry rates that don't correlate with bad intents
You have multilingual requirements (Transcribe has broader language support than Lex's built-in STT)

It's also a cleaner architecture for testing — you can unit test your NLU layer independently of audio input, which makes bot development significantly faster.

Cost Breakdown

Amazon Transcribe Streaming is billed per second of audio transcribed (~$0.024/min). At 10,000 calls averaging 3 minutes of active speech:

10,000 calls × 3 min × $0.024 = ~$720/month

But you're already paying for Lex's built-in STT in the per-request pricing. The net delta ends up around $48/month for this client's volume — a rounding error compared to the agent time recovered.

TL;DR

Amazon Lex's built-in STT struggles with real-world background noise
Decouple STT (Amazon Transcribe) from NLU (Lex RecognizeText) using Lambda
Add CloudWatch metrics so you can actually see what's happening
500 fewer transfers/month, $1,000+ saved, $48 in additional AWS costs

Full case study with architecture diagrams is on the 45Squared blog. The technical deep dive including the full Lambda implementation is on AIOPSCrew.com.

Building on Amazon Connect or Lex and running into similar issues? I do fixed-scope Architecture Sprints — production-ready in 2 weeks, fixed price, no retainer. Feel free to reach out.