AI Agent Requirements Specification — is a verifiable contract between the business, the user, the developer, and operations. It describes not only the “role and tone,” but also the target intents, sources, tools, permissions, states, errors, human review, eval, logs, and acceptance artifacts.
A standard spec for a form and API is not enough: model responses are nondeterministic, quality depends on context, and a tool call can change the real system. That is why a requirement like “95% accuracy” without a dataset, a definition, and critical failures is not suitable for acceptance.
Short answer: start with a one-page project brief: owner, users, one outcome, in/out of scope, critical failure, data contour, and approval. Then add the intent contract, source registry, tool cards, authority matrix, state machine, frozen eval, and evidence package. Acceptance is based on a fixed version of the model/prompt/index/tools, not an open-ended demo.
Key points in one minute
- Define the outcome and current baseline before choosing a model.
- Each intent has inputs, output, evidence, tools, and stop conditions.
- Each source has an owner, version, access, and authority.
- Read and write are separate tool permissions.
- Uncertainty leads to clarification or handoff, not fabrication.
- Eval includes standard, edge, unauthorized, and adversarial cases.
- The client receives code, configs, evals, logs, runbooks, and exports.
Contents
- AGENT method
- Project brief
- Intents and boundaries
- Sources and data
- Tools and permissions
- States and errors
- Human control
- Security
- Eval and metrics
- Logs and NFRs
- Acceptance and handover
- FAQ
- How AI Dawn prepares an AI agent specification
- Conclusion
AGENT method
- A — Actors and objective: who is asking, who gets the benefit, who is responsible.
- G — Boundaries: in/out of scope, prohibited actions, uncertainty, and escalation.
- E — Evidence: sources, versions, citations, data quality, and provenance.
- N — Toolset: schemas, rights, confirmation, idempotency, and rollback.
- T — Tests: representative eval, guardrails, monitoring, and acceptance evidence.
Project brief
One page includes: problem/current workflow, users/affected parties, owner, primary outcome/baseline, scope, top risks, data classification, human decision, launch mode, and stop authority. The brief is approved before the detailed specification.
Requirements for legality, privacy, and sector rules are approved by qualified people. NIST GAI Profile is useful as a cross-industry risk reference, but it does not replace specific regulations.
Intents and boundaries
| Intent card fields | Content |
|---|---|
| trigger/actor | how it starts and who has permission |
| required input | fields, context, identity level |
| output | schema, evidence, confidence/unknown |
| tools | read/write, preconditions, limits |
| completion | verifiable terminal state |
| handoff | triggers, queue, context, owner |
| critical fail | an error that blocks release |
Out of scope is written just as specifically: does not sign, does not change permissions, does not determine the legal/medical outcome, does not write to production without approval — if those boundaries are needed.
Sources and data
Source card: system/URI, owner, authority, scope, effective/version, refresh, access, retention, and conflict rule. The spec defines which answer requires citation, what to do in case of stale/conflict/not found, and how to avoid showing an unauthorized fragment.
For RAG, describe ingestion, chunk metadata, ACL, retrieval, citations, deletion, and index version. Detailed architecture is in the RAG guide.
Tools and permissions
Tool card: purpose, input/output JSON schema, identity/role, read/write, preconditions, confirmation, timeout, retry, idempotency, partial result, reconciliation, rate/cost limit, audit fields, and rollback/compensation. The LLM does not generate arbitrary API requests: the gateway validates schema and policy.
The authority matrix maps actor × intent × tool × data × environment. The agent does not inherit the full permissions of a service account “because it is easier that way.”
States and errors
Action truth table separates proposed, awaiting_confirmation, submitted, confirmed, rejected, failed, unknown and compensated. A tool HTTP 200 response does not always mean business completion. After a timeout, the agent checks status first instead of blindly repeating the write.
Ambiguous input, missing source, tool unavailable, unauthorized access, rate limit, partial success, stale state, and human unavailable are specified. Each failure has a user message, internal state, retry owner, and terminal outcome.
Human control
For each outcome, set auto, review, approve, two-person or prohibited. The reviewer sees the input, sources, proposed action, affected object, diff, and uncertainty. Approval is tied to specific parameters and expires if they change.
Handoff includes queue, owner/SLA, transcript, summary, evidence, actions, reason, and next safe step. In manual mode, the bot does not interrupt the operator.
Security
The OWASP list for agentic applications highlights behavior hijacking, tool misuse, and identity/privilege abuse. Microsoft guidance notes that every agent–tool/service connection expands the attack surface.
The specification includes a threat model, trust boundaries, prompt-injection tests, least privilege, secret isolation/rotation, egress/tool allowlists, data minimization, sandboxing, confirmation, audit, rate/spend limits, incident response, kill switch, and recovery. Retrieved text and tool output are always untrusted.
Evaluation and metrics
| Layer | Primary | Critical guardrail |
|---|---|---|
| intent | correct route | unsafe/missed escalation |
| RAG | supported answer | invented/stale source |
| tool selection | correct tool/schema | unauthorized tool |
| action | confirmed outcome | wrong/duplicate write |
| human | accepted useful output | hidden material uncertainty |
| operations | latency/completion | stuck state/unnoticed failure |
A frozen eval includes representative, edge, missing, conflicting, unauthorized, injection, tool-failure, and handoff cases. Thresholds are set by intent and severity. NIST AI RMF Core requires documenting test sets, metrics, tools, and checking conditions similar to deployment.
Logs and NFRs
Trace: request/conversation/actor IDs; model/prompt/policy/index/tool versions; retrieval IDs; tool inputs/outputs with redaction; approvals; latency; tokens/cost; errors; final state. The log itself must not create a leak.
NFRs: availability/degraded mode, latency distributions, capacity/rate, recovery, retention/deletion, localization/accessibility, model/provider fallback, change/regression gate, monitoring/alert ownership, cost budgets, and decommissioning. Numbers are set after the baseline, not copied from someone else's specification.
Acceptance and handover
Acceptance is performed on a release candidate with frozen eval and raw results export. Separately: functional intents, critical guardrails, security/adversarial, permissions, failure/recovery, performance/cost, handoff, and rollback.
Source/code, environment/config, prompt/policy, tool schemas, data/index pipeline, evals/graders/answers, dashboards/alerts, runbooks, architecture/data-flow/threat model, decision log, credentials rotation procedure, training, and export/decommission are handed over. The link between the specification and the fast experiment is in the AI MVP plan.
Frequently asked questions
Do I need to specify the model in the specification?
Record the release model/version for reproducibility, but describe acceptance by behavior. Then a model change can be verified with a regression eval.
How do I define accuracy?
By intent and operation: classification, retrieval, supported facts, tool/action outcome. Describe the dataset, denominator, scorer, uncertainty, threshold, and critical failures.
Do I need the system prompt in the specification?
You need requirements for behavior, authority, and boundaries. The prompt is one versioned implementation artifact, not the entire specification.
Who approves the specification?
The business/process owner, product/analyst, domain reviewer, IT/data, security/privacy/legal as applicable, and the acceptance owner. The developer does not approve business risk on the customer's behalf.
How do you accept an agent without real write actions?
Use a sandbox/stub, recorded fixtures, and shadow mode. Verify schema, selection, approval, idempotency, status/reconciliation, and rollback before granting production permission.
What if the API does not exist yet?
Describe the expected contract and the mock separately, and leave the blocker as Unknown. Do not accept integration based on a mock as if it were a production connection.
How AI Dawn prepares the specification and AI agent
AI Dawn can review the process, assemble the brief and specification, prepare source/tool/authority contracts and evals, build the RAG/agent/integrations, configure human review, security, observability, acceptance, launch, training, and support.
The safest first step is to choose one intent, assign an owner and users, fix the baseline, outcome, out-of-scope, sources, one read-only tool, approval, and critical failure, then build a representative eval. Discuss the task.
Conclusion
A strong spec for an AI agent describes not the model’s magic, but a repeatable sociotechnical process. The AGENT connects actors, boundaries, evidence, tools, and tests.
Treat every intent, source, tool, and failure under an explicit contract. Keep human authority for material actions and require raw evidence instead of accepting results by visual inspection.