Infrastructure Agents Guide

How to design, build, and operate AI agents for infrastructure teams — safely.

AI agents can write IaC, fix compliance findings, detect drift, review PRs, and respond to incidents — all autonomously. But autonomy without guardrails is a liability. Agents that can terraform apply can also terraform destroy. Agents that read configs can leak secrets. Agents that loop can burn budgets.

This guide covers every architectural decision you need to make when building infrastructure agents — with real patterns, code snippets, multiple alternatives, and the risk framework to evaluate your choices.

If you're looking for the broader, non-infrastructure version, see the Enterprise Agent Guide.

If you want to see these patterns implemented in a real product, see OpenGeni and its open-source repository, which packages this guide's architecture into a proven stack for infrastructure agents.

Who This Is For

• Platform engineers evaluating whether to build or buy agent capabilities
• SREs designing safe automation for incident response and remediation
• DevOps leads building self-service IaC platforms
• Engineering leaders who need a reviewed architecture for AI-driven infrastructure

Guide Structure

Core Principles

1. Agents Default to PR-First Change Control — Every infrastructure change flows through a pull request. The agent produces diffs, not deployments. If you support direct execution at all, treat it as a separate break-glass architecture with separate credentials, approval paths, and audit controls.
2. Least Privilege by Default — Agents get the minimum credentials and tool access needed. Privileges are scoped, time-limited, and auditable.
3. Observability Is Not Optional — Every tool call, credential request, and decision point is logged and traced end-to-end.
4. Fail Safe, Not Fail Open — When in doubt, the agent stops and asks a human. Timeouts and policy gates are structural — not suggestions.
5. The Agent Is Not Special — Agent-initiated changes go through the same review, CI, and deployment pipelines as human-initiated changes.

Quick Start: Mental Model

┌───────────────────────────────────────────────────────────┐
│                    YOUR INFRASTRUCTURE                    │
│  AWS / Azure / GCP / OCI    Terraform / Bicep / Pulumi    │
│  GitHub / GitLab / ADO      Prowler / Checkov / Custom    │
└────────────────────────────┬──────────────────────────────┘
                             │
                  ┌──────────▼──────────┐
                  │    POLICY PLANE     │  ← What agents CAN do
                  │  (rules, approvals) │
                  └──────────┬──────────┘
                             │
            ┌────────────────▼────────────────┐
            │          AGENT RUNTIME          │
            │  Skills · Subagents · Tools     │  ← How agents DO it
            │  Credentials · Sandboxing       │
            └────────────────┬────────────────┘
                             │
                  ┌──────────▼──────────┐
                  │   CHANGE CONTROL    │  ← How changes LAND
                  │  (PRs, validation)  │
                  └──────────┬──────────┘
                             │
                  ┌──────────▼──────────┐
                  │    OBSERVABILITY    │  ← How you SEE it
                  │  (traces, alerts)   │
                  └─────────────────────┘

Alternatives Covered

This guide doesn't prescribe a single stack. For each architectural layer, we cover multiple approaches:

Contributing

Found an error? Have a better pattern? Contributions are welcome.

• Issues — Open an issue for questions, suggestions, or corrections
• Pull Requests — Submit a PR for content improvements or new examples
• Discussions — Use GitHub Discussions for broader architectural questions

Please keep contributions focused on patterns and architecture — not vendor-specific marketing.

About

This guide is built by the team at Cloudgeni, where we design, build, and operate autonomous infrastructure agents in production across AWS, Azure, GCP, and OCI for enterprise teams.

Every pattern here comes from running these systems in production. We open-sourced it because we kept answering the same architectural questions — writing them down once seemed more useful.

We also released OpenGeni as a concrete implementation of this guide: a production-oriented infrastructure-agent stack with source available at Cloudgeni-ai/opengeni.

License

The guide text is released under CC BY 4.0. Use it, adapt it, share it — just give credit.

Code snippets are released under MIT.