Building AI Agents — A Practitioner’s Guide for Software Engineers & Architects
About This Course
Who This Is For
Software engineers and architects who want a working catalogue of AI agent patterns to embed into their existing SDLC, not another LLM primer.
What “Way” Means Here
Each entry is a distinct agent you can build: its trigger, its inputs, the action it takes, and the metric (DORA, NFR, MTTR, coverage) it moves.
How to Use This
Pick one agent per sprint. Start with read-only/advisory mode, graduate to auto-action once trust and guardrails are in place.
Outcome
A portfolio of 100 agent patterns spanning the full engineering lifecycle, plus 3 documented cases of agents shipped in production.
Chapter Road Map
Ch 1–2
The Pull Request
Agents that review, gate, and create pull requests — the highest-leverage automation surface in any engineering org.
Ch 3–4
Keeping Systems Current
Version-upgrade agents and pipeline agents that keep services modern and builds green without manual toil.
Ch 5–6
Quality & Reliability
Agents that generate and prune tests, and agents that triage, diagnose, and remediate production incidents.
Ch 7–8
Trust & Memory
Security/compliance agents that enforce guardrails, and documentation agents that keep institutional knowledge fresh.
Ch 9–10
Architecture & Scale
Agents that govern design decisions, plus the orchestration patterns that let many agents work together safely.
01
The pull request is the single most agent-friendly checkpoint in software delivery: it has a clear input (a diff), a clear output (approve/block/comment), and a clear NFR to optimize for — review latency without sacrificing defect escape rate.
1.1Static-Analysis-Gated Auto-Review Agent
Wires SAST/lint output into a PR webhook handler that posts inline comments and blocks merge once severity crosses a configured threshold, removing first-pass review toil from humans entirely.
1.2LLM Diff-Reasoning Review Agent
Feeds the unified diff plus surrounding repo context (imports, call sites, ADRs) to an LLM constrained by a review rubric, then posts structured, file-anchored comments via the GitHub/GitLab review API.
1.3Risk-Scoring Auto-Approval Gate
Computes a change-risk score from files touched, blast radius, historical defect density per module, and PR size, then auto-approves and fast-tracks merges that fall below the risk floor.
1.4Convention & ADR Conformance Agent
Validates a PR against architecture decision records and coding standards encoded as machine-readable rules, flagging drift from agreed patterns before a human reviewer even opens the diff.
1.5Test-Coverage-Delta Agent
Diffs coverage reports pre/post-PR, identifies newly added uncovered branches, and comments with the exact test stubs needed to close the gap, optionally opening a follow-up commit.
1.6Secrets & Critical-CVE Veto Agent
Runs gitleaks/Trivy-class scanners as a mandatory check that vetoes merge outright on detected secrets or critical-severity CVEs, with no override path except a documented security exception.
1.7Reviewer Routing & Expertise-Graph Agent
Combines CODEOWNERS with a learned expertise graph (who has touched this module, who resolved similar bugs) to assign the optimal human reviewer and auto-escalate on SLA breach.
1.8Merge-Train Conflict-Resolution Agent
Runs inside a merge queue to auto-rebase, resolve trivial textual conflicts, and re-trigger CI, cutting the manual “rebase and re-push” loop out of high-traffic repositories.
1.9Changelog & Release-Note Synthesis Agent
Aggregates merged PR titles, labels, and diffs since the last tag into a semantic-version-tagged changelog, separating breaking changes, features, and fixes automatically.
1.10Post-Merge Regression Watcher Agent
Watches canary and deployment metrics for a window after a merge lands, correlates anomalies back to the specific PR, and auto-opens a revert PR when a regression signal crosses threshold.
02
If review agents protect the merge gate, creation agents attack the other end: turning tickets, errors, and schedules directly into draft PRs so engineers start from a working diff instead of a blank file.
2.1Issue-to-PR Agent
Reads a Jira/Linear ticket, plans an implementation against the codebase, opens a branch, writes the change, and raises a draft PR linked back to the ticket for human refinement.
2.2Dependency-Bump PR Agent
A Renovate/Dependabot-style agent that opens PRs for outdated packages, summarizes the upstream changelog and breaking changes, and auto-merges patch-level bumps that pass CI.
2.3Scheduled Refactor-Discovery Agent
Periodically scans for duplication, dead code, and rising cyclomatic complexity, then raises small, reviewable refactor PRs rather than one unreviewable mega-diff.
2.4Bug-Fix-from-Stack-Trace Agent
Ingests a production stack trace and error-tracker context (Sentry/Datadog), locates the root cause via repo search and call-graph traversal, and proposes a fix PR with a regression test.
2.5Service-Scaffolding Agent
Generates a new service skeleton — controller, service, repository layers, CI config, Dockerfile — from an internal template on a single Slack or CLI command.
2.6Cherry-Pick & Backport Agent
Watches for commits labeled “backport-needed” and automatically cherry-picks them onto active release branches, opening one PR per target branch.
2.7Commit Message & PR Description Agent
Generates conventional-commit-formatted messages and structured PR descriptions (what/why/how-tested/risk) directly from the diff, replacing the blank-description anti-pattern.
2.8Feature-Flag Wiring Agent
Detects new code paths in a diff and automatically wraps them in the team’s feature-flag SDK calls, opening the matching flag-config PR in the flag-management repo.
2.9API-Contract Sync Agent
Detects OpenAPI/protobuf schema changes in a service and raises companion PRs that regenerate and update dependent client SDKs across consuming repositories.
2.10Migration-Script Generation Agent
Diffs ORM model changes and produces a database migration PR with both the forward migration and a tested rollback script, reducing a common source of production incidents.
03
Version drift is one of the largest hidden NFR risks in an org — EOL runtimes, unpatched frameworks, deprecated APIs. These agents turn upgrades from a quarterly fire-drill into continuous, low-risk background work.
3.1Runtime/Language Upgrade Agent
Applies rule-based source transformations (OpenRewrite-style recipes) to move a codebase across major language versions — e.g. Java 8 to 21 — and opens the upgrade as a reviewable PR.
3.2Framework Migration Agent
Applies codemods for major framework jumps such as Spring Boot 2→3 or Django LTS bumps, rewriting config, annotations, and deprecated method calls in one pass.
3.3Deprecated-API Replacement Agent
Scans for calls to APIs flagged deprecated in the current or next runtime version and applies the documented safe replacement, validating each substitution against the test suite.
3.4Monorepo Dependency-Sequencing Agent
Builds the internal dependency graph across a monorepo or service fleet and sequences upgrade PRs in topological order so downstream services never upgrade ahead of an incompatible upstream.
3.5Build-Tool Migration Agent
Converts build configuration between tooling generations — Maven to Gradle, npm to pnpm — and validates the converted build produces an identical artifact before opening the PR.
3.6License & Compliance-Drift Agent
Checks every transitive dependency pulled in by an upgrade against an approved-license allowlist and flags newly introduced copyleft or incompatible licenses before merge.
3.7Performance-Regression Gate Agent
Runs an automated before/after benchmark suite on every version-bump PR and blocks merge if latency, throughput, or memory regress beyond a configured tolerance.
3.8Ephemeral-Sandbox Validation Agent
Spins up a short-lived containerized environment running the full integration suite against the upgraded stack, giving a high-confidence signal before the PR ever reaches a human reviewer.
3.9EOL & CVE-Tracking Agent
Continuously cross-references the service inventory against vendor EOL calendars and CVE feeds, proactively opening tickets and draft PRs well ahead of a forced, urgent migration.
3.10Fleet-Wide Upgrade Orchestrator
Coordinates a phased rollout of a version bump across hundreds of services — canary cohort first, automatic pause on error-budget burn, staged expansion, and a one-click rollback gate.
04
A pipeline is a deterministic state machine an agent can reason about directly — parsing logs, bisecting failures, and making release-gating decisions far faster than a human paging through a build dashboard.
4.1Flaky-Test Detection & Quarantine Agent
Tracks pass/fail variance per test across runs, statistically identifies flaky tests, and auto-quarantines them into a non-blocking suite while opening a ticket with the flake signature.
4.2Build-Failure Root-Cause Agent
Parses build logs, correlates the failure to the specific commit via automated bisection, and posts a root-cause summary directly on the offending PR instead of a raw stack dump.
4.3Pipeline Self-Healing Agent
Distinguishes infra-flake failures (network timeout, runner OOM) from real failures and automatically retries with backoff or reschedules to a healthier runner pool, without human intervention.
4.4Test-Impact Selection Agent
Builds a code-to-test dependency map and runs only the subset of tests actually impacted by a given diff, cutting CI wall-clock time on large monorepos by an order of magnitude.
4.5Artifact & SBOM Generation Agent
Produces a software bill of materials and provenance attestation for every build artifact automatically, satisfying supply-chain security NFRs without a manual compliance step.
4.6Progressive-Delivery Agent
Drives canary or blue/green rollouts, automatically widening traffic share as health metrics stay green and halting or rolling back the moment an SLO is threatened.
4.7CI Cost-Optimization Agent
Analyzes runner utilization and cache hit rates, right-sizes runner pools, and restructures pipeline caching to cut CI spend without lengthening build time.
4.8Pipeline-as-Code Governance Agent
Lints pipeline definitions (GitHub Actions, GitLab CI, Jenkinsfile) against an org-wide policy — mandatory security scan stages, approval gates — and blocks non-compliant pipeline changes.
4.9Cross-Service Release Orchestration Agent
Sequences a multi-service release in dependency order, waiting for each service’s health checks before triggering the next, replacing a manually coordinated release calendar.
4.10SLO-Burn-Rate Rollback Agent
Monitors error-budget burn rate immediately after a deploy and automatically triggers a rollback the moment burn rate exceeds the threshold defined in the service’s SLO policy.
05
Test suites are an NFR in their own right — coverage, signal-to-noise, and execution time all compound. Agents here both grow and prune the suite, and verify that the suite itself is trustworthy.
5.1Unit-Test Generation Agent
Generates unit tests for uncovered code paths and validates each candidate test with mutation testing before proposing it, so generated tests genuinely improve fault-detection rather than just inflating a coverage number.
5.2Property-Based Test Discovery Agent
Infers invariants from function signatures and existing assertions, then generates property-based tests (Hypothesis/QuickCheck-style) that explore the input space rather than fixed examples.
5.3Integration-Test Synthesis Agent
Reads OpenAPI/gRPC contracts and generates end-to-end integration tests covering happy-path, edge-case, and error-response scenarios for every defined endpoint.
5.4Autonomous Exploratory UI Agent
Drives a headless browser through click-paths it discovers itself, captures visual diffs against a baseline, and files defect reports with reproduction steps for anything anomalous.
5.5Synthetic Test-Data Generation Agent
Generates realistic, schema-valid, privacy-safe synthetic fixtures for staging and test environments, removing the need to copy production data for testing.
5.6Regression-Suite Pruning Agent
Identifies redundant tests that never independently catch a real defect and proposes their removal, keeping suite execution time low without sacrificing fault coverage.
5.7Consumer-Driven Contract Testing Agent
Generates and maintains Pact-style consumer contracts automatically as client code evolves, and verifies provider services against every active contract on each deploy.
5.8Load/Performance Test Generation Agent
Derives realistic load profiles from production traffic patterns and generates k6/Gatling-style load test scripts targeting the NFRs defined for a given service.
5.9Mutation-Testing Quality Agent
Continuously runs mutation testing on critical modules and reports a mutation score, surfacing exactly which “covered” lines actually have no meaningful assertion behind them.
5.10Accessibility & Compliance Testing Agent
Runs automated WCAG audits on every UI PR and blocks merge on new accessibility regressions, attaching the specific axe-core violation and a suggested fix.
06
MTTR is the NFR most directly improved by agents: triage, correlation across telemetry, and remediation are exactly the kind of pattern-matching-at-scale work LLM-driven agents are well-suited to.
6.1Alert Triage & Deduplication Agent
Clusters correlated alerts from multiple monitoring tools into a single incident, suppresses duplicate noise, and pages only the on-call owner of the actual root system.
6.2Cross-Signal Root-Cause Agent
Correlates logs, traces, and metrics around an incident’s start time to propose a ranked list of probable root causes before a human even joins the incident channel.
6.3Auto-Remediation Runbook Agent
Matches an incident’s signature against a library of runbooks and executes pre-approved remediation steps — restart, scale-out, cache-flush — within tightly scoped guardrails.
6.4Incident-Commander Copilot Agent
Maintains the incident timeline automatically from chat and system events, drafts status-page updates, and reminds the commander of unaddressed checklist items in real time.
6.5Postmortem Generation Agent
Assembles a first-draft postmortem from the incident timeline, relevant deploys, and root-cause findings, leaving the team to refine and add action items rather than write from scratch.
6.6Capacity-Forecasting Agent
Projects resource exhaustion (storage, connection pools, queue depth) from historical growth trends and opens a capacity-planning ticket well before the limit is hit.
6.7SLO Burn-Rate Watchdog Agent
Continuously evaluates multi-window burn-rate alerts against each service’s SLO and escalates only when burn rate indicates a genuine error-budget threat, cutting alert fatigue.
6.8Log-Anomaly Detection Agent
Builds a baseline of normal log patterns per service and flags statistically anomalous sequences in real time, catching novel failure modes that static alert rules miss.
6.9On-Call Knowledge Retrieval Agent
A RAG agent over runbooks, past incidents, and architecture docs that answers an on-call engineer’s question in-context inside the incident channel during an active page.
6.10Chaos-Experiment Design Agent
Proposes targeted chaos-engineering experiments based on a service’s dependency graph and historical incident causes, then schedules them in a controlled blast-radius window.
07
Security agents earn trust by being narrow, auditable, and reversible first — these patterns are deliberately scoped to enforce policy and reduce toil without becoming an unbounded autonomous actor on production systems.
7.1SAST/DAST Triage Agent
Deduplicates findings across multiple scanners, ranks them by real exploitability rather than raw CVSS score, and routes only actionable findings to engineering queues.
7.2Secrets-Rotation Agent
Detects credentials approaching expiry or flagged as exposed, rotates them through the secrets manager, and updates every consuming service’s configuration automatically.
7.3Policy-as-Code IaC Gate Agent
Evaluates Terraform/Kubernetes manifests against OPA/Conftest policies before apply, blocking infrastructure changes that violate network, IAM, or encryption-at-rest requirements.
7.4Dependency-Vulnerability Patch Agent
Cross-references the dependency tree against a CVE feed, opens patch PRs for affected packages ranked by exploitability, and verifies the patched build still passes CI.
7.5Least-Privilege Access-Review Agent
Analyzes actual IAM usage against granted permissions and proposes scoped-down policy diffs for roles holding unused privileges, with human approval required before applying.
7.6Threat-Modeling Assistant Agent
Generates a first-draft STRIDE-style threat model from a service’s architecture diagram and data-flow description, which architects then refine in design review.
7.7Compliance Evidence-Collection Agent
Continuously gathers and timestamps audit evidence (access logs, change approvals, scan results) for SOC 2/ISO 27001 controls, replacing a manual quarterly evidence scramble.
7.8PII/Data-Classification Scanning Agent
Scans schemas, logs, and data stores for unclassified PII fields and proposes classification tags and masking rules before sensitive data reaches a non-production environment.
7.9Container-Image Hardening Agent
Analyzes Dockerfiles for unnecessary attack surface — root user, unpinned base images, unused packages — and opens a hardened-image PR with the resulting layer-size and CVE-count diff.
7.10Adversarial Prompt-Testing Agent
Red-teams an org’s own AI-enabled features with adversarial and jailbreak-style prompts before launch, reporting failure modes back to the owning team as a structured test report.
08
Documentation decays the moment code changes; these agents treat docs as a build artifact regenerated from source, and treat institutional knowledge as a retrievable, queryable system rather than a stale wiki.
8.1API-Docs Generation Agent
Regenerates API reference documentation directly from OpenAPI/protobuf source on every merge, eliminating the gap between what the docs say and what the service actually does.
8.2ADR-Drafting Agent
Detects a significant architectural change in a PR (new datastore, new external dependency, breaking API change) and drafts an architecture decision record for the team to finalize.
8.3Code-to-Diagram Agent
Generates sequence and component diagrams directly from call-graph and dependency analysis, keeping architecture diagrams synchronized with the actual code instead of a static slide.
8.4Onboarding Knowledge-Base Agent
Builds a living onboarding guide per service by combining README content, recent PR history, and common Slack questions into a single, continuously refreshed reference.
8.5Stale-Docs Detection Agent
Diffs documentation claims against the current codebase and flags documentation that references removed functions, renamed endpoints, or deprecated configuration.
8.6Internal RAG Search Agent
Indexes repos, wikis, and design docs into a retrieval-augmented search agent that answers engineering questions with citations back to the source document, not a hallucinated guess.
8.7Runbook Generation Agent
Synthesizes a draft operational runbook for a new service from its deployment config, alerting rules, and dependency list, ready for an SRE to validate and finalize.
8.8Domain-Model Extraction Agent
Mines the codebase’s entities, value objects, and bounded contexts into a living glossary and domain model, helping new architects understand the system’s actual ubiquitous language.
8.9Meeting-to-Spec Agent
Transcribes a design discussion and converts it into a structured technical spec draft with decisions, open questions, and action items clearly separated for the team to review.
8.10Customer-Facing Release-Notes Agent
Translates internal, engineering-flavored changelogs into customer-facing release notes in plain language, filtering out internal-only changes automatically.
09
For architects specifically, agents shift from “write code” to “govern the shape of the system” — enforcing conformance, surfacing debt, and reviewing designs before a single line is written.
9.1Architecture-Conformance Checking Agent
Statically validates that actual module dependencies match an approved target architecture (e.g. a C4 container diagram) and flags unauthorized cross-layer or cross-service calls.
9.2Coupling & Cycle-Detection Agent
Analyzes the module dependency graph for cyclic dependencies and excessive coupling, surfacing the specific edges that should be broken before they harden into a structural problem.
9.3API-Design Linting Agent
Validates new REST/GraphQL endpoint designs against the org’s API style guide — naming, pagination, error envelope, versioning — before the contract is finalized and built against.
9.4Cost & Capacity Modeling Agent
Estimates the infrastructure cost and capacity profile of a proposed design from its data volume and traffic assumptions, surfacing cost outliers during design review rather than at the cloud bill.
9.5Tech-Debt Quantification Agent
Scores modules on a composite tech-debt index (churn, complexity, test gaps, incident history) and ranks them so architects can prioritize remediation by actual risk, not gut feel.
9.6Service-Boundary Recommendation Agent
Analyzes data access patterns and call frequency to recommend domain-driven service boundaries when splitting a monolith, flagging where a proposed split would create a chatty interface.
9.7Design-Review Copilot Agent
Pre-reads a design doc against the org’s NFR checklist and prior incident postmortems, surfacing relevant precedent and unanswered questions before the live design review starts.
9.8Schema-Evolution Agent
Validates proposed schema changes for backward compatibility against every known consumer, flagging breaking changes and proposing an expand-contract migration path automatically.
9.9NFR Verification Agent
Checks a service’s actual measured latency, availability, and throughput against the NFRs declared in its design doc, flagging the gap before it becomes a customer-facing SLA breach.
9.10Reference-Architecture Generator Agent
Given a workload profile (read-heavy, event-driven, batch), proposes a reference architecture from the org’s approved patterns library, complete with the relevant ADRs pre-linked.
10
Once an org has a dozen single-purpose agents from chapters 1–9, the engineering problem becomes orchestration: planning, tool-use, memory, guardrails, and evaluation across many agents acting on the same codebase.
10.1Supervisor-Worker Orchestrator Pattern
A planning agent decomposes a goal (e.g. “upgrade and ship”) into subtasks dispatched to specialized worker agents from earlier chapters, then aggregates their results into one coherent action.
10.2Tool-Use / Function-Calling Framework Design
Defines a typed, narrowly scoped tool interface (read-repo, run-tests, open-pr, query-metrics) that every agent calls through, keeping each agent’s capability surface auditable and bounded.
10.3Human-in-the-Loop Approval Gateway Pattern
Routes any agent action above a defined blast-radius threshold (production deploy, data deletion, access grant) through a mandatory human approval step before execution.
10.4Long-Running Memory & Context Management
Maintains durable, retrievable state (decisions made, files touched, open questions) across a multi-day agent task so context isn’t lost between sessions or after a context-window reset.
10.5Agent Evaluation Harness Agent
Runs every agent against a fixed regression suite of past tasks before each prompt or tool-set change ships, catching capability regressions the same way a CI suite catches code regressions.
10.6Guardrails & Sandboxing for Code-Executing Agents
Runs any agent that executes generated code inside an isolated, network-restricted, resource-capped sandbox, with every action logged for audit before results are trusted.
10.7Internal Developer Platform (IDP) Integration
Exposes the agent fleet through the org’s existing IDP (Backstage-style catalog) so engineers invoke agents the same way they invoke any other golden-path platform capability.
10.8Cost & Token-Budget Governance Agent
Tracks token and compute spend per agent and per team against budget, throttling or routing to a cheaper model tier automatically when a budget threshold is approached.
10.9Multi-Repo Coordination Agent
Coordinates a single logical change that spans multiple repositories — shared library bump plus every consumer update — opening and tracking the full set of PRs as one unit of work.
10.10ChatOps-Native Agent Interface Pattern
Surfaces the entire agent fleet through Slack/Teams slash-commands and threaded conversations, so engineers trigger and monitor agent work without leaving their existing chat tool.
★ Real-World Reference Implementations
Three documented, production-deployed cases where an AI agent was built and shipped to achieve a specific software-engineering goal — useful as proof points and as design references when pitching an agent investment internally.
Meta · Engineering Productivity
TestGen-LLM / Automated Compliance Hardening
An agent pipeline that generates candidate unit tests for existing code, filters them by build success, pass rate, and coverage improvement, and lands only the tests that clear every bar — deployed against real production codebases at Meta as part of its automated test-improvement research.
arxiv.org/abs/2402.09171 →
Amazon · AWS
Amazon Q Developer — Java Version-Upgrade Agent
An agent that performs automated end-to-end application upgrades (notably Java version migrations such as Java 8/11 to 17), analyzing the codebase, applying transformation rules, running tests, and opening the upgrade as a reviewable change — used internally at Amazon before being offered as a managed AWS capability.
aws.amazon.com/q/developer →
GitHub · Security
GitHub Copilot Autofix for CodeQL Findings
An agent that takes a CodeQL-detected vulnerability, generates a targeted code fix with explanation, and proposes it directly as a suggested change on the pull request or alert, aimed at closing the gap between vulnerability detection and actual remediation in real repositories.
github.blog/copilot-autofix →