From prompt to accountable system — how design, evaluation, release, deployment, operations and governance combine into one system.
Looked at from the outside, an AI agent seems to be mostly a prompt. Somebody wrote clever instructions, connected a model, and the thing started working. The prompt matters — but in a mature environment it is one layer out of many.
An agent has to be designed. Someone has to decide what it is allowed to touch. Its tools have to be built, described and versioned. Its context has to be assembled, curated and kept fresh. Its behaviour has to be evaluated, packaged into something you can ship, and promoted into an environment where real consequences live. Then it has to be watched, corrected, secured, upgraded and — eventually — retired.
If an organization runs hundreds of agents across dozens of teams, another problem appears: you need to know what actually exists, who is accountable for it, and what it can reach. That is why the agentic era is generating its own vocabulary of registries, manifests, catalogs, evaluations, ladders and receipts.
Some of it describes behaviour. Some describes permission. Some describes what was deployed. Some exists to answer one deceptively simple question:
This field guide is a map of that world. It is the agentic successor to the software anatomy every technology organization already knows: SDLC, CI/CD, GitOps, CMDB, SBOM, SLOs, postmortems. Each has an agentic counterpart — sometimes a direct translation, sometimes a concept with no ancestor at all, because software that decides and acts creates problems that software which merely runs never had.
It is not written for a machine-learning researcher. It is written for the technically literate person around agentic systems: the product manager, founder, consultant, investor, operations lead, business architect, marketer or delivery director who has to make decisions about agents without building the runtime themselves.
The goal is not to learn a hundred names. It is to understand the relationships between them. Where classic software asked what do we have and where does it run, agentic software adds three questions that change everything: what may it do on its own, how do we know it is still behaving, and who answers for the outcome?
The landscape is easiest to understand split into five overlapping areas.
Creating the thing. Deciding the job to be delegated, decomposing it into steps, choosing models, writing instructions and skills, building tools, designing what the agent shows a human before it acts.
Turning a working prototype into a version you can safely run. In classic software this is compilation and packaging. Here it is evaluation: proving a specific bundle of model, prompt, tools and policy behaves as intended.
Actually running that version in a specific environment, with specific credentials, against specific systems and real people.
Keeping a live agent healthy: watching behaviour, catching drift, reviewing its work, handling escalations, absorbing incidents, controlling cost.
Running the whole estate: which agents exist, what each may do, who owns it, what data it touches, what it costs, whether it still deserves the autonomy it has.
The foundational concept of this guide is the ADLC — Agent Development Lifecycle. It is not a technology or a product. It is a model describing the stages an agent passes through, from the decision to delegate something to the decision to switch it off.
| Classic SDLC | ADLC | Why the shift matters |
|---|---|---|
| Testing | Evaluation | Deterministic software passes or fails a test. An agent produces a distribution of behaviour, so the question moves from "does this return 4" to "across a hundred realistic cases, how often does it do the right thing, how does it fail, and what does it do when unsure". Evaluation is statistical, and it never fully ends. |
| Operating | Supervising | A deployed service is monitored. A deployed agent is supervised: someone reads a sample of its work, approves the hot actions, and absorbs the escalations. That work has throughput limits — and those limits, not model capability, usually decide how many agents an organization can actually run. |
| Functional improvement | Behavioural improvement | A release can change how an agent reasons, refuses, escalates and sounds without changing a single feature. |
In older organizations these stages sit in different departments: a data science team builds, an engineering team integrates, a business team uses, and nobody owns the behaviour. The modern answer is the one DevOps gave twenty years ago, shifted one level up. Call it AgentOps:
That small shift produces the whole family of practices in this guide: declarative agent definitions, automated evaluation, behavioural regression suites, action receipts, autonomy maps as living policy, and reversal designed before launch rather than improvised during an incident.
Before anything is built, someone has to decide how the agent will be constructed. Agent architecture describes the significant elements of an agentic system and the relationships between them. It is not the wording of an instruction.
It answers questions like: what job is being delegated, and what does "done" look like? How is that job decomposed into steps the agent can plan over? Which tools does it call, and what can each tool reach? What does it remember, for how long, and who can edit that memory? Which actions may it take alone, which require a human, which are forbidden? Where does it hand off — to a person, a specialist agent, or an external system? And what evidence does it leave behind?
There is no single mandatory format, and the level of detail varies enormously. The problem starts when everyone draws it their own way — and in agentic systems that problem is worse than in classic software, because the most important facts are invisible on a normal box-and-arrow drawing.
A useful agent diagram therefore encodes three things a classic diagram never had to:
The C4 model gave software four levels of zoom — context, container, component, code. Agentic systems need the same discipline, with different contents at each level.
Who delegates work to this system, what outside systems does it touch, and what does it produce for whom? An account manager delegates to a campaign agent, which reaches the ad platform, the CRM and the client. At this level nobody cares how the agent is built. The question is: who is trusting it with what, and who sees the result?
The large, separately deployable pieces: the orchestrator, each agent runtime, tool servers (often MCP servers), the memory and vector stores, the evaluation harness, the human review surface.
Inside a runtime: planner, retriever, tool adapters, guardrail and policy checks, the verifier that inspects output before it leaves, the escalation router.
The lowest level is no longer only code. It is system prompts, skills and instruction files, tool schemas, policy definitions, and the evaluation cases that define what "correct" means.
Good architecture documentation lets you change the level of zoom. Most organizations live comfortably at levels one to three. Level four is where the behaviour actually lives — and where most teams have no documentation at all.
The word architecture covers three very different scopes.
Agent architecture describes one agent: its role, tools, memory, boundaries and escalation paths. The question is how is this agent built?
System-of-agents architecture describes several agents delivering one business outcome together — an orchestrator, specialists, a verifier, humans at defined checkpoints. The question is how do these actors collaborate, and who owns the result? This is the level where attribution becomes hard and where multi-actor clarity stops being a nicety.
Enterprise agent architecture tries to describe the agentic landscape of a whole organization.
A diagram shows what exists. It rarely shows why it was designed this way. Classic engineering solved this with the ADR — Architecture Decision Record. Agentic systems need the same artifact, with a wider remit.
This matters more than in classic software, because agent decisions look arbitrary from the outside. Two years later, a new team sees a confirmation step on a trivial action and removes it as friction — not knowing it was added after a €40,000 incident.
The set of technologies used to build and run an agentic system. Two layers deserve attention because teams routinely forget them until something goes wrong.
An instruction is a request; a guardrail is a mechanism the agent cannot talk its way past. If your spending limit lives in the system prompt rather than in the tool, you do not have a limit — you have a preference.
The human surface is equally first-class. Every consequential agent needs somewhere a person can see what it did, disagree, undo and escalate. Teams that treat this as "the UI we'll add later" ship agents nobody is willing to trust with anything meaningful.
The naive version is a list of names. A mature one carries the fields that let someone make a decision.
| Field | Example | Why it matters |
|---|---|---|
| Agent | invoice-matching agent | Identity, and a name humans recognize |
| Delegated job | Match invoices to POs, flag exceptions | Business purpose, not technical function |
| Accountable human | Finance operations lead | Someone answers for outcomes |
| Autonomy | Auto under €2,000; approval above | The contract, readable outside the codebase |
| Hottest action | Approve payment — HIGH | Risk is set by the hottest thing it can do |
| Data reach | Finance systems, supplier records | Exposure and privacy surface |
| Model & version | Frontier model, pinned | Upgrades change behaviour |
| Status | Production since March | Distinguishes pilots from load-bearing systems |
| Volume & cost | ~4,000 actions / month | Value, and the review burden it creates |
The difference is qualitative. One inventory says "we use an invoice agent". The other says: an agent with payment-approval authority handles 4,000 finance actions a month, owned by one named person, auto-approving below a threshold set nine months ago.
A list still does not express the organization's stance. The technology-radar model — adopt, trial, assess, hold — translates cleanly, and is unusually valuable here because the ground moves so fast.
An inventory says what you have now. A radar says what you want more of, less of, and what you are watching. Together they turn a moving landscape into something a leadership team can actually steer.
Before an agent runs, it has to exist somewhere. In a healthy setup that place is a version-controlled repository — and what lives there is broader than code.
AGENTS.md, CLAUDE.md, SKILL.md, a business.md describing how a company actually works — have quietly become the substrate agents read. Covered in depth in the Markdown guide and Markdown for AI.If the agent's behaviour changes, can you point at the commit? If behaviour changes because someone edited a text box in a vendor console, the agent has no source of truth — only a current mood.
The monorepo/polyrepo decision recurs, with an agentic twist. One repository for the estate makes shared context, shared tools and fleet-wide policy changes trivial — when a refusal rule or an escalation recipient changes, it changes everywhere at once. One repository per agent gives teams separation, independent release cadence, and tighter permissions on sensitive agents.
Neither is universally right. But the agentic version has an extra dimension the software version did not: context inheritance. When agents share a repository they tend to share instruction files — and a change to a shared file silently changes the behaviour of every agent that reads it, including ones whose owners were not in the conversation.
A folder decision quietly becomes a behavioural blast radius. Whichever model you choose, the rule that saves you is the same: shared context files need owners and change review, exactly like shared libraries.
Every agent inherits a large surface it did not write: a model with a version, provider and safety settings; a framework or SDK; internal APIs and their permissions; MCP servers, often third-party; retrieval sources including the open web; prompt and skill libraries; and sub-agents, which have dependencies of their own.
Two things make this dependency graph harder than the software one.
First, dependencies arrive through content. A retrieved document, a web page, a tool description written by a vendor — all of these enter the agent's reasoning. A library can only run the code it contains. A retrieved page can contain instructions.
Second, dependencies change without a version bump. A model provider updates a system-level behaviour, a vendor rewrites a tool description, a knowledge base gets a new page. Nothing in your repository changed; your agent behaves differently on Tuesday.
An SBOM lists what is inside a piece of software. An ABOM lists what is inside an agent's behaviour.
The same artifact also powers model-deprecation planning, licence and data-usage review, and incident scoping. It is the single most under-built artifact in agentic organizations today.
The full chain from intent to action — instructions, context and retrieval, model, plan, tools, action, evidence — can be attacked at every stage. The attacks differ from classic software in one crucial way: the payload is language, not executable code.
This is why security in agentic systems cannot be a review step before launch. The attack surface is the agent's ordinary working day: reading, retrieving, deciding, calling. The practical defences are boring and effective — treat all retrieved content as untrusted input, scope tool permissions to the narrowest useful set, pin models, keep secrets outside the model's context entirely, and make every consequential action produce a receipt.
In classic software the build turns source into a runnable artifact. In agentic software it turns behavioural sources into a versioned, evaluated bundle: assembling prompts, skills and context files into final form; resolving tool schemas and pinning the model version; running the evaluation suite and recording the scores; running behavioural regression against the previous version; generating the ABOM; and producing an immutable, signed bundle.
A prompt in a console is not an artifact — it has no version, no evaluation record, and no way back. A bundle is a thing you can point at and say: this exact combination was tested, scored 96.3%, and was approved by this person on this date. Most agentic incidents that become embarrassing trace back to the absence of that line.
Artifacts have to live somewhere. A registry stores versioned agent bundles the way a container registry stores images — carrying the bundle, its ABOM, its evaluation results, its autonomy map, and the identity of whoever approved promotion. Alongside it two related catalogs usually appear: a prompt and skill registry for reusable behavioural components, and a tool catalog for the capabilities agents can be granted.
Only bundles from the registry run in production. That single rule eliminates the most common failure mode in early agentic estates — production behaviour that exists only in someone's browser tab.
Continuous integration means every change is automatically verified. For agents, verification is evaluation — and it produces a percentage, not a green tick.
Four properties separate a real evaluation suite from a demo checklist.
It measures failure modes, not just success. Escalation recall — how often the agent correctly refuses or hands off — usually matters more than task accuracy. An agent that completes 99% of tasks and confidently invents the other 1% is worse than one that completes 95% and flags the rest.
It contains cases drawn from production. Every incident, every human correction, every "that's not what I meant" becomes a case. The suite grows the way scar tissue does.
It is versioned with the agent. A score means nothing without knowing which suite produced it.
It runs on model upgrades, not just code changes — the most under-appreciated practice in this guide.
Continuous delivery for agents means every evaluated bundle is ready to promote. Continuous deployment means approved bundles promote automatically. The agentic pipeline adds stages that have no software equivalent.
Shadow mode. Running an agent in parallel with the humans doing the same job — proposing, never acting — generates real cases with a human ground truth attached. Most teams skip it and pay for that later, in production.
Not every build is a release. A team may produce dozens of bundles a week. A release is the version officially designated for a particular use — and for agents, a release is a statement about behaviour. Three artifacts describe it from different angles.
| Artifact | Answers |
|---|---|
| Release manifest | What exactly shipped: model, prompts, tools, policy, evaluation scores — the ABOM. |
| Behaviour changelog | What changed in how the agent acts, refuses, escalates or sounds. |
| Release notes | What the people who work with this agent need to know. |
Deployment is running a specific agent version in a specific environment, with specific credentials, against specific systems. The agentic complication is that environments are defined less by where the code runs than by what the agent can reach.
Useful environment design therefore separates three things explicitly: the model endpoint — same or different from production? The tool estate — real systems, sandboxed copies, or mocks? And the data — real customer records, synthetic, or anonymized? Each combination is a different risk profile.
The most common mistake in early agentic work is a "test" agent with live write permissions, because building sandboxed tools felt like a detour. It is not a detour. It is the environment.
Deployment architecture adds the facts agent architecture leaves out: where the orchestrator runs and in which region, which model endpoint with what data-residency and training terms, where tool servers sit relative to the systems they reach, and where evidence is stored. In regulated work these are not infrastructure details — they are the answer to whether the system is permitted at all.
Agents as code means the agent's definition — version, policy, permissions, context sources, escalation rules — is declared in a file rather than configured in a console. Context management is the discipline of deciding what the agent is allowed to know at each step, and keeping it fresh; most context problems present as reasoning problems, which is why they get misdiagnosed.
Sandboxes give an agent somewhere to act without consequence — the agentic equivalent of a test database, and just as often skipped. And reconciliation is the GitOps idea moved up a level: declare the intended state and let a controller continuously compare reality against the declaration, so drift becomes visible instead of accumulating silently.
The manifest is the single most useful artifact in this part. It states, in a form both humans and machines can read: what this agent is, who owns it, what it may do autonomously, what requires approval, what is prohibited, what it can reach, what identity it uses, how it escalates, and how it is shut down. It is the machine-readable half of an Agent Owner's Manual.
Templates and packaging make the safe path the easy one: a new agent starts from a shape that already has evaluation hooks, a policy file, receipts and an owner field, rather than from an empty prompt box.
Configuration, secrets and delegated authority close the part. An agent that acts under a shared service account cannot be held accountable, because its actions cannot be distinguished from anyone else's. Agents need their own identities, their own credentials, and authority that is delegated explicitly and can be revoked without breaking three other systems. Secrets belong outside the model's context entirely — anything in the context window is one clever request away from being repeated back.
In classic architecture the unit is a service. In agentic architecture it is an agent — and an agent is not a service, because a service does what it is called to do while an agent decides what to do.
That difference changes what has to be described. A service has an interface. An agent has an interface and a disposition: how it interprets ambiguity, when it asks, when it refuses, what it does with a partial answer.
Every tool an agent can call, with its description, its inputs and outputs, the system it reaches, the authority it carries, and whether its effects are reversible. Tool descriptions are behavioural surface: a badly worded description changes when an agent reaches for it, which makes tool copy an engineering concern rather than documentation.
How agents find each other. The moment one agent can delegate to another, the estate needs a directory with capabilities, authority levels and ownership attached — otherwise delegation happens by convention, and convention is not a control.
What the agent is allowed to know, from where, and how fresh it must be. Context has a lifecycle of its own: sourced, ingested, indexed, retrieved, used, and eventually stale. Most "the agent hallucinated" incidents are context incidents with a misleading name.
Structured outputs are how an agent's judgement becomes something another system can act on safely. A contract that specifies not only shape but required evidence — a citation, a confidence, a source id — converts a fluent answer into a checkable one.
For any assertion the agent makes: which source, which retrieval, which reasoning step, which version. Provenance is what lets you answer the question that follows every discovered error — what else was based on this?
The catalog is the human-facing view: what exists, what it is for, who owns it, how to request access, what it costs. The service catalog is the same list read as offerings — the agents other teams can actually consume, with the service levels attached.
A CMDB records configuration items and the relationships between them. Its agentic version records agents, tools, models, context sources, identities, systems and owners — and, crucially, the edges between them.
The edges are the point. A list of agents tells you little. A graph that can answer "which agents reach the billing system", "which use this model", or "which hold write access to customer records" turns inventory into a risk instrument.
Cost per unit of work, including the part nobody counts: review time. An agent that halves handling time and doubles supervision load has not saved anything. Economics that exclude the human cost of oversight consistently overstate the case.
Reading the estate as a portfolio: what to invest in, what to standardize, what to merge, what to retire. Most estates carry several agents doing approximately the same job for different teams, each with its own owner and none with enough usage to justify the maintenance.
A named person, not a team. Teams do not answer questions at 3am; people do. This is the same rule that anchors the Agent Owner's Manual, and the reason it is the first item in the readiness check below.
Monitoring answers whether the system is up. Behavioural observability answers whether it is still itself — and the second question is the one that matters for an agent.
The signals are different in kind: escalation rate, refusal rate, tool-selection distribution, confidence profile, human-override rate, and the shape of the work it declines. A drop in escalations can be an improvement or the earliest sign of a serious regression, and only the surrounding data distinguishes them.
Three artifacts for three questions. A trace shows the steps taken. A transcript shows what was said. An action receipt shows what changed in the world, under whose authority, and whether it can be reversed. Only the third survives a legal question.
Who talks to whom, and who may act on whose behalf. In multi-agent estates the delegation map is where unpleasant surprises live: authority granted transitively that nobody would have approved directly.
Runbooks for known operations; playbooks for classes of agentic failure — drift, tool outage, context poisoning, permission escalation, silent degradation. Incident management for agents differs in one respect: containment usually means reducing autonomy rather than restarting a service. The postmortem's real output is not the narrative but the new evaluation case.
| Instrument | What it fixes | The agentic difference |
|---|---|---|
| SLI / SLO / SLA | How good it must be | Indicators are behavioural, not just availability: correct-outcome rate, escalation accuracy, time-to-human on a hot action. |
| Trust budget | What freedom it has earned | The error budget's agentic cousin. Behave within your service levels and autonomy expands; spend the budget and autonomy contracts automatically, before someone has to argue for it. |
| Agent reliability engineering | Who keeps it honest | SRE moved up a layer — toil reduction, capacity planning and reliability work applied to behaviour rather than uptime. |
| On-call & supervision throughput | The real ceiling | How many actions a human can meaningfully review per hour. This, not model quality, is what caps the number of agents an organization can run. |
| Reversal, rollback, recovery | Whether you can take it back | Rollback restores a version. Reversal undoes an effect in the world. Designing reversal before launch is the difference between an incident and a crisis. |
Capacity planning for agents is not about tokens or throughput. It is about supervision throughput — the finite number of consequential actions your people can actually review. Every autonomy decision is a trade against that budget, and the budget does not scale with the model.
The classic questions still apply, plus one that has no ancestor: what happens when the thing we are securing decides to act?
The distinctive surfaces are context poisoning, tool abuse, permission escalation through delegation, instruction injection through content the agent reads, and the quiet one — an agent behaving exactly as instructed by an instruction nobody reviewed. That last case is covered in depth in prompt injection in .md context files, where the point is that context files are the one input an agent is built to trust.
How this estate could cause harm, ranked, owned and reviewed. Distinct from a general risk register because the failure modes are behavioural: not "the service is down" but "the agent confidently did the wrong thing at scale, politely, for eleven days".
A model upgrade is a behavioural change disguised as a version bump. Behavioural regression suites are the only defence, and they have to run before the provider's deprecation date, not after. This is the single most predictable disruption in an agent estate, and the one most often handled as a surprise.
An inventory of what each agent can authenticate as, and under what licence its models, data and tools may be used. Data rights matter more here than in classic software, because agents move information between systems that were never designed to share it.
The three-document sequence that turns an estate into a plan. Current state is what you actually have — usually a surprise. Target architecture is the reference design a standard agent should conform to. The roadmap is the sequence and the honest cost of getting there.
Principles are the directional layer — short, arguable, and useful precisely because they rule things out. Governance is where autonomy is granted and withdrawn. And the behavioural debt register records the shortcuts still being paid for: the hardcoded exception, the prompt patch instead of a fixed tool, the approval step added because nobody trusted the evaluation.
Retirement is a first-class stage: revoke credentials, archive evidence, notify dependents, remove from the registry, and confirm nothing silently depends on it. Platform engineering for agents provides the paved road — templates, evaluation harnesses, gateways, policy as code — so that the safe path is also the easy one. Guardrails enforced by mechanism beat guardrails requested in a prompt, every time.
Sooner or later every artifact in this guide turns out to be a node or an edge. Agents, tools, models, context sources, identities, systems, owners, actions, incidents and evidence — connected.
Along the way the estate needs a handful of distinctions that sound pedantic until an incident makes them urgent. Source of truth is where a fact is authored; system of record is where it is officially held. One central registry is never enough, because static inventory (what was declared) and dynamic inventory (what is actually running) diverge — and the gap between them has a name: drift. Beyond drift sit shadow agents: the ones nobody registered, usually built by someone competent and helpful, which is exactly why they are hard to find.
The most valuable view is not a list of agents. It is a path from a technical fact to a business consequence.
The same traversal, read for responsibility rather than damage. "The agents did it" is not an answer; this map is what replaces it.
Radar, inventory and deprecation dates in one view. Without it, a provider's retirement schedule becomes a scramble; with it, a plan.
Running from origin to production. For each element: can we confirm its origin, who could change it, was it evaluated, can we reproduce it?
Backwards it answers "what is this claim based on?" Forwards, after an error is found in a source: "which outputs used this, and which reached a customer?"
Not every dependency is technical. Some of it lives in what people know — and leaves when they do.
The view an executive actually asks for: which parts of the business now depend on delegated judgement, and how much.
That is the whole argument for maintaining these maps as living structures rather than documents. A wiring diagram of a system that only changes on release day can be refreshed quarterly. A map of a system that reasons, delegates and drifts has to be derived continuously, or it is fiction with a timestamp.
The single most useful change of perspective in this guide is this.
The prompt is one element. To function, the agent needs context. Context needs curation and freshness. Tools need permissions. Permissions need scope. Scope needs review. Behaviour needs evaluation. Evaluation needs cases. Cases come from incidents. Incidents need owners. Owners need evidence. Evidence needs a receipt. Models have lifecycles. Autonomy has to be earned, and can be lost. And the whole thing changes underneath you, continuously.
Which is why an agentic organization eventually needs answers to a small set of blunt questions.
In a two-person team, one person can hold most of this in their head. In an organization running forty agents across six functions, it has to be written down, automated and connected.
| Artifact | Answers |
|---|---|
| Agent architecture diagram | How the system is put together |
| Agent decision record | Why it was designed this way |
| Agent stack | What technologies it uses |
| Agent inventory | What we have, and where |
| Agent radar | Where our practice is heading |
| ABOM | What is inside this agent's behaviour |
| Evaluation suite | How well it behaves, and how it fails |
| Agent bundle & registry | Exactly what was released |
| Agent manifest | What it is allowed to do, and who it answers to |
| Autonomy map | Autonomous, confirmed, blocked — in plain language |
| Gateway policy | What is actually enforced, not just intended |
| Behaviour changelog | What changed in the agent's character |
| Transcripts & traces | What happened, step by step |
| Action receipts | What changed in the world, on whose authority |
| Agent catalog | What exists and who owns it |
| Agent CMDB | What connects to what |
| Service levels & trust budget | How good it must be, and what freedom it has earned |
| Runbooks & playbooks | What we do when it goes wrong |
| Postmortems | What the incident taught the system |
| Risk register | How this estate could cause harm |
| Behavioural debt register | What shortcuts we are still paying for |
| Portfolio review | What to invest in, standardize, or retire |
Run these against one real agent — ideally your most consequential one. Anything you cannot answer in under a minute is the finding. Nothing is stored or sent anywhere; the total calculates in your browser as you go.
Answer for one agent, not for the estate. Readiness is not an organizational property — it varies enormously by agent, and averaging hides exactly the gap you are looking for.
Method · The ADLC, the ten maps, the artifact index and the readiness check are auxfirst's own frameworks, developed through client work rather than derived from a published standard — we say so plainly rather than implying one exists. Where a concept has a direct ancestor in classic software practice (SDLC, CI/CD, GitOps, CMDB, SBOM, SLO, error budgets, the C4 model, technology radars, architecture decision records) the lineage is named in the text so the borrowing is visible. Examples are illustrative patterns, not case studies; auxfirst does not publish named client results.