Lesson 5. Technical Specification (TS) for an AI Agent#
Why This Matters#
A TS is a document where you describe what the agent should do. A good TS helps you understand the project yourself and hand it off to a developer or client.
Key Idea#
TS = project map
The TS answers: why the agent exists, what it does, how it works, what's needed to launch.
Structure of a TS for an AI Agent#
1. General Information
What to include:
- Project name
- Client (customer or your company)
- TS creation date
- TS author
Example:
Project name: AI agent for lead qualification at digital agency "WebPro"
Client: WebPro LLC
Date: 02/01/2026
Author: Ivan Petrov, AI consultant
2. Agent Goal and Tasks
What to include:
- Why the agent is needed
- What problem it solves
- What result is expected
Example:
Goal:
Automate initial lead qualification so managers receive only warm and hot leads.
Tasks:
- Collect data from the customer (task, budget, timeline)
- Evaluate the lead (hot/warm/cold)
- Hand off warm and hot leads to the manager
- Record all leads in Google Sheets for analytics
Expected result:
- 40% reduction in manager workload
- Response time to hot leads within 1 hour
- Data collection for analytics (all leads in one table)
3. Target Audience
What to include:
- Who will interact with the agent
- Knowledge level
- Expectations
Example:
Target audience:
- Potential clients of the digital agency
- Small and medium businesses
- Level: from beginner entrepreneurs to experienced marketers
- Expectations: quick cost and timeline estimate, without lengthy negotiations
4. Agent Workflow Scenario
What to include:
- Step by step: what happens
Example:
Scenario:
1. Customer messages the bot on Telegram (e.g., "Hello, I want to order a website")
2. Agent greets and asks the first question: "What's your task? (website, advertising, SMM, design, other)"
3. Customer answers (e.g., "website")
4. Agent asks the second question: "What budget are you planning? (up to 50k, 50–200k, 200k and above)"
5. Customer answers (e.g., "200k and above")
6. Agent asks the third question: "When do you need it? (urgent — within 2 weeks, within a month, planning ahead)"
7. Customer answers (e.g., "urgent")
8. Agent evaluates the lead: "Lead rating: Hot"
9. Agent records data in Google Sheets (name, contact, task, budget, timeline, rating)
10. Agent sends a notification to the manager on Telegram: "New hot lead! [data]"
11. Agent tells the customer: "Great! I'm passing your request to the manager, they'll reach out within an hour."
5. Prompt (agent instructions)
What to include:
- Full prompt (role, task, context, rules, format)
Example:
Prompt:
You are the sales manager's assistant at digital agency "WebPro".
Your task: ask the customer 3 questions, evaluate the lead, and hand off to the manager if the lead is warm or hot.
Questions:
1. What's the task? (website, advertising, SMM, design, other)
2. Is there a budget? (up to 50k, 50–200k, 200k and above)
3. When do you need it? (urgent — within 2 weeks, within a month, planning ahead)
Lead rating:
- Hot: budget 200k+, urgent
- Warm: budget 50–200k, within a month
- Cold: all others
Format:
- Ask questions one at a time (one question per message)
- After all answers, output: "Lead rating: [rating]"
- If the lead is hot or warm, say: "Handing off to the manager, they'll reach out within an hour"
Rules:
- Tone: professional but friendly
- If the customer doesn't want to answer a question, move to the next one
- Don't be pushy
Actions:
- After evaluating the lead, record data in Google Sheets (use the tool)
- If the lead is hot or warm, send a notification to the manager on Telegram
6. Knowledge Base (if needed)
What to include:
- What data is needed
- Data format
Example:
Knowledge base:
This agent doesn't require a knowledge base (the agent asks questions, not answers them).
If FAQ is needed (e.g., "What services do you offer?"), add a base with questions and answers.
7. Integrations and Tools
What to include:
- Which services to connect
- What to configure
Example:
Integrations:
1. Telegram Bot API
- Create a bot via @BotFather
- Get the token
- Connect to Zapier
2. Google Sheets
- Create spreadsheet "WebPro Leads"
- Columns: Date, Name, Contact, Task, Budget, Timeline, Rating
- Connect via Google Sheets integration in Zapier
- Configure data recording
3. Telegram notifications to manager
- Configure webhook or use Telegram plugin for sending messages
- Manager chat ID: [specify ID]
8. Metrics and KPIs
What to include:
- How to measure success
Example:
Metrics:
- Number of leads processed per day
- Share of hot/warm/cold leads
- Time from first message to handoff to manager
- Conversion of hot leads to deals (track via CRM)
Target KPIs:
- Process 50+ leads per week
- 70% of leads qualified automatically (without manager involvement)
- Response time to hot lead: under 1 hour
9. Timeline and Stages
What to include:
- When to do what
Example:
Stages:
1. Prompt development and testing (1 day)
2. Create Telegram bot and configure in Zapier (1 day)
3. Configure integrations (Google Sheets, notifications) (1 day)
4. Testing with test queries (1 day)
5. Launch in test mode (3 days)
6. Collect feedback and make adjustments (2 days)
7. Full launch (day 10)
10. Risks and Limitations
What to include:
- What could go wrong
- What the agent does NOT do
Example:
Risks:
- Customer may not answer questions → agent will pass the lead as "cold"
- Agent may misunderstand the answer (e.g., "budget is flexible") → needs testing and prompt refinement
- Google Sheets may be unavailable → configure backup storage or error notification
Limitations:
- Agent does NOT negotiate price
- Agent does NOT answer questions about portfolio (qualification only)
- Agent does NOT handle complex requests (e.g., "need website + advertising + SMM") — hands off to manager