AI agent brief & specification template
Turn a vague AI-agent idea into a specification someone can review, build and test, before anyone writes a line of code or a system prompt.
This free workbook walks you through the purpose, tasks, context, tools, rules, outputs and acceptance tests of one agent — then assembles them into a single handoff document.
9 structured worksheets · Rules & escalation · Acceptance tests · No technical knowledge needed
The problem
Most agent ideas are one sentence long.
“An agent that handles support.” “An agent that helps with leads.” It sounds clear until someone has to build it, and then every important decision is still open.
Whoever builds it fills those gaps with guesses. You find out which guesses were wrong once it is running.
Who is it actually for?
What starts it?
What is it allowed to change?
When must it stop and ask?
How will you know it works?
Definition
What is an AI agent specification?
An AI agent specification defines what an agent should do, for whom, with what information and tools, inside which rules — and how you will test that it behaves that way.
It is a business and operational document, not a technical design. It says what has to be true. How to make it true is left to whoever builds it.
What to specify
Seven things every agent specification has to answer.
A simple example
Same idea. Specified.
Weak concept
An agent that helps with leads.
The user, trigger, tasks, authority, output and success criteria are all undefined.
Stronger concept
An agent that reviews newly submitted lead forms, checks them against approved qualification criteria, drafts a qualification summary, and routes uncertain cases to a sales manager for review.
The responsibility, starting point, output and human escalation point are visible enough to specify further.
The stronger version still isn’t a specification. But it is specific enough to start one, and the workbook takes it the rest of the way.
How to build it
Eight steps, one agent.
Use one copy of the workbook per agent and work through the sheets in order. Each step produces something the next one depends on.
- 01
Write the brief
Define the user, the problem, the outcome, the scope and the default level of autonomy.
- 02
Break it into tasks
Observable responsibilities, each with a trigger, the decisions involved, the human’s part and the result.
- 03
Map context and inputs
The information each task depends on, its source, how current it must be, and what happens without it.
- 04
Specify tools and actions
What the agent may read, send, write or change — and the minimum permission each one needs.
- 05
Set rules and escalation
Boundaries, approval points, how uncertainty is handled, and who gets the case when the agent stops.
- 06
Define outputs and interaction
How people start the agent, what usable output it must produce, and what they can do next.
- 07
Write acceptance tests
Turn requirements into scenarios with pass criteria you can observe, not just plausible answers.
- 08
Review the final specification
Read the assembled summary, resolve the open questions, then decide whether it is ready for build.
The important part
Decide where autonomy stops.
The question that matters most is not what the agent can do. It is what it may do on its own, and what it must hand back to a person.
Pick the safest default that still delivers the outcome, then make individual tasks stricter where the risk is higher. A workflow that implies an action does not, on its own, justify permission to take it.
Default autonomy, safest first
- 1
Advises only
Recommends. A person decides and does everything.
- 2
Drafts for approval
Prepares the work. Nothing leaves until a person approves it.
- 3
Acts after explicit approval
Can take the action itself, but only after a yes.
- 4
Performs predefined actions independently
Acts alone, but only on low-risk actions you have listed in advance.
Five kinds of rule.
Every boundary in the workbook is one of these, which makes them easy to review and easy to test.
Must
Show the criteria used and the reason for every recommendation.
Must Not
Do not infer a missing business fact. Mark it missing and stop that decision.
Ask First
Get manager approval before any rejection with external consequences.
Escalate
When submitted information conflicts with the criteria, hand it to Sales Ops.
Verify
Check a value against its authoritative source before relying on it.
How you’ll know it works
Write the tests before it’s built.
A plausible answer is not proof that an agent behaves as specified. Acceptance tests turn each requirement into a scenario with a pass condition you can actually observe.
The useful tests are rarely the happy path. They are the missing input, the request outside scope and the action that needed approval.
- Category
- Boundary
- Scenario
- Required qualification information is missing
- Input
- A lead submission with one required field left blank
- Expected
- The agent names the missing field, does not infer a value, and routes the case for review
- Pass if
- No fabricated value, no final decision issued, and the defined human review is requested
The workbook
Specify the agent once. Hand it over with confidence.
Everything above is on this page for free. The workbook does the part a webpage can’t: capture each decision in a structured place, track readiness, and assemble it all into one specification.
ai-agent-brief-and-specification-template.xlsx
XLSX · 9 worksheets
Enter your email and we’ll send the template straight to your inbox. Free, no account, no card.
We may email you occasionally for feedback, or to tell you about new Cognardo resources. Unsubscribe any time.
Built-in reviewers
Let AI find the gaps. Not fill them.
Each sheet ends with an optional prompt you can paste into ChatGPT, Claude or Gemini along with what you’ve written. It looks for vague responsibilities, missing inputs, unapproved actions and untested requirements.
Every prompt returns questions and risks for you to decide on. None of them invents permissions, sources or business rules on your behalf.
9 optional AI assists
The finish line
What “Ready for build” means.
The Final Specification sheet ends with one status. It is worth being precise about what that status does and doesn’t claim.
It means
- The business and operational specification is defined well enough for implementation review
- Major open questions have been resolved, or deliberately deferred
- A human has reviewed it
It does not certify that
- The technical architecture is sound
- It is secure or compliant
- It is safe to run in production
- It is feasible to build as written
Where it helps
One specification, every conversation about the agent.
Briefing a developer or agency
Hand over a specification they can quote and build against, instead of a paragraph and a call.
Building it yourself
In a no-code agent builder, a custom GPT or Claude project — know what it should do before you start.
Getting sign-off
Give managers, legal or operations one document showing what the agent may and may not do.
Testing a delivered agent
Run the acceptance scenarios against what was built and record pass, fail or needs revision.
Comparing options
Use the same specification to evaluate vendors or platforms on the same requirements.
Changing an existing agent
Version the specification so a change in scope or permissions is a recorded decision.
Keep it where you work
Keep your agent instructions one click away.
Once the specification is done, its brief, rules and review prompts get reused constantly. Workbench is our browser extension for exactly that — keep prompts and context organised, fill the variables in a form, and run them without leaving ChatGPT, Claude or Gemini.
FAQ
Questions, answered.
What is an AI agent specification?+
A structured description of what an AI agent should do, for whom, with what information and tools, inside which rules — and how you will test that it behaves that way. It is a business and operational document, not a technical design: it defines the requirements an implementation has to meet.
What is the difference between an agent brief and an agent specification?+
The brief is the short version: purpose, primary user, outcome, scope and autonomy. The specification builds on it with tasks, context, tools, rules, outputs and acceptance tests. In this workbook the brief is the first sheet, and the Final Specification sheet assembles everything into one handoff view.
Do I need to be technical to use it?+
No. It was written for the person who understands the work, not the code. It deliberately avoids architecture, models and frameworks. Those are decisions for whoever builds the agent, and they are easier to make once the requirements are clear.
How much autonomy should an AI agent have?+
As little as the work allows. Start from the safest level that still delivers the outcome, usually drafts for approval, and make individual tasks more restrictive where needed. Anything sensitive, irreversible or externally visible should have an explicit human approval rule.
Can I use it for a custom GPT, a Claude project or a no-code agent?+
Yes. The specification is platform-neutral. Once it is complete, the brief, rules and outputs translate directly into instructions, and the acceptance tests tell you whether the result actually behaves as specified.
How do I test an AI agent before I rely on it?+
Write the tests before it is built. For each important requirement, describe a scenario, the input, the behaviour you expect and an observable pass condition. Cover normal tasks, but also missing inputs, scope boundaries, permissions, approval points and failures, because those are where agents usually go wrong.
Does “Ready for build” mean the agent is safe to deploy?+
No. It means the business requirements are defined well enough for implementation review. It does not certify architecture, security, compliance, production safety or feasibility. A qualified person should still review those where they matter.