The change request document and the change management agent

Read and export a change request in the customer's template, see which sections the change management agent drafted, and switch the agent on or off.

How-to · Updated 2026-10-28 · Describes release 0.1.164

Goal

Every change request carries a document in the section order of the customer's change request template: version control, requesting organization, then sections 1 to 9. You read it on the change page, download it as Markdown or Word, and the ticket write-back carries it. The change management agent drafts the narrative sections; everything that decides what runs stays the platform's.

Before you start

incidents.view to read and download the document; incidents.act to ask the agent to draft it again.
members.manage to change the two workspace switches on Guardrails.
A change request: an escalated analysis with a fix mints one, and so does a request you declare on Changes.

The sections and where each one comes from

Section	Filled from
Version control	The change's own history: created, drafted by the agent, approval requested, approved, released for execution, reclassified, executed. One row per event, version 1.0 upwards; a change approved by one person and released by another names both, and one person who approved it and later ran it reads approved, then released.
Requesting organization	The workspace name (or `settings.cr_template.organization`), the change title as "<title> in <target environment>", the submitted date (the approval request, else the creation date), the reference, class and tier. The environment is the alert's `env`/`environment` label, else the account and region in scope, else the service.
Section 1 – Change request objective	Pre-, during- and post-execution objectives drafted by the agent; without a draft, the before-state check, the plan's steps and its verification.
2.1 Requirements	The agent's statement of the request, else the change summary, plus the write connection the platform chose for each step.
2.2 Assumptions	The agent's list, else the plan's limitations.
2.3 Prerequisites	The agent's list, plus what the platform enforces: the change window, the approvals at the tier, the before-state read before every write.
2.4 Impact (L, M, H)	A level decided in code: H at tier L3, when the change removes a relationship in the estate, or when three or more services depend on the target; M at tier L2 or with any dependent; L otherwise. Then the blast radius and the agent's rationale; when the estate model reasoned the impact over the target (any basis but an estimate) and nothing is lost, also affected or depending on it, it reads the card's headline with its basis label — Blast radius — Certified blast radius: No negative impact found: nothing depends on the target through the estate model, or … No negative impact found — gains only: N consequences gained followed by what the change gains — the line 2.5 cites. An estimate always keeps its list. Under it, the same sentences as the change page's blast radius card: the one basis sentence (Estimate: computed from the target's direct neighbours in the estate map; this operation has no exact before/after delta., or the report's own reason), the map's coverage gaps one line per kind with the denominator (N of M resources in the estate map: no relationship model yet …, … stale after the last harvest, left out of reasoning, … inconsistent between sources, left out of reasoning), and last the change management agent's impact in plain words — The change management agent read the same neighbourhood: No impact when the draft read this very report, else the words as written — a bare No impact as The change management agent's note: No impact (…).
2.5 Risk (L, M, H)	A level decided in code: H for an emergency change or tier L3, M for a normal change or tier L2, L for a standard change. Then the class reason, the blast radius the risk is weighed against — the change page's headline (No negative impact found: nothing depends on the target through the estate model when nothing is lost, also affected or depending, else the counts), basis sentence and coverage gaps, without the agent's words — and the agent's rationale.
3.1 Existing environment	The current state the estate harvest holds, the resources recorded at triage and the before-state recorded per step.
3.2 New resources	What the change creates (a backup step, a new file); "None" when every step changes an existing resource.
Section 4 – Scope of work	For a change that follows a step runbook, first the runbook in plain words: its name, revision and certification, Purpose, When to use, Risks, Backout and its steps, with the targets bound from the incident. Then S/No, phase and performed by: Platform for checks, steps and validation, Customer for a manual command or a pull-request merge, the approvers by name. Then the resources in scope by phase, then the command for each typed step, in its CLI form (validated like an executed step; the platform runs the same operation through the write connection, and a step with no CLI form adds no line). A pre-change AWS backup (an AMI or an EBS snapshot) gets its `aws ec2 create-image` / `create-snapshot` line too, before the step it protects, with the name, description and tags the platform sends (the retain-until date once the backup was taken, `YYYY-MM-DD` before); an Azure disk snapshot has no line: its source disk is read only when the change runs.
Section 5 – Rollback plan	The rollback steps the change's runbook declares, in its order, each with its command line (the recorded groups back after an isolation, the root volume restored from the pre-change image); with no declared rollback, the compiled inverse of each typed step and the recorded rollback. Then the manual undo commands, and out of scope (the agent's list and every excluded resource).
Section 6 – Estimated timeline/duration	A platform estimate from the number of steps and the change window that applies. Not a commitment.
Section 7 – Impact on running cost per month	USD 0.00 when the change creates nothing; "Not provided yet" when it creates a resource whose cost the platform does not estimate.
Section 8 – Change closure details	"Verify the services and configurations" (Customer), the post-change validation verdict, the before- and after-state records, the post-implementation review, and the resource snapshots table (below).
Section 9 – Customer acceptance	The customer's authorised requester (name, title, email) — left Not provided yet for the customer to complete: who accepts a change request on the customer side is still open. Below it, Platform approvals: who requested approval, every approver with the time, and the link to the change as evidence.

A section with nothing to show says Not provided yet. The customer's address, logo and disclaimer are not reproduced; settings.cr_template.logo_text adds one line of text above the title.

Scope by phase (our proposal)

The customer left open who defines the scope. The platform proposes: triage owns before (the resources recorded when the analysis escalated), the platform owns during (the compiled step targets and any backup) and after (what validation reads plus the one-hop neighbours of the service, both directions, at most 10). The document marks this split as a platform proposal. A request drafted with its validation plan lists exactly those checks — V1, V2, … with what each must show — under Scope of work and as the after resources, because post-change validation runs that list and nothing else.

Resource snapshots

Every resource the plan writes is read, read-only, at three points, and each read is evidence on the change — never a restore source and never the verdict:

Before — each resource's own before-state, read just before its first write (the pre-change state the rollback is compiled from; no extra read).
After each step — in a plan of more than one step, after every write step that succeeded, each written resource is read again with the same read its before-state took, through the step's own connection. A backup step changes nothing on its resource and is not followed by a read. At most 10 resources per step and 40 reads per change; a step that reaches the cap says how many it left. A read that fails or raises is recorded with its reason and never stops or retries the release.
After the change — the post-change read the last-known-good record takes once the change is verified.

The change page's Resource snapshots card and the table in Section 8 list them in that order, each with its state and whether it differs from the resource's before-state (changed, unchanged, or — when either read cannot be compared, such as a read that kept no parsed state). Each read after a step is stored as an artifact of kind snapshot. A planned change request says the snapshots are still to come. The resources in scope are the ones the plan writes; their one-hop neighbours are read by the validation plan instead (our proposal).

Procedure

Open a change request on Changes: the Change request document card leads the page — the page is the change request, and Download Markdown / Download Word give it to the CAB. The line under the title says whether the change management agent drafted the narrative sections, is drafting them, or failed. You should see the title, the reference and the submitted date.

API: GET /api/aiops/{tid}/changes/{id}/document — incidents.view; the sections as data plus their Markdown.
Press Show sections. Each section carries a badge: Change management agent, Platform records or Agent draft + platform records. You should see every section of the template in order.
Press Download Markdown or Download Word for a file to attach to the customer's ticket or e-mail. The Word file is a plain document with headings and tables, no template styling. You should see a file named change-request-CHG-<id>.md or .docx.

API: GET /api/aiops/{tid}/changes/{id}/document?format=markdown or ?format=docx.
To have the agent draft again (after the analysis re-ran, or for a request you declared yourself), press Draft with the change agent. The scheduler starts the run within a minute; the card refreshes until it lands. You should see the drafting line change to drafted.

API: POST /api/aiops/{tid}/changes/{id}/document/draft — incidents.act; 409 when the switch is off or the change already ran.

The change management agent

When an analysis escalates with a fix, the change request is minted and marked for the agent. On the next scheduler tick one short change-agent run starts: at most 8 steps, reading what the triage run recorded (the read_evidence tool), never the estate again, and no web access. Its structured answer fills objectives, requirements, assumptions, prerequisites, the impact and risk rationale, the impact in plain words and out of scope. Operations, the write connection per step, class, tier, approvals, scope, validation, rollback and cost stay code. A run that is refused or does not land within the agent turn timeout leaves the document on the platform's records, and the drafting line says why. A change released (or rejected) before its draft lands keeps the request as it was decided: the narrative is not added afterwards, and the drafting line says the draft did not land because the change had moved on; the run's cost stays on the record. The run costs one bounded agent turn per change request, counted in the workspace's spend like any other run.

Switch (Guardrails › Change management agent)	Default	What it changes
Let the change management agent draft change requests (`change_agent_cr` → `aiops_change_agent_cr`)	on	On: the agent run above drafts the narrative sections — one paid run per change request (about USD 0.33 measured). Off: no extra run; the document shows the platform's records only.
Let the change management agent draft the fix too (`change_agent_owns_plan` → `aiops_change_agent_owns_plan`)	off	Phase 2. On (with the switch above): the incident and compliance analyses name the corrective mechanism and draft no plan; the change request opens as a draft and the agent drafts the plan with the document. The class and tier rules then run on its plan, and the fix review reads that plan. Off: the analysis drafts the plan, and its prompt is unchanged.

With the second switch off (the default), the incident or compliance analysis drafts the fix itself — the activities, the validation and the rollback on the change request come from its wrap-up (the plan reads generated_by: wrapup) — and the change management agent writes only the narrative sections around it. Turn on Let the change management agent draft the fix too (with the switch above) for the analysis to stop at triage and the change management agent to draft the fix.

With Phase 2 on, the agent's run also gets the write capabilities (it may read the estate to confirm the target), so in a workspace with a private-network agent it runs there; an agent image older than this release drafts no plan and the document says the draft failed.

Impact in plain words

The agent's run also receives, fenced as estate data, the impact the platform computed (its basis, the intended and also-affected resources, what is lost or gained, the services that depend on the target — computed then if nobody had opened the request yet) and the target's one-hop neighbours in the service graph, upstream callers and downstream dependencies. It writes what could break upstream or downstream and how, naming them, or exactly No impact when none of that lists anything. The words sit next to the computed blast radius — on the change page under Affected resources & blast radius (or Blast radius) as In plain words (change management agent), and in section 2.4 — as a conclusion on the same basis while the report shown is the one the draft read (its estate version, basis, mode and a fingerprint of what it lists are recorded with the words, so a report redrafted with another scope is not taken for it): The change management agent read the same neighbourhood: … for an estimate and … the same blast radius: … otherwise. No impact is spelled out only over a report that reasoned over the target (any basis but an estimate) and found nothing lost, also affected or depending: as nothing loses reachability, a route, a permission or a dependency over a certified or computed delta, and as nothing depends on the target through the estate model over a runtime one — a start, reboot or restart reasons over what depends on the target, not over reachability. Once the reviewed report or a later harvest replaces the one the draft read, the words show as written — except a bare No impact, which reads as the agent's note and never as a second verdict beside the basis: The change management agent's note: No impact (drafted over an earlier report), or (drafted before this estimate's basis was shown) for a draft that read no report: one made before 0.1.161, or while no impact had been computed yet. They never replace the computed report: the level stays the platform rule. When the agent writes No impact but the computed report lost a relation or affected a resource, both places say that the computed impact decides the level. Part of the same run, behind Let the change management agent draft change requests: no extra run.

An upgrade — a plan with aws.ssm.patch_baseline, aws.ssm.upgrade_packages, aws.lambda.update_runtime or aws.ecr.rebuild_image — also carries an Upgrade warning in section 2.4 and under Affected resources & blast radius: what runs on the target, who calls it, and the target version's known breaking changes with their source, as the change management agent wrote them in the same run. Until the agent has checked them, or when it did not, the warning reads exactly unknown, not checked; it is never left out. Any other change has no upgrade warning.

If something fails

The drafting line says failed: pillar disabled or unconfigured — the change pillar is off for this workspace; turn it on in Agents.
409 the change management agent is off for this workspace — the switch is off on Guardrails.
Not provided yet in a section you expected — the change has no data for it yet (no plan, no harvest, no approval). Request approval or re-run the analysis, then open the card again.

Next steps

Change windows, emergency changes and rollback — how the class, the window and the approvals in the document are decided.
Settings reference — every switch with its default.