Template 03 — Agent Card

Purpose

The single document that defines an agent. Every reviewer downstream works from this card. Without it, security review, RAI review, identity provisioning, build, eval, pilot, and production gates all re-derive context from scratch.

The Agent Card is the agent's contract: what it does, what it doesn't, what data it sees, what it can act on, when humans approve, how it fails, how it's monitored, how it retires. Every field is enforceable — if the running agent doesn't match its card, that's a defect.

• When you use it: After approval (M8), before build (M11). Lives in source control next to the agent's code.
• Who fills it: Agent Builder.
• Who reviews: Department Champion (Section 3 scope, Section 9 HITL), Security (Section 5/6/8 data + identity), Legal (Section 4/10 risk + failure modes), CoE Lead (overall sign-off).
• Format: Markdown file in the agent's source-control folder. Versioned. Updated when scope materially changes.

Worked example (AP Accountant invoice reconciliation)

"Agent Card v1.0 for finance-invoice-recon, drafted by the Builder (CoE Lead + Finance Champion) on 2026-04-22 after approval at M8."

agent_card_version: 1.0
created: 2026-04-22
last_revised: 2026-04-22
agent_status: Approved → Build (M11 next)

§1 — Identity

§2 — Purpose (workflow + KPI)

This agent assists the AP accountant by reading incoming vendor invoice PDFs from her Gmail mailbox, extracting structured fields (vendor name, total amount, line items, PO reference), looking up the matching open PO in NetSuite, scoring match confidence, and drafting a reconciliation proposal as an email back to the accountant for review.

KPI (target):

§3 — Scope (do / not do)

Will do:

• Parse vendor invoice PDFs from Gmail
• Look up matching open POs in NetSuite (read-only)
• Score match confidence (0.0–1.0)
• Draft a reconciliation proposal email to the accountant
• Flag exceptions (variance > 2%, vendor not found, multi-PO match)

Will NOT do:

• Send any email externally (drafts only, into the accountant's Gmail drafts folder)
• Write to NetSuite under any circumstance (read-only access only)
• Post journal entries
• Approve payments
• Modify vendor records
• Process emails outside the accountant's mailbox
• Touch customer PII (none in scope)
• Self-promote autonomy stage

§4 — Risk tier + risk-driver tags

§5 — Inputs / data sources + classification per source

Not accessed: any NetSuite write endpoint, any Gmail mailbox other than the named accountant's, any customer-facing system.

§6 — Outputs / tool calls + permission scope per call

LLM cost limits: $0.10 per invoice (hard cap, retry-loop guard kicks in at 3× baseline).

§7 — Autonomy level + explicit thresholds

Confidence thresholds:

• ≥ 80% match confidence → propose match to accountant
• 60–80% → propose match with "low confidence" flag
• < 60% → propose as exception requiring manual investigation

§8 — Identity & credentials (rotation policy)

Emergency revocation procedure (target: 60 seconds):

1. Disable agent-finance-invoice-recon user in Entra ID admin console
2. Set LaunchDarkly flag finance-invoice-recon-enabled to off
3. Verify in LangSmith no further executions

Tested: 2026-04-25 ✅ (60-second drill passed).

§9 — HITL gates (by rule)

§10 — Failure modes & worst-case action

Worst-case overall: A wrong match proposal lands in the accountant's drafts; she reviews and rejects. Cost: one human re-review. Acceptable.

§11 — Monitoring + alerts

Per-execution log fields (LangSmith):

• Timestamp (start + end)
• Agent ID + version
• Invocation source (Gmail trigger payload hash, NOT the email content)
• Input prompt (vendor parsed fields only — raw PDF bytes never logged)
• Output (proposed match + confidence + reasoning)
• Tool calls (NetSuite query, internal DB lookup)
• Model + version
• Tokens (in + out) + cost
• Policy checks fired (input validation, output schema, tool allowlist)
• HITL event (recorded when accountant approves/rejects)
• Latency per step
• Outcome (proposed / exception / error)
• Error stack trace (if any)

Dashboards (LangSmith + Datadog):

• Cost per invoice (target < $0.10)
• Match accuracy weekly (target ≥ 95%)
• HITL acceptance rate weekly (target ≥ 90%)
• Latency p50 / p95 (target p95 < 15s)
• Failure rate (target < 3%)
• Drift indicator (vs launch baseline)

Alerts (PagerDuty):

Audit log retention: 6 months in LangSmith, then archived to S3 Glacier for 7 years (SOX-adjacent for AP records).

§12 — Eval criteria + pre-prod test set

Golden dataset: 200 historical invoices from Q1 2026, anonymized, with human-verified correct PO matches.

Pass thresholds (must pass before pilot promotion):

Re-evaluation cadence: Re-run golden-set eval at every prompt change. Re-run red-team scenarios quarterly.

§13 — Retirement criteria

The agent will be retired (status → Retired in registry) when any of the following is true:

• KPI miss for 2 consecutive quarters (match accuracy < 90% OR HITL acceptance < 70%)
• NetSuite API undergoes breaking change requiring > 2 weeks of rewrite
• Replaced by a NetSuite-native AI matching feature with superior accuracy
• AP Manager (Mike Chen) leaves without an identified successor Champion
• Risk appetite v[X.X] revoked the financial-action approvals this agent depends on
• Any Severity-1 incident traceable to the agent's design (not operational)

Retirement procedure: Follow templates/11-retirement-checklist.md.

Sign-off block

Blank template (copy below for your agent)

# Agent Card — [Agent Name]

```yaml
agent_card_version: 1.0
created: [YYYY-MM-DD]
last_revised: [YYYY-MM-DD]
agent_status: [Approved → Build / Build → Pilot / Pilot → Prod / Production / Retired]

§1 — Identity

§2 — Purpose (workflow + KPI)

[2–4 paragraphs: what workflow this agent serves, who the primary user is, what the agent does.]

KPI (target):

§3 — Scope (do / not do)

Will do:

• [Action 1]

Will NOT do:

• [Excluded action 1]
• [Excluded action 2 — be specific]

§4 — Risk tier + risk-driver tags

§5 — Inputs / data sources + classification per source

Not accessed: [explicit exclusions]

§6 — Outputs / tool calls + permission scope per call

LLM cost limits: [per-execution cap]

§7 — Autonomy level + explicit thresholds

Confidence thresholds: [explicit numeric thresholds]

§8 — Identity & credentials (rotation policy)

Emergency revocation procedure:

1. [Step]
2. [Step]

Tested: [Date + result]

§9 — HITL gates (by rule)

§10 — Failure modes & worst-case action

Worst-case overall: [single sentence]

§11 — Monitoring + alerts

Per-execution log fields:

• [List required fields from framework §24]

Dashboards:

• [List dashboards]

Alerts:

Audit log retention: [duration + medium]

§12 — Eval criteria + pre-prod test set

Golden dataset: [size + source]

Pass thresholds:

Re-evaluation cadence: [when]

§13 — Retirement criteria

The agent will be retired when any of the following is true:

• [Criterion 1 — be specific]
• [Criterion 2]

Retirement procedure: Follow templates/11-retirement-checklist.md.

Sign-off block

---

## Usage notes

- **Length:** Aim for 2–4 pages filled out. Longer than 6 pages = too much detail. Shorter than 1 page = not enough.
- **Source of truth:** This Card is what the build is measured against. If the running agent does something not in the Card, that's a defect, not a feature.
- **Versioning:** Bump version on any material change to Sections 3, 5, 6, 7, 9, 10. Re-sign on material changes.
- **Quarterly reconciliation:** At every quarterly review, walk the Card against what the agent actually does. Update if scope drifted; re-approve if drift was material.
- **Stage 3 (Autonomous) requires its own re-approval cycle.** Don't pre-authorize Stage 3 in the initial Card.

## Common pitfalls

| Pitfall | What it looks like | Fix |
|---|---|---|
| Vague scope | "Helps with invoices" | Step-by-step list of will/won't actions |
| Missing "will NOT" list | Only positive scope described | Add the explicit exclusion list |
| Over-permissive credentials | One service account with broad access | Separate credential per system in §8 |
| Soft HITL gates | "Human approves when needed" | Specific rules per trigger in §9 |
| Worst case not stated | No §10 row reads "what's the worst the agent could do?" | Force a worst-case sentence per failure mode |
| Eval thresholds not numeric | "Should be accurate" | Specific numeric pass thresholds in §12 |
| No retirement criteria | "We'll retire it when we don't need it" | Specific quantitative triggers in §13 |
| Card and reality drift | Card written once, never updated | Quarterly reconciliation in continuous monitoring |

## Framework cross-references

- `framework.md` §14 (the 13-section spec)
- `framework.md` §10 (risk classification — feeds §4)
- `framework.md` §17 (privileged identities — feeds §8)
- `framework.md` §19 (3 guardrail layers — feeds §6 + §9)
- `framework.md` §20 (5 control mechanisms — feeds §6 + §7 + §9)
- `framework.md` §21 (5 monitoring signals — feeds §11)
- `framework.md` §22 (autonomy progression — feeds §7)
- `framework.md` §24 (observability fields — feeds §11)
- `workflows.md` Step 5 (Agent Card written)
- `workflows.html` → In Action view → node M9 (Agent Card written)