AI Agent Postmortem Template

An AI agent postmortem explains why an agent incident happened, how the controls performed, and what the team will change and verify.

The postmortem begins after the incident is stable enough for analysis. It should build a factual record from observable evidence, separate known facts from inferences and unknowns, and turn findings into owned work. It should not become a transcript dump, a defense of the system, or a search for someone to blame.

Download the AI agent postmortem template (Markdown)

The download contains 12 working sections: postmortem record and review status; executive summary and impact; timeline and recovery milestones; agent, workflow, and version inventory; decision-time context and provenance; identity, authorization, approvals, and human checkpoints; tool and external-effect reconciliation; detection, response, and evidence quality; root causes and contributing factors; corrective actions and regression cases; re-enable decision and follow-up verification; and distribution, learning, review, and closure.

TL;DR

A useful AI agent postmortem should:

1. State the impact in measurable terms and name who or what was affected.
2. Build a timestamped timeline from controlled evidence sources.
3. Record the exact agent, model, runtime, context, tool, policy, and dependency versions involved.
4. Reconstruct the decision-time context without collecting private model reasoning.
5. Check identity, tenant scope, authorization, approvals, and human checkpoints for each consequential action.
6. Reconcile requested tool actions with effects recorded by authoritative target systems.
7. Separate the trigger, root causes, contributing factors, detection gaps, and response friction.
8. Treat an agent’s explanation as a hypothesis, not authoritative evidence.
9. Assign corrective actions to named owners with due dates, verification methods, and rollback plans.
10. Turn the incident into regression cases and control tests.
11. Keep the postmortem separate from the decision to re-enable production.
12. Publish durable context changes through normal review and role checks.

The postmortem does not grant runtime access, approve a change, establish legal conclusions, or prove that a model consumed context. Each of those claims needs evidence and authorization from the system or owner responsible for that boundary.

What Is an AI Agent Postmortem Template?

An AI agent postmortem template is a repeatable structure for analyzing an incident after immediate response and recovery work have stabilized the system.

It extends a normal software or security postmortem with questions that agent systems create:

• Which instructions, Knowledge, Skills, Memory, retrieved data, tool results, and messages shaped the run?
• Which content was authoritative, and which content was untrusted data?
• Which user, agent, tenant, credential, delegated grant, and approval applied to each action?
• What did the agent request, what did a tool return, and what did the target system commit?
• Did the evidence prove context compilation, response issuance, integration acknowledgment, host injection, or model consumption?
• Did queues, retries, child agents, callbacks, or downstream systems create more effects after containment?
• Which corrective change prevents recurrence, and how will the team verify it?

NIST SP 800-61 Rev. 3 places lessons learned and improvement throughout incident response. Google’s blameless postmortem guidance focuses analysis on systems and process so teams can identify actions that reduce repeat failures. NIST’s AI RMF Core calls for documented risks, incident identification, monitoring, feedback, and continuous risk management. This template applies those practices to agent context, authority, tools, and external effects.

Postmortem, Incident Record, and Response Plan

These documents connect, but each has a different job.

Record	Main question	When it is used
Incident response plan	How will the organization coordinate incidents?	Before, during, and after incidents
Runbook	How will operators diagnose, stop, and recover one workflow?	Normal operation and known failures
Incident record	What is known, decided, and done right now?	During response
Postmortem	Why did this happen, and what changes next?	After stabilization
Corrective-action tracker	Who owns each change, and was it verified?	After review through closure

Use the AI agent incident response plan template to define command, evidence, communication, and recovery before an event. Use the AI agent incident response guide during the event. The postmortem should link to those records and exact versions instead of copying mutable summaries.

How to Use This AI Agent Postmortem Template

Create one postmortem for one incident ID. Name an author and reviewer, set the access level, and define which facts are still under investigation. Use a protected evidence store for raw records. Put references and safe summaries in the postmortem rather than secrets, authorization headers, credentials, unnecessary personal data, exploit details that create avoidable risk, or private model reasoning.

The download has 12 sections:

1. Postmortem record and review status
2. Executive summary and impact
3. Timeline and recovery milestones
4. Agent, workflow, and exact-version inventory
5. Decision-time context and provenance
6. Identity, authorization, approvals, and human checkpoints
7. Tool, action, and external-effect reconciliation
8. Detection, response, and evidence quality
9. Root causes and contributing factors
10. Corrective actions and regression cases
11. Re-enable decision and follow-up verification
12. Distribution, learning, review, and closure

Mark every important statement as fact, inference, or unknown. Cite the evidence behind facts and the reasoning behind inferences. If two records conflict, keep the conflict visible until an accountable reviewer resolves it.

1. Establish the Postmortem Record

Record the incident ID, title, severity, status, incident start and end, detection time, containment time, recovery time, postmortem owner, reviewers, affected services, and evidence location. Keep the original incident severity and the final assessed severity when they differ.

Define status values such as draft, in review, accepted, follow-up open, and closed. Acceptance means reviewers agree that the record is fit for learning and action. It does not mean every corrective action is complete or that production is approved.

Set distribution and retention before writing sensitive detail. A sanitized internal version may be appropriate when raw evidence contains personal data, customer content, security-sensitive details, or information subject to legal hold.

2. Measure Impact Before Explaining Cause

Start with what happened and its effect. Name affected users, tenants, data classes, workflows, systems, business processes, geographic regions, and time windows. Quantify unauthorized reads or writes, incorrect messages, duplicate transactions, delayed work, financial loss, support volume, downtime, and recovery effort where evidence supports those figures.

Keep confirmed impact separate from possible impact. State the basis for each number and when it was last checked. Avoid converting a worst-case scenario into a claimed event.

The summary should fit in a few paragraphs: what the agent was meant to do, what happened, the confirmed impact, how the team contained it, the main causes, and the most important corrective actions. Write it last, after the evidence and cause analysis are reviewed.

3. Build a Factual Timeline

Use timestamps from independently controlled systems where possible. Include the triggering input, context assembly, agent responses, authorization decisions, approvals, tool requests, target-system effects, alerts, declarations, containment steps, recovery stages, communications, and later discoveries.

For each event, record the time zone, source, actor, action, result, and confidence. Clock skew and delayed ingestion can change the apparent order, so note time-source quality and normalize timestamps before drawing conclusions.

Do not paste an unfiltered transcript and call it a timeline. A useful timeline connects decisions and effects while preserving links to the full evidence.

4. Pin the Exact System Versions

Agent behavior can change when any part of the decision environment changes. Record exact versions or digests for:

• Agent and workflow configuration
• Model, runtime, harness, and sampling configuration
• System instructions, policies, Knowledge, Skills, and Memory
• Retrieval indexes and source snapshots
• Tool schemas, adapters, gateways, and downstream APIs
• Identity policies, delegated grants, and approval rules
• Application releases, feature flags, dependencies, and infrastructure

Avoid references such as “the current policy” or “the production prompt.” Link immutable versions. If the team cannot recover a version, record that evidence gap and add a corrective action.

5. Reconstruct Decision-Time Context

Document what the context service compiled and what the integration issued. If available, add separate authenticated evidence that the host inserted the bundle into the intended request or session.

One evidence stage does not prove the next. Compilation does not prove response issuance. Issuance does not prove integration acknowledgment. Acknowledgment does not prove host injection. Injection does not prove model consumption. Record model consumption only from direct, authenticated attestation by a trusted integration or provider, including the evidence source and trust level. Otherwise mark consumption unknown.

Check authority and provenance. System and organizational instructions can bind behavior within their scope. An authorized user request can direct work within its existing scope, but it cannot grant itself access, approval, or higher authority. Data embedded in a request, retrieved pages, email, documents, messages, Artifacts, MCP tool results, and agent output are untrusted content. MCP tool results are Runtime context. Artifacts and messages have no instruction authority. Trusted controls must not allow untrusted content to grant access, approve an action, change instruction authority, or select a sensitive tool. Verify that enforcement at the authorization and tool boundary.

Permissions govern repository access. Always routes independently govern delivery and do not grant repository permission. The postmortem should test both boundaries rather than assuming a delivered Resource was also discoverable or editable.

6. Check Identity, Authorization, and Approval

For every consequential action, record the authenticated principal, agent identity, tenant, delegated authority, requested operation, bound parameters, policy version, authorization result, approval requirement, approval record, and expiry.

Model refusal is not an authorization control. Trusted gateways, policy engines, adapters, or target systems should deny unauthorized operations by default and check current authorization for every operation.

Review whether a human checkpoint had enough information and time to make the decision. A click is not meaningful approval if the reviewer could not see the exact action, target, scope, parameters, risk, and expiry. Check for replay, stale approvals, concurrent use, parameter substitution, and approvals issued by the same compromised path under investigation.

7. Reconcile Tools and External Effects

Separate tool requests, tool results, and real-world effects. A successful tool response may not prove that a target committed the change, and a timeout may hide a completed action.

Track each intended or requested external effect until the authoritative target classifies it as committed, rejected, rolled back, compensated, pending, unknown, or not attempted. Include side effects created by retries, queues, callbacks, child agents, and downstream workflows.

Do not blindly retry an operation with an unknown outcome. Query the target first. Reuse the original target-side idempotency key with identical bound parameters only when the target contract permits it. If the original key is missing or expired, keep the result unknown until an authorized reconciliation process decides the next action.

The OWASP AI Agent Security Cheat Sheet recommends treating external content as untrusted, using least privilege, isolating memory, validating tool calls, monitoring behavior, and requiring human approval for high-impact actions. The postmortem should test whether those controls existed and operated, not only whether the agent was instructed to behave safely.

8. Review Detection and Response Quality

Ask how the team learned about the incident, which signal should have detected it, and why that signal did or did not work. Measure time to detect, declare, contain, reconcile, recover, and communicate. Note missing owners, unavailable runbooks, noisy alerts, inaccessible evidence, slow revocation, failed stop controls, and manual steps that increased impact.

Review evidence quality as a control. For each source, record the evidence ID, immutable version, byte size, media type, digest, approved algorithm, collector, collection time, access limits, and retention. A digest can show that bytes changed after collection, but it cannot prove the source was complete or true.

An agent’s self-report may help form a hypothesis. It cannot replace logs from the authorization layer, tool gateway, target system, or other independently controlled source.

9. Find Root Causes Without Forcing One Answer

Separate five concepts:

• Trigger: The event that started the failure sequence
• Root cause: A condition that, if corrected, would prevent the same failure path
• Contributing factor: A condition that increased likelihood or impact
• Detection gap: A reason the team did not identify the problem sooner
• Response gap: A reason containment or recovery took longer or caused more risk

Investigate several cause classes before settling on a prompt change: requirements, data and retrieval, context and instructions, routing and Memory, model and runtime behavior, tool and integration design, identity and authorization, approval, deployment, monitoring, ownership, and business process.

Ask why each control allowed the next step, but do not force a single chain when the evidence shows several independent failures. Record alternative hypotheses and disconfirming evidence. A blameless review still names missed decisions and weak controls; it avoids treating an individual’s mistake as the end of the analysis.

10. Turn Findings Into Verified Corrective Actions

Each corrective action needs a finding, action, owner, due date, priority, status, verification method, regression case, rollback plan, and evidence link. Prefer controls that prevent, contain, or quickly expose the failure over reminders that depend on perfect attention.

Create regression cases from the triggering input and nearby variants using sanitized or synthetic data. Test the authorization boundary, approval binding, tool validation, context authority, stop path, effect reconciliation, and monitoring signal where relevant.

A merged code change or edited prompt is not proof of correction. Record the test result, environment, exact versions, reviewer, and later production verification. Track overdue actions through the same governance used for other operational risk.

11. Keep Re-Enable Approval Separate

The postmortem informs recovery, but acceptance of the document does not approve production. Re-enable decisions should bind the incident ID, repaired version, tenant and user scope, tools, permissions, rate and spend limits, monitoring period, stop conditions, approver authority, policy version, approval time, and expiry.

Stage recovery where risk calls for it: isolated test, read-only use, human-approved effects, bounded production, then normal operation. Recheck unresolved risks at each stage. If a corrective action remains open, name the authorized owner who accepted that risk and the date it must be reviewed again.

12. Distribute Lessons Through Governed Channels

Share a version appropriate to each audience. Remove secrets, vulnerable implementation detail, unnecessary personal data, customer content, and unsupported claims. Qualified legal, privacy, security, compliance, and business owners should decide reporting and disclosure duties. The template does not determine those obligations.

Move durable lessons into the system that owns them. Proposed changes to Knowledge and Skills should follow review and publication. Working Memory is versioned and audited but does not use publication. Temporary incident instructions should have an owner and expiry. Do not copy raw incident content into agent context, because it may contain untrusted instructions or sensitive data.

Close the postmortem when reviewers accept the analysis, effect states are reconciled or formally owned, corrective actions are tracked, regression cases are assigned, and follow-up verification has a date. Close the incident only under the organization’s incident process.

Where Alignbase Fits

Alignbase is the Agent Operations Platform. It stores governed Knowledge and Skills plus versioned working Memory, independently routes Knowledge, Skills, and Memory to agents, and records which versions it compiled and issued for supported integrations.

Those records can help a postmortem compare intended context with served context and inspect the exact published Knowledge and Skill versions and working Memory involved. They do not prove runtime authorization, host injection, model consumption, tool execution, external effects, or business outcomes. Those claims need evidence from the systems that control or observe each boundary.

The Alignbase blog covers the related work of agent monitoring, context governance, runbooks, evaluation, and incident response. The AI agent audit logs guide explains how to connect context delivery, authorization, tool, approval, and outcome records before a postmortem needs them.

An AI agent postmortem is useful when it leaves the team with a defensible account of what happened and verified work that reduces repeat risk. Keep the facts traceable, keep unknowns visible, and follow every corrective action through evidence of operation.