AI Lead-Gen Agent User Guide
1. Getting Started
1.1 Product Overview
HeyCivis (AI Lead-Gen Agent / AI SDR Agent) is a fully automated lead-generation bot that runs on your own computer. Using your own LinkedIn account, it automatically finds potential customers on LinkedIn, performs background screening, match filtering, connection requests, personalised outreach and continuous follow-up, and guides interested customers to book a meeting — steadily delivering high-quality opportunities to your sales team. Customer data, conversation history and follow-up progress are all stored on your own computer and never uploaded to a server; these data are kept by default even when the app is uninstalled.
1.2 Quick Start
For first use, just complete the following 6 steps; each step is explained in detail in its corresponding section.
System Requirements
- Windows (64-bit);
- Network access to LinkedIn, the AI model service and the HeyCivis account service; if email lookup is enabled, access to the email lookup service is also required.
Step 1: Download & Install
The installer is HeyCivis-Setup.zip, available from the HeyCivis website (the download link is provided after purchase or trial application).
- Double-click
HeyCivis-Setup.exe; - Follow the prompts to complete the installation. It installs to the current user’s program directory by default and requires no administrator privileges;
- After installation, desktop and Start menu shortcuts are created automatically, and the built-in Agent Skill is deployed with a one-time installation self-check.
On first launch, the client prepares the browser components it needs as required.
Step 2: Register and Sign In to Your HeyCivis Account
Register with an email and password, or sign in with an existing account. Both require accepting the terms of service and privacy policy and completing the human verification; registration signs you in automatically.
The account needs available balance or any active subscription before the bot can start. See “2.1 Account & AI Model”.
Step 3: Link Your LinkedIn Account
In “2.2 LinkedIn Account & Daily Quota”, enter your LinkedIn email and password.
First switch the LinkedIn interface language to English, otherwise the bot may fail to recognise pages and operate correctly.
Step 4: Configure the AI Model
In “2.1 Account & AI Model”, enter the provider, model name and API key; OpenAI-compatible services also require the API base. No API key is needed when using the built-in HeyCivis model.
Step 5: Create Your First Project
In “3.1 Creating a Project”, create a project and fill in:
- Business intro: describe the product, target customers, the problems solved and core value;
- Prospecting goal: describe who to find, how to screen, what to talk about and how to move forward.
Both texts drive search-keyword generation, AI customer screening and follow-up messaging. See “3 Projects” for how to write them.
Step 6: Start the Bot
On the Tasks page, click “Start”, and the bot automatically begins searching and screening customers during the working window. Execution is shown in “4 Operations”. For details on starting and stopping, see “1.3 Starting, Stopping & Window Behaviour”.
1.3 Starting, Stopping & Window Behaviour
Starting
If an execution account, AI model or project is missing, the Tasks page shows “Initialising”; “Start” appears only after the configuration is complete.
After confirming that the LinkedIn account, working time zone and active window at the top of the page are correct, click “Start”. The page status refreshes automatically as the bot runs; to see the latest status immediately, use “Sync” in the tray menu to refresh manually.
Stopping
To pause, click “Stop” on the Tasks page.
Closing the Window Is Not Quitting
- Clicking the close button in the top-right corner hides the app to the system tray — the bot keeps running;
- To fully quit the app, use “Quit” in the tray menu.
Where to See Results After Starting
- Tasks page: today’s used connection and follow-up quotas, the three task types and their status;
- Projects page: customer progress, conversation history and execution log.
See “4 Operations” for details.
2. Configuration
2.1 Account & AI Model
On first launch, register or sign in to your HeyCivis account. The “email” field is the account name; registration and sign-in must use the same value.
Once signed in, “Settings > Account” shows the account status:
| Item | What it shows |
|---|---|
| The account name currently signed in | |
| Password | Click “Change” to change the sign-in password |
| Balance | Click “Top up” to add balance |
| Subscription | Shows the current subscription status; click “Buy” when there is no subscription |
| Authorisation | Shows whether the bot can be used right now |
The bot can only start when the account has available balance or any active subscription. Without usage rights you can still view and edit the configuration, but you cannot start the bot or run business operations through the Skill.
If the status cannot be confirmed temporarily, check the network and click the retry icon next to the relevant field. To switch accounts, click “Sign out”.
AI Model
The model is used to generate search keywords, screen customers and generate follow-up content. Fill in the AI model area of “Settings > Account”:
| Field | What to enter |
|---|---|
| Provider | HeyCivis, OpenAI, Anthropic, Google, DeepSeek or OpenAI-compatible |
| Model | Enter the model name; with HeyCivis you can enter heycivis or heycivis-pro |
| API key | Enter the API Key for the model service; not required with the built-in HeyCivis model |
| API base | Required for OpenAI-compatible services; enter the API endpoint |
It takes effect after saving.
2.2 LinkedIn Account & Daily Quota
LinkedIn Account
In “Settings > LinkedIn”, enter your LinkedIn email and password and click “Save”. To switch accounts, click “Clear” first, then enter the new one.
Before use, switch the LinkedIn interface language to English, otherwise the bot may fail to recognise pages and operate correctly.
Daily Quota
The quota is the maximum number of tasks assigned per day. It affects only two task types — connection requests and follow-ups. In “Settings > LinkedIn”, set the daily connection quota and the daily follow-up quota separately; the defaults are 20 and 25.
The quota is the execution ceiling for the day, not a target to be reached; setting it to 0 means no such action is executed that day. The higher your account reputation, the higher you can set it. Once the ceiling is reached, the remaining tasks are skipped for the day and work resumes after the quota resets. A stable quota helps reduce the chance of triggering LinkedIn’s risk controls, but it cannot guarantee the account will never be restricted.
2.3 Work
In “Settings > Work”, choose the working time zone; it should match the environment the LinkedIn account is normally used in.
The working time zone determines the bot’s working window, the time displayed in the app and the automated browser’s time zone at the same time.
Changes take effect after restarting the bot.
The “working rhythm” panel on the same page shows the bot’s active window, pauses between actions, work and rest rhythm, connection re-check interval and match threshold. The bot follows a human-like rhythm and needs no configuration here.
2.4 Email Lookup
In “Settings > Email”, enter your BetterContact API key and save to enable work-email lookup.
Without a key, this feature stays off: the bot does not look up work emails; once a customer passes screening, the connection request is sent directly — a connection request can be sent without a work email.
Once enabled, after a customer passes screening the bot first looks up their work email: it sends the connection request only when an email is found; customers with no email found are marked “No email”.
Saving with an empty key turns email lookup off.
2.5 Network
In “Settings > Network”, check whether LinkedIn is reachable from the current environment. Click “Check now” and the page shows the check status and the time of the last check.
Run this check first when the bot cannot sign in or has made no progress for a long time; if the check fails, review your network or proxy settings and run it again.
2.6 Skill
The Skill lets you run lead-gen operations on demand through agents that support Agent Skills (such as WorkBuddy, Codex and Claude): prospecting for customers, sending connection requests, checking connection results, syncing conversations, generating follow-up drafts, sending messages, and viewing and managing projects and customers.
The automatic bot is best for continuous daily lead generation; the Skill suits operations where you pick the list and confirm the outbound actions. Both share the same projects, customers, quotas and business state.
“Settings > Skill” manages two installation targets separately, WorkBuddy and generic Agent Skills: click “Install” when not installed, “Update” when a new version is available or the client path has changed, and “Uninstall” when no longer needed. Each card shows the installed version and the latest version bundled with the client; the two installations are independent.
After a successful install or update, enter /heycivis-ai-sdr-agent please run the installation self-check in a new conversation in the agent platform. Before running business operations through the Skill, stop the bot on the Tasks page and keep the client running; if the client is not running, the Skill returns CLIENT_NOT_RUNNING — start the client and retry.
2.7 Blacklist
Blacklisted customers never re-enter the lead-gen flow.
In “Settings > Blacklist”, view the blacklisted customers; after removing one, that customer may re-enter the lead-gen flow.
2.8 Reset
“Settings > Reset” provides two operations:
Initial Setup
Walks through the execution account, the AI model and the first project in order, and asks you to accept the terms of use before it finishes, without overwriting existing data.
Clear Data
Deletes all customers, customer progress and execution records and resets the search keywords, while keeping projects and account configuration.
Stop the bot before running “Clear Data”.
2.9 About
“Settings > About” shows the app name, current version, company and contact email. Click “Check” next to the version number; when a newer version exists the button turns into “Update”, and clicking it takes you to the download page.
3. Projects
3.1 Creating a Project
A project decides what the bot promotes, who it looks for and how it communicates. Different products, markets or target customers should be created as separate projects.
Click “+” in the top-right corner of the Projects page, fill in the following and save:
| Field | Requirement |
|---|---|
| Project name | Use an easily recognisable product, market or region name |
| Execution account | Select the current LinkedIn account; cannot be changed after creation |
| Business intro | Describe the product, target customers, the problems solved and core value |
| Prospecting goal | Describe who to find, how to screen, what to talk about and how to move forward |
| Booking link | Enter the meeting-booking or product-consultation address |
We recommend writing the business intro and prospecting goal in English, so they stay consistent with English LinkedIn profiles and search keywords.
3.2 Business Intro
The business intro describes the product, target customers, the problems solved and core value; the bot uses it to generate search keywords and judge whether customers match. Avoid writing only a company description or a marketing slogan.
Example:
HeyCivis (AI Lead-Gen Agent) is a fully automated lead-generation bot that runs on a local computer. Using the company’s own LinkedIn account, it automatically finds potential customers on LinkedIn, performs background screening, match judgment, personalised outreach and continuous follow-up, and invites interested customers to book a meeting or hands them over to sales. The product supports business communication in 50+ languages, helping companies develop global customers steadily and continuously while reducing reliance on trade shows, referrals and manually maintained customer lists.
3.3 Prospecting Goal
The prospecting goal describes who to find, how to screen, what to talk about and how to move forward, and should include the following six items:
| # | Item | Requirement |
|---|---|---|
| 1 | Target customer | Role, industry, region, company size and typical characteristics |
| 2 | Screening criteria | Make it clear which customers qualify and which do not |
| 3 | Opening topic | The problem or business scenario to discuss first in initial communication |
| 4 | Interest signals | Which expressions from the customer mean it is safe to move forward |
| 5 | Next action | The concrete action once interest appears, e.g. invite a product consultation and guide them to fill in the booking link |
| 6 | Do-not-contact | People, industries, roles or scenarios you do not want to reach out to |
Example:
Target customer: within companies that sell B2B products or services globally, the founders, heads of sales, heads of marketing and heads of international business responsible for sales growth and business development.
Screening criteria: companies that sell products or services to business customers, have clear target industries, countries or purchasing roles, and want to keep developing new customers; companies mainly selling B2C with no B2B need, as well as job seekers, recruiters, students and unrelated roles, do not qualify.
Opening topic: how the company currently finds new customers, and the problems it faces in lead generation, background screening, multilingual outreach and follow-up.
Interest signals: the customer mentions relying on trade shows or referrals, manual search being inefficient, lacking multilingual sales capability, follow-up being inconsistent, or wanting more high-quality sales leads.
Next action: once the customer confirms they have a lead-gen need and are open to learning about the solution, invite them to a 30-minute product consultation and guide them to pick a time through the booking link.
Do-not-contact: job seekers, recruiters, students, vendors of similar software, and roles unrelated to sales or business development.
The booking address is filled in separately in the project’s “Booking link” field.
3.4 Seed Customers
Seed customers are customers already manually confirmed to fit the project; the bot does not need to search and screen them again — for example, an existing target list or contacts designated by sales.
In the project details, click “Seed customers” and paste full LinkedIn profile URLs, one per line. Duplicate customers and invalid links are skipped.
https://www.linkedin.com/in/example-one/
https://www.linkedin.com/in/example-two/Seed customers skip search, AI screening and email lookup and go straight to “Screened”; after that, their profiles are still read and they run through the normal flow of connection requests, request checks and follow-up. Only import customers already manually confirmed as a fit.
3.5 Editing, Exporting & Deleting
Editing
“Project config” lets you edit the project name, business intro, prospecting goal and booking link. Edits only affect customers processed afterwards.
Exporting
“Export” exports customer data and progress as an Excel file.
Deleting
Deleting a project also deletes its customers, execution records and search keywords. Stop the bot before deleting.
4. Operations
4.1 Customer Progress & Conversations
“Customer progress” is for viewing and filtering all customers in a project. The main stages:
| Stage | Meaning |
|---|---|
| Screened | Fits the project requirements, waiting to be processed further |
| To connect | Waiting for a connection request to be sent |
| Pending approval | Connection request sent |
| Connected | Now a LinkedIn contact; can be followed up |
| Closed | This round of follow-up has ended |
| Failed | Customer does not match or the action cannot continue |
| No email | No usable work email found |
Click a customer’s name to open their LinkedIn profile; click “Details” to view the email, screening reason, customer outcome and conversation history. Customer outcomes include: booked a meeting, explicitly declined, not a match, no budget, already has a solution, bad timing, no response.
When there are many customers, “Load more” at the bottom of the list continues loading the next batch, while the total shows “N items in total”.
4.2 Execution Log & Search Keywords
“Execution log” shows the connection and follow-up actions that have taken place.
“Search keywords” shows the keywords the bot uses and their usage status; you can also add or delete them manually.
4.3 Today’s Quota & Tasks
“Today’s quota” shows the connection and follow-up quotas already used today; once the ceiling is reached, the corresponding actions are no longer executed.
“Today’s tasks” shows the three task types — connection requests, checking connection requests and following up customers — and their status; click “View all” to filter by project, status and type.
After stopping the bot, you can clear planned tasks that have not been executed; completed tasks are not deleted.
5. Using the Skill
The Skill lets you operate the lead-gen business on demand through agents that support Agent Skills (such as WorkBuddy, Codex and Claude). Unlike the automatic bot, which runs continuously, the Skill suits viewing results, handling specific customers, adjusting drafts and completing operations that are only sent after your confirmation; both share the same projects, customers, quotas and business state. See “2.6 Skill” for installation and configuration.
5.1 Before You Start
- The client is installed, you are signed in to your HeyCivis account, and the model and LinkedIn account are configured, with available balance or an active subscription;
- The Skill is installed in the agent platform and the installation self-check has passed (see “2.6 Skill”);
- Before running business operations through the Skill, stop the bot and keep the client running.
The business intro and prospecting goal saved in the project determine the actual search, screening and communication. A new industry, region, role or screening condition raised on the fly is not automatically written into the project; you need to either keep the current goal, edit the project, or create a new project first.
5.2 Common Prompts
| Goal | You can say |
|---|---|
| View projects | List all my projects |
| View project customers | Show me the current customers in the “Manufacturing lead-gen” project |
| Prospect and prepare connections | Prospect a batch of customers in the “Manufacturing lead-gen” project and prepare connection requests |
| Check connection results | Check the connection results for this project |
| Follow up a specific customer | Write a follow-up message for hans-sales, but do not send it yet |
| Edit a project | Edit the opening topic of “Manufacturing lead-gen”; keep everything else unchanged |
| Edit a customer record | Mark the 3rd customer in the current list as failed — not a match, because the company only sells domestically |
The same conversation reuses the current project. When the project name is unique, the task continues directly; a project is only requested for selection when names are duplicated or unspecified. Customers can be selected by name or by the current list number; old numbers become invalid after the list is refreshed.
Small results are shown directly in the conversation; long lists, multi-customer message drafts and batch results are generated into a dated local HTML report and opened automatically. To keep processing customers in the report, you can use the current report numbers directly; when the report cannot open automatically, the generated local file location is provided.
5.3 Confirmation Rules
| Operation | Behaviour |
|---|---|
| Search, screen, check connections, sync conversations, generate drafts | Executed directly |
| Send connection requests | Shows the final connection list and waits for confirmation |
| Send messages or end follow-up | Shows the final draft, suggestion and customer outcome, then waits for confirmation |
| Change a customer stage or outcome | Shows the final change and waits for confirmation |
When the conversation contains only one pending action just shown, you can simply say “go ahead with this”, “confirm” or any other clear agreement. After editing a list or draft, refreshing the list, switching projects or starting another task, the old version can no longer be confirmed.
When the outbound result is unclear, the Skill stops further outbound actions and does not retry automatically; check the actual result on LinkedIn first, then continue.
6. How It Works
6.1 The End-to-End Flow
After completing account, LinkedIn account, quota and AI model setup and creating a project, start the bot on the Tasks page. During the working window the bot automatically generates and assigns three task types — connection requests, checking requests and follow-ups — without manual per-customer creation; connection requests and follow-ups consume the daily quota, while checking requests are not quota-limited. Customers that pass screening get a connection request; once accepted they move to follow-up, and clear interest leads to an invite to fill in the booking link. Execution is shown on the Projects page (customer progress, conversations and execution records) and the Tasks page (today’s quota and tasks).
7. FAQ
7.1 Run Log
The “run log” shows what the bot is currently executing and any error messages. When something unusual happens, follow the log tips:
| What you see | What to do |
|---|---|
| Account needs to sign in again | Return to the sign-in page and sign in again |
| No usage rights | Top up balance or buy a subscription in “Settings > Account” |
| Account status cannot be confirmed | Check the network and click the retry icon next to the relevant field |
| Model API error | Check the model name, API key and API base |
| LinkedIn unreachable | Run the check in “Settings > Network” and review the network or proxy settings |
| LinkedIn not logged in or security check triggered | Complete the login or verification in the automatically opened browser, then restart |
| LinkedIn page is not in English | Switch to English and restart |
7.2 Common Questions
Is the bot still running after I close the window?
Yes. Closing the window only hides the app to the system tray; the bot keeps running. To fully quit, use “Quit” in the tray menu. See “1.3 Starting, Stopping & Window Behaviour”.
Where is my customer data stored?
Customer data, conversation history and follow-up progress are stored in the local user data directory on your machine and never uploaded to a server. See “1.1 Product Overview”.
What if today’s quota is used up?
The remaining tasks are skipped automatically and resume once the quota resets the next day. See “2.2 LinkedIn Account & Daily Quota”.