AI agents as code

AI agents as code means an agent's configuration is a file in a repository: which model it uses, what it is told to do, which tools it may call, what identity and permissions it runs under, when it runs, how much it may spend, and where credentials live — usually YAML or TypeScript checked into git beside application code.

Teams adopt it for the same reasons they adopt infrastructure as code. Pull requests review changes before production, git history shows who changed what, rollback is a revert, CI can validate schema and policy, and drift detection catches console edits that never made it back to the repo.

The file does not fully define runtime behavior. Models are non-deterministic, so the declaration is the contract you intend; evals and monitoring prove the agent still meets it. Secrets belong as references, not literal values. Spend caps and tool allowlists belong in the declaration, not only in an operator's memory.

What goes in an agent definition file

Different products use different filenames and schemas. The ideas recur: identity (name, description, tags), model or model alias, system instructions or prompt (inline or path to markdown), tools and skills (by name or path), environment (repos, runtime, MCP servers), triggers (cron, webhooks, events), budgets or rate limits, and metadata for observability.

Permissions are part of the definition when the platform supports them: which OAuth scopes an agent may request, which APIs it may reach, which repositories it may touch, and whether a human must approve an action. Treat those fields like firewall rules. If they are missing, every console session becomes the source of truth and production drifts the moment someone clicks a wider scope.

Credential references point at a vault, environment binding, or secret name — never the secret value. A committed API key is a leak waiting for a fork. The declaration should say `credentialRef: prod/stripe` or equivalent; the runtime resolves it at execution time.

Checklist: a production-grade agent file

Use this when reviewing a new agent definition in a pull request:

Why teams choose agents as code over console-only setup

Console UIs are fast for a prototype. They are poor system of record for a regulated team or for agents that run on a schedule while nobody is watching. A file in git forces the same review culture as application code: two eyes on a budget change, a linked ticket on a new tool, and an auditable diff when an incident traces back to a prompt edit.

Rollback is mechanical. Revert the commit that raised the temperature or added a dangerous shell tool; redeploy or let the sync job pick up the previous revision. Drift detection closes the loop the other way: if someone edits live state in a dashboard, the next plan step shows a diff against the repo and reconciliation can restore the declared configuration.

Multi-environment workflows become tractable. The same agent shape ships to staging and production with different secret references and budgets, rather than re-clicking through two consoles and hoping they match.

Four declarative agent patterns (verified read 2026-10-08)

Ellipsis: deploy agents from git

Ellipsis documents agents as YAML under `.ellipsis/` with `ellipsis.kind: agent`, holding session settings such as prompt, model, environment repositories, and budget blocks. The page read 2026-10-08 states that committing a valid `.yaml` or `.yml` on the default branch makes the agent appear on the dashboard Agents page, that an invalid update leaves the last valid version running, and that deleting the file disables the agent.

The public URL ellipsis.dev/docs/agents-as-code redirected on 2026-10-08 to the Deploy from git section of ellipsis.dev/docs/agents. Budget examples on the same page show per-session caps and day/week/month limits enforced at the platform, which is the shape agents-as-code teams want in the file rather than in tribal knowledge.

OpenAgentPack: validate, plan, apply

OpenAgentPack's README read 2026-10-08 describes an open-source control plane where one `agents.yaml` declares environment, model, instructions, tools, skills, MCP servers, vaults, and credential references. The workflow is deliberately Terraform-like: validate the declaration, plan the diff against remote managed agents, then apply in dependency order.

The project emphasizes drift detection when someone edits a cloud console by hand and content-hash diffing so only changed resources update. That is the operational half of agents as code: the YAML is not merely documentation; it is the desired state the tooling reconciles toward.

Cotool: response agents synced from GitHub

Cotool's Response Agents as Code guide read 2026-10-08 explains YAML files in your own GitHub repository, reconciled on a schedule (roughly every five minutes) into Cotool agents. Each file uses `apiVersion`, `kind: ResponseAgent`, `metadata`, and `spec` with model alias, tool names, inputs, triggers, and system prompt inline or via markdown.

Agents synced from the repo are engine-owned and read-only in the Cotool UI; you change them by editing YAML and waiting for sync. Each create or update can append to version history with the source commit SHA, which is the audit trail teams expect from git-backed configuration.

Veryfront Code: agents as project files

Veryfront Code's Agents guide read 2026-10-08 defines an agent as a file in `agents/` exporting a system prompt, optional tools, memory, and skills. TypeScript uses `agent({ id, system, ... })` from `veryfront/agent`; markdown agents use frontmatter for model and `max-steps` with the path providing the id.

Directory layouts such as `agents/researcher/AGENT.md` with colocated `tools/` and `skills/` keep capabilities beside the agent definition. That is agents as code at the application layer: the repo is the product, and agent behavior is versioned with the rest of the codebase.

Limits and trade-offs

A declaration is not a proof. The same YAML can pass validation and still hallucinate, call the wrong tool, or burn budget on a loop. Teams pair agents as code with eval suites, canary prompts, and spend gates enforced at runtime — not only fields in a file.

Not every agent platform exposes every knob in YAML yet. You may still need the console for secrets binding, OAuth consent screens, or provider credentials. The goal is to shrink that surface over time and record every remaining manual step as debt.

This pattern is also not the same as a coding agent in your IDE. Tools that write repository code on demand are a different category. For that distinction see coding AI agents on this site — one link, because the search intents differ.

Spend limits, secrets, and identity in declared agents

Budget fields in Ellipsis-style YAML and OpenAgentPack declarations mirror what production teams already enforce in policy engines: cap per session before a runaway loop invoices the card. The same idea for autonomous products is developed in budget-gating an autonomous agent.

Secret references belong in the file; values do not. Leak patterns when agents hold raw keys are in how AI agents leak API keys and secret management for AI agents. Empyre Vault is built so keys never leave storage and agents receive access or signatures instead of exports.

When an agent acts on a user's behalf with third-party APIs, OAuth scopes and token exchange belong in the architecture — not a long-lived key pasted into the YAML. OAuth for AI agents and Empyre Relay (relay.empyre.dev) cover hosted consent and PKCE for that path; they complement file-based agent definitions rather than replacing them.

Where Empyre fits

Empyre on empyre.dev is not an agent-definition framework and does not ask founders to author agent YAML. It turns a brief into a live software company and keeps eight AI executives operating it after launch — product, marketing, support, legal surface, finance, and creative work on a schedule.

The overlap with agents-as-code thinking is operational: tool permissions and spend are enforced in the platform, credentials are not handed to models as plain text, and OAuth-shaped identity for integrations is a first-class product (Relay) alongside secret storage (Vault). If you need git-native declarations for your own agents, use one of the patterns above. If you need a business operated without building that control plane yourself, that is a different purchase.

Common questions

Related

Last updated 2026-10-08. Competitor descriptions reflect each product's publicly documented capabilities at that date; they change often, so check the source before relying on a detail.