A good AI agent specification makes the result testable before you pay for a large project. It should explain what data the assistant receives, what it may do and how the team will notice an error. “We need a smart sales assistant” does not define those boundaries.
This guide develops the document using an illustrative example: an assistant prepares a catalogue-based draft reply for a sales representative. You can complete requirements, collect examples and discuss the solution with different providers using shared terms. You do not need to choose a model or buy a platform before preparing the specification.
Describe the work from the employee's perspective
Start with a short account: an employee receives a product question, finds specifications and terms in approved documents, prepares a reply and checks it. The assistant should reduce search and drafting time. The employee retains the decision to send.
Explain why this is a problem now. Information may be spread across the catalogue and instructions, requiring several files to be opened. Measuring time on a few comparable enquiries is enough for an initial assessment. Do not put invented savings in the requirements.
List the first stage's boundaries separately. Our example excludes negotiation, autonomous discounts, payment, sending customer messages and changing the CRM. Those functions can be considered later as separate tasks with separate checks.
Define inputs and the output format
List required data and behaviour when it is missing. If a product code is needed to select the correct manual, the right action is to request clarification. Do not force the agent to answer an incomplete question at any cost.
| Element | Example requirement | Check |
|---|---|---|
| Input | Question, product code, response language | An unknown code triggers clarification |
| Draft | Concise answer containing confirmed terms | No specifications based on assumptions |
| Sources | Document and relevant section | The employee can open the link |
| Uncertainties | List of missing or disputed information | Conflicts are not concealed |
Describe successful output without relying on elegant prose: the employee understands the answer, sees its basis and knows what needs clarification. If another program receives the result, the developer separately specifies field formats and required-value validation.
Show a good result and an unacceptable one. A fictional product with clearly labelled illustrative specifications is sufficient. Do not present it as the company's actual catalogue.
Create a source register
Every source needs an owner, storage location, update process and priority when information conflicts. Uploading documents to a “knowledge base” does not make them correct. An old price list may look just as convincing as a current one.
| Source | Owner | Usage rule |
|---|---|---|
| Product catalogue | Product range owner | Use the approved version |
| Manufacturer's manual | Technical specialist | Check that it matches the model |
| Sales terms | Head of sales | Do not override individual agreements |
Define how the agent learns about updates and what it does before receiving them. For example, if current terms are unavailable, it drafts only the confirmed part and hands the question to a staff member. Different sources may need different freshness rules; “update monthly” is not a universal solution.
Also identify information excluded from this scenario: restricted customer correspondence, personal data or internal calculations unnecessary for the answer. Use anonymised examples when discussing the project with a provider; transfer live access separately.
Build an action matrix
Separate reading, drafting and changing data. “CRM access” is too broad. Reading a record, creating a note, sending an email and deleting a record have different consequences.
| Action | Pilot rule | Who checks |
|---|---|---|
| Find catalogue information | Allowed within the approved knowledge base | Employee verifies the source |
| Prepare a response | Draft only | Employee edits it |
| Send a proposal | Excluded from the first stage | A person sends it manually |
| Change a price | Prohibited | Verified by a negative test |
If a later stage needs human approval, state precisely what is approved: the action, recipient and final parameters. Approving the general intention to “reply to the customer” must not become permission for any wording.
n8n offers a mechanism for approving individual tool calls. This is one implementation example, not a mandatory platform choice. The requirement should hold regardless of the tool: a restricted action cannot happen without the specified approval.
Describe exceptions and human handoff
Write exceptions as “if — then” rules. If the product is not found, ask for its code. If documents conflict, show both sources to the owner. If a service is unavailable, retain the task and report that no result was obtained. If a question is outside scope, pass it to an employee.
A handoff needs a recipient and useful context: the original question, information found and reason for stopping. “Something went wrong” does not help anyone continue.
Set retry and spending limits per run. If the process calls several services, the total limit matters, not just one model request's price. A failed chain must not retry indefinitely. Determine actual values through testing and the selected services' capabilities.
Provide separate stop instructions: who disables agent actions, how manual work continues and how the queue is reviewed later. A saved draft must not send automatically after connectivity returns without the required check.
Prepare acceptance examples before development
Include an ordinary request, incomplete data, an unknown product, an outdated source, a contradiction and an attempt to push the assistant outside its task. Define the permitted action and critical error for each.
Test K-04. A question about delivery time for a fictional product. No delivery time appears in the sources. Expected: the agent gives no date, states that confirmed information is unavailable and suggests that the employee clarify the timing. Critical error: an invented date or promise to the customer. Test several phrasings of the question.
Keep some examples for an independent check after configuration. Save versions of data and results so that changes can be compared with earlier behaviour. The input-and-expected-output approach is described in the n8n guide to AI workflow evaluation.
Assess facts, compliance with prohibitions, completeness and employee effort separately. “We liked the answer” does not explain whether the system is usable. One successful demonstration is insufficient for critical requirements.
Include operating requirements
- Who owns accounts and can revoke the provider's access.
- Where runs, spending and unfinished tasks are visible.
- Which data is retained, who can see it and when it is deleted.
- Who updates sources and checks configuration changes.
- How to report a problem and return to the previous working version.
- Which materials, instructions and source files are handed to the company.
Do not require indiscriminate logging. Investigation may need only a task identifier, source versions, status and error category. Retaining complete customer messages requires a separate access and storage decision.
Clarify dependence on the provider. If only the system's author can add a new document, record that limitation and the maintenance cost. It may be acceptable for the first stage, but it should not be hidden.
A short specification template to complete
User: [role]. Task: [one action]. Current method: [steps and measured time]. Input: [fields and channel]. Output: [format, sources, uncertainties].
Allowed: [reading and drafting]. Human approval required: [action and parameters]. Prohibited: [boundaries]. Sources: [owner, version, updates]. Missing information: [clarification or handoff].
Testing: [scenarios and criteria]. Stop: [conditions and owner]. Costs: [limits and monitoring method]. Handover: [accounts, instructions, materials]. The first stage ends with [verifiable pilot result].
Ask the provider to identify unknowns and propose the smallest useful test. If documents and access must be investigated first, treat that as separate work with its own deliverable. Do not blend it with a promise of a completed agent.
When to postpone development
If sources conflict, no reviewer is available or the task occurs once a month, try ordinary search and response templates first. If every decision requires lengthy human investigation, generating a draft may not reduce the work. Test a few examples before ordering development.
Use the completed specification yourself or share it with your chosen specialist. The next step is a limited pilot that checks value. Start describing the business process with the free process brief.
Specification glossary
- Agent tool — a permitted programmatic action, such as document search.
- Knowledge base — prepared sources for answers that need to be kept current.
- Holdout sample — examples for checking an already configured version.
- Negative test — a check that a prohibited action actually does not happen.
- Version — a recorded state of settings and sources for reproducible testing.
Apply this to your task
Specify one agent scenario and connect every material permission or restriction to a test.
AI agent requirements: open the worksheet · Download the CSV to complete. Free access, no registration. Use it yourself or share it with your provider.