Treating Agent YAML Files as First-Class Infrastructure Artifacts

Agents-as-code means defining AI agents in YAML configuration files stored in version control, with their permissions, tools, budgets, and behavioral constraints reviewed through pull requests. Those definitions must pass validation and control sandboxed execution so that the policy the team reviewed sets the limits enforced in production.

Why agents authoring code changes what their config files are

An AI agent wiped a Railway database in a documented incident where it had write access without a pre-execution policy gate. The consequence was not a poor code suggestion. The agent could act on a live resource, and no enforced boundary stopped it before it did the damage. A YAML definition, had it existed and been enforced, is where that gate would have belonged. The distinction is between asking an agent to behave safely and restricting what it can actually do.

That distinction becomes central when agents sustain work across multiple steps, invoking tools, interpreting results, and iterating without a human executing each action. Atlassian piloted an AI coding agent with human-in-the-loop across real-world JIRA issues in production at scale in two months. Agents are already first-pass executors. The move from SE 2.0, human-authored and agent-assisted, to SE 3.0, agent-authored and human-reviewed, therefore changes the status of the files that define them. Permissions and tool declarations become part of the production system because they govern an author that can execute its own decisions.

How the ecosystem converged on YAML as the language for agent behavior

The ecosystem is adopting a familiar infrastructure-as-code pattern, externalizing configuration, versioning it, and treating behavior as data. YAML is the medium for that convergence. These definitions do for agents what Terraform configurations did for cloud infrastructure, separating what the system does from how the system is built. The pattern appears across agent frameworks and platform configuration, although the file layouts differ.

dev/v1alpha2 as the API version and Agent as the kind. Tool-server definitions cover GitHub MCP and AWS Terraform. The agent is deployed with kubectl apply -f aws-terraform-agent.yaml`, in the same way that infrastructure is deployed. Here, YAML is a deployable artifact rather than a document describing desired behavior.

Microsoft Foundry places agent configuration and prompt-definition files in source control with MCP server configurations and Bicep or ARM infrastructure templates. Standalone agent.yaml definitions are deprecated in favor of unified azure.yaml configuration. Azure’s SRE Agent uses a directory pattern instead. Under my-agent/, agent.json holds identity and model settings, while roles.yaml defines RBAC assignments and other YAML files describe skills, subagents, safety hooks, and scheduled automations. The directory is version-controlled and deployed through a script as a coordinated set of agents-as-code files.

What belongs inside a production-grade agent YAML file

For teams defining agents in YAML, the production artifact should specify identity, authority, resource limits, and behavioral constraints alongside a prompt and a model name. Identity comes first because reviewers need to know which agent and model version a change affects. Agent ID, model class, and version pinning make that clear. Updating a model then means choosing to change its configuration. Keeping these settings in the reviewed definition also supports investigation of model drift over time.

Permission scope should then use explicit RBAC assignments to set out what the agent may read, write, invoke, and delegate. Tool and subagent declarations define the execution paths available within that scope, including which tools the agent may call and which subagents it may spawn. These belong with the agent definition because undeclared tool access is a route beyond its intended authority. A reviewer needs to see both the assigned role and the mechanisms through which the agent can exercise it.

Resource controls set out how much the agent may use when it runs, including model tier, maximum tokens per session, and circuit-breaker thresholds. Budgets need more than one layer of control. Per-request limits, per-session rolling budgets, per-key monthly caps, model-tier routing, and circuit breakers serve different purposes, while YAML declares the agent-level portion of that stack. If those settings exist only in a gateway configuration, the engineer reviewing a behavioral change cannot assess its resource implications in the same diff.

Safety hooks should set out the pre-execution gates, write restrictions, and kill-switch capability the agent must have. Evaluation gates address a different question, whether the agent’s behavior qualifies for promotion. Foundry’s pipeline defines hallucination-rate thresholds and task-completion floors, which are behavioral SLOs that belong with the agent definition they govern. The OpenFOAM/CFD case-bundle study illustrates the broader principle by keeping simulation configuration, execution scripts, and review records in one reviewed bundle. The reviewable unit is the governed work.

How to manage agent definitions through pull requests in Git

Git provides a shared record of proposed authority. A pull request exposes changes to permissions, tools, and budgets as a diff, allowing reviewers to judge them with the behavior they govern. History records how that authority changed, while versioning gives deployment and rollback a stable reference. A dashboard or gateway may enforce runtime policy, but settings held only there sit outside the workflow in which the team reviews the agent definition. The repository connects the policy decision to an inspectable artifact.

Stephanie Jarmak’s Engineering Reliable Coding Agents explains why that connection is necessary. Agents are evaluated as models but deployed as systems whose reliability depends on permissions, execution state, and resource allocation around the model. The model is only one part of deployment. When reviewers look only at prompts or generated patches, they miss the controls around the model that also shape how the agent behaves.

Foundry’s promotion pipeline puts this approach to work by moving definitions from Dev through Test/QA to Production. Evaluation gates apply at every stage, and human approval is required from Test/QA onward. Rollback is a version-pointer switch. Version-controlled definitions make that switch meaningful because the team can identify the artifact being promoted or restored.

Microsoft’s open-source agent-governance-toolkit extends the audit side with a cryptographically chained audit trail and a Decision BOM. Its control mappings cover OWASP Agentic Top 10, NIST AI RMF 1.0, the EU AI Act, and SOC 2. Those mappings presuppose a version-controlled artifact under audit. They do not, however, establish that every reviewed restriction was enforced during execution. Repository history supplies evidence of approved intent.

The review gap: what PR review catches in agent YAML and what it misses

A pull request can show a wider permission scope, a tool the agent can now use, an unpinned model, or a higher token budget. The core infrastructure-as-code review weakness is uncertainty about whether the execution environment interprets those declarations as the reviewer expects. A policy that reads as restrictive can grant access, and a correct-looking diff can conceal permissive behavior.

Terraform has a plan step that previews changes before apply, while most agent YAML schemas lack an equivalent dry-run enforcement step. Schema validation remains necessary, but it addresses only part of this gap. Passing validation does not demonstrate that declared restrictions constrain a live session. Jarmak’s monograph identifies failures originating in the harness, permissions, and resource allocation layers, and notes that improvements at one layer may not improve end-to-end task outcomes.

The human-centered coding agents position paper describes verifiability as an ongoing challenge, with agent-generated patches that are longer than ideal patches among the issues. YAML review has a similar burden when small changes affect behavior in ways that are hard to see. Teams need to link schema validation in CI to runtime enforcement and session-level sandboxing so that the declared restrictions limit what the agent can do when it runs.

OWASP’s Agent Control Standard, formally unveiled September 1–2, 2026, provides declarative hooks and policy enforcement points for that coupling. YAML declares intent, while the execution layer enforces it. OWASP’s Agent Bill of Materials, or AgBOM, complements repository review through production inspection, tracing, and instrumentation. Together, these controls connect the approved definition to the agent that actually ran, rather than treating approval as the end of governance.

How sandboxed execution makes declared YAML policy enforceable at runtime

The execution boundary should be one agent session in one disposable environment. Ten concurrent tasks then have separate environments, preventing competition within a shared one. Credentials are minted fresh for each session and revoked when it ends. Failed task environments can be discarded without unwinding their local effects, although disposal is not a substitute for gates on external writes. The sandbox and the YAML definition must be designed together so that the agent receives only the authority its reviewed policy allows.

The deployment path is part of that coupling. CircleCI’s kagent pattern places the agent declaration in the same pipeline as its execution infrastructure through kubectl apply -f aws-terraform-agent.yaml. This creates parity between deploying an agent and deploying infrastructure. The pipeline can manage the definition and the environment as connected production artifacts, rather than leaving one team to approve policy and another to interpret it independently.

Without a centralized execution layer, teams build separate isolation mechanisms, producing inconsistent security postures, fragmented audit trails, and no unified observability. A common execution layer gives repository governance a shared runtime meaning. Its purpose is not merely to launch agents, but to apply their reviewed boundaries to actual sessions.

Audit records must preserve the link between authorization and execution. The agent_id field identifies the model instance and version, while parent_identity records the human or system that authorized the session. The delegation_scope field records the OIDC scopes granted. These fields become useful evidence only when the environment enforces the corresponding authority declared in YAML.

Treating agent YAML review as a team practice, not a one-time setup

Teams need to maintain this discipline as agents proliferate, tasks change, and permissions drift. The OpenFOAM study offers a useful operating distinction. Build mode keeps engineers close to case preparation and documentation, while Replay mode applies the reviewed artifact across variants. Agent definitions need the same separation between active development and approved reuse. An artifact’s previous approval does not settle whether a later permission or model change is appropriate.

In practice, schema validation should be a required CI gate before an agent YAML change merges. Permission scope should be a named item in the pull-request template, with delegation scope explicitly reviewed. Budget changes need equally visible scrutiny. Token budgets and model tiers should remain reviewable fields, and a change in model class or an increase in the token limit should require explicit approval. Model identifiers should be version-pinned so that updates go through this process and the model stays at its reviewed version until a change is approved.

Regular audits should compare the definitions in use with actual session logs, checking declared scope against exercised scope to find permission drift. The human-centered coding agents paper identifies task alignment, steerability, verifiability, and adaptability as dimensions of ongoing collaboration, and each provides a criterion for reviewing the operating process as tasks evolve.

The compliance consequence follows from that routine work. The ACS and AgBOM framing points toward audits asking for a machine-readable inventory of what agents are authorized to do. Teams maintaining YAML in version control, validation in CI, sandboxed enforcement, per-session credentials, and audit logs are producing that inventory through their normal review process. They are building the basis for an AgBOM as a byproduct of production discipline, rather than reconstructing agent authority when an audit begins.