AI Agent Specification Template: The Engineering Contract

FISTA's rule is that an agent is built only after its specification exists, and the specification is only finished when every section can be tested. This is the template, with guidance on what makes each section testable. It sits beneath the operational Digital FTE job description template and applies the method in spec-driven development explained to agents.

What does the template contain?

Section	Content	Test it maps to
1. Intent and scope	Outcome; case types in and out	Scope tests; out-of-scope cases in the golden set
2. Inputs	Sources, formats, schemas, trust level	Schema validation; untrusted-content handling tests
3. Outputs	Records, messages, artifacts with schemas	Output validation; end-state tests
4. Decision rules	Thresholds, sequences, exception taxonomy	Golden-dataset cases per rule and exception
5. Tools and permissions	Per action: tool, classification, principal, gate	Permission tests; gate tests
6. Prohibited actions	What must never happen	Permission boundaries; adversarial tests
7. Escalation	Triggers, handoff content, recipients	Scenario tests
8. Evaluation	Criteria, golden dataset, thresholds by category	The harness itself
9. Non-functional budgets	Latency, steps, tokens, cost per task	Measurements in the harness
10. Operations	Logging fields, monitoring, alerts, kill switch, rollback	Operational tests
11. Autonomy and change	Current level; evidence to advance; change process	Review records

How should intent and scope be written?

One paragraph on the outcome and why it matters, followed by explicit case types in scope and out of scope. Out-of-scope cases go into the golden dataset with escalation as the correct behavior, so scope is tested rather than assumed.

How are inputs and outputs specified?

Inputs list every source with its format and a trust level: system-of-record data is trusted; documents, emails, web content, and free-text fields are untrusted and handled as data, never instruction. Outputs are schemas for every record, message, or artifact the agent produces, validated on the agent's side before any tool call. Untrusted-content handling is described in what is indirect prompt injection.

How are decision rules written?

As a person would need them on their first day, with numbers: matching tolerances, routing thresholds, sequences, tie-breaks, and the exception taxonomy with the action for each category. Each rule becomes at least one golden-dataset case. Where a rule requires judgment, the spec says "human decides" and defines the handoff.

How are tools and permissions specified?

Tool	Action	Classification	Principal	Gate
CRM	Read contact	Read	Read-only, user-delegated	None
CRM	Update contact fields	Reversible write	Scoped writer	Sampling
Billing	Issue refund above threshold	Consequential	Withheld	Human approval

The classification drives principal, gate, and test depth, per how to design tool permissions for AI agents.

How are prohibited actions handled?

Listed explicitly and enforced as permission boundaries at the tool layer, with adversarial tests that attempt each through injected instructions. Prohibited actions that live only in the prompt are not controls.

What goes in the evaluation section?

The correctness criteria per output, the golden dataset's composition by category and difficulty, thresholds per category, zero-tolerance criteria, scoring methods (deterministic checks, rubric judges with calibration, end-state verification), and the production sampling plan. The build is described in how to build a golden dataset and the method in the evaluation-driven development whitepaper.

What are the non-functional and operational requirements?

Latency budgets at the relevant percentiles, step and token budgets per task, cost per task budget, logging fields (agent identity, delegated user, tool, parameters, outcome, trace identifier), monitoring and alert thresholds, the kill switch, and rollback. Operations design follows AI agent runbook template.

How is the specification maintained?

Versioned in the repository with the agent's code; reviewed like code; changes gated on regression; updated at every performance review with the exception analysis. A spec that has not changed in a year is a sign the review is not happening.

What does a completed section look like?

For an invoice-matching agent, the decision-rules section reads like a procedure with numbers: match quantity within the tolerance stated for the vendor class; match price within the percentage and absolute tolerances stated; treat a missing receipt as exception category two and route to the receiving team with the order attached; treat any invoice whose remittance details differ from the vendor master as category five and route to accounts payable control with the difference highlighted; never propose a match when the purchase order is closed. Each sentence maps to a golden-dataset case, and the two categories with routing map to escalation scenarios. The tools section lists the ERP read tool with a read-only principal, the match-proposal tool as a reversible write with sampling, and the posting tool as withheld, so the permission tests are written directly from it.

What are the common mistakes?

1. Rules without numbers.
2. Trust levels unstated, so documents become instructions.
3. Tools without classification.
4. Evaluation deferred to after the build.
5. Prohibited actions in the prompt only.

How does FISTA Solutions help?

FISTA Solutions writes this specification with process owners and security teams before building any AI agent, through forward deployed engineers, and installs the template across teams through AI enablement. FISTA has delivered 150+ projects for 50+ companies across 12+ countries.

To specify an agent with us, message FISTA on WhatsApp, or read spec-driven development with coding agents for the software-side counterpart.