> Build an AI agent that answers candidates about open positions, application status and interviews on WhatsApp, while screening decisions stay with people. # AI agent for recruiting and HR An AI agent for recruiting answers candidates on WhatsApp and your careers page: which positions are open, how the process works, where their application stands and when they can interview, booked straight into your applicant tracking system. It never promises a job, never discusses salary beyond what the posting says, and never judges a candidate, because screening decisions stay with your recruiters. With Vatio you describe that agent in one `vatio.yml` file, and it runs on your own WhatsApp number and in a widget on your careers site. This guide builds one for a recruitment agency. The same shape works for an in-house talent team. ## What the agent handles Candidates ask the same few things, usually at night and usually more than once: - **Open positions.** "Do you have anything in logistics near Leeds?" The agent searches the openings and sends the posting link. - **Application status.** The candidate gives their application ID and email, and the agent tells them the stage and the next step. - **Interview scheduling.** For applications at the interview stage, it offers free slots and books the one the candidate picks. - **The process.** How many stages there are, how long each takes, what to bring, whether they can apply to two roles. - **Everything else goes to a person.** Feedback on a rejection, salary negotiation, interview accommodations, complaints. A typical exchange on WhatsApp: > **Candidate:** hi, I applied for the warehouse supervisor job 2 weeks ago, any news? > > **Agent:** Let me check. What's your application ID? It's in the confirmation email and starts with AP. I'll also need the email you applied with. > > **Candidate:** AP-20931, maria.r@mail.example > > **Agent:** Thanks, María. Your application is in review with the hiring team. If it moves forward, the next step is a 30-minute video interview, and you'll be able to book it here. Behind the last reply was one call to `application_status`, whose backend checked that the ID and the email belong together. It said nothing about her chances, because the rules say it never does. Every tool call is visible in the inbox, next to the reply it produced. ## Before writing anything: five questions for the recruiting team 1. **Who writes in, and about what?** Usually open positions and application status, then interviews. 2. **What must it never say?** Promises, opinions on a candidate's fit, salary beyond the posting, reasons for a rejection. 3. **When does a person take over?** Feedback requests, negotiation, accommodations, complaints, a candidate asking about their data. 4. **Which systems does it read from?** The API of your applicant tracking system: postings, applications and interview calendars. 5. **What do your local rules require?** Automated decisions about candidates, consent, how long CVs are kept. Those answers come from your legal or HR team, not from whoever writes the YAML. The answers become the instructions, the `handoff` conditions, the tools and the knowledge. ## The `vatio.yml` ```yaml workspace: alder-talent agent: name: Alder Talent personality: Warm, respectful and brief. Plain words, no HR jargon. instructions: | You answer candidates for Alder Talent, a recruitment agency: open positions, how the process works, the status of an application and interview scheduling. Open positions: call search_jobs with what the candidate is looking for and where. Share the posting link it returned so they apply there. Application status: ask for the application ID (it is in the confirmation email) and the email they applied with, then call application_status. Give the stage and the next step as it returned them, and nothing else. Interviews: only when application_status says the stage is interview. Call interview_slots, offer at most three, read the chosen one back and call book_interview. Only say an interview is booked when book_interview returned it. Process questions: search knowledge_lookup first. If it does not answer, say so and offer to pass the question to the team. Rules you never break: - Never promise a job, an interview or an outcome, and never guess a candidate's chances. - Never say whether a profile or CV fits a role, rank candidates or reject anyone. Recruiters review every application. - Never discuss salary beyond the range published in the posting. - Never ask about age, family plans, health, religion or other personal matters the posting does not require. tools: [search_jobs, application_status, interview_slots, book_interview, knowledge_lookup] knowledge: [careers] links: privacy: https://alder-talent.example/candidate-privacy handoff: after_turns: 12 when: - the candidate asks why they were not selected or wants feedback - the candidate wants to negotiate salary or conditions - the candidate needs an accommodation for an interview - a complaint about the process or a recruiter - the candidate asks to see, correct or delete their data ``` A few choices worth explaining: - **"Recruiters review every application."** The rule is also the answer. When a candidate asks "am I good enough?", the agent has something true to say instead of an opinion. - **"As it returned them, and nothing else."** An agent that softens "not selected" into "still being considered" has made a promise on your behalf. Stages are words your team chose; the agent repeats them. - **Salary is the posting's range or nothing.** If the posting says "competitive", so does the agent, and the question goes to a recruiter. - **Business hours decide what happens after a handoff.** The recruiting team sets them on the inbox's Business page, not in `vatio.yml`: here Monday to Thursday 9:00–18:00 and Friday 9:00–17:00, London time. Inside hours the agent goes quiet so a recruiter can pick up. Outside them it keeps helping and says the team will reply on the next working day. Vatio does not notify anyone of a handoff yet; the conversation shows as waiting in the inbox. See [business hours](https://vatio.ai/docs/handoff#business-hours). ## Tools: openings, applications and interviews A tool is one HTTP request to your backend, described in YAML. Keep the address and key in secrets: ```bash vatio secrets set ATS_API https://ats.alder-talent.example vatio secrets set ATS_API_KEY sk_live_... ``` `tools/application_status.yml`: ```yaml description: Get the stage and next step of a candidate's application. when_to_use: The candidate asks how their application is going and gave the application ID and email. parameters: type: object properties: application_id: { type: string, description: "Starts with AP, e.g. AP-20931" } email: { type: string, description: "The email the candidate applied with" } required: [application_id, email] access: public request: method: POST base_url: "$env.ATS_API" path: /applications/status requires: [params.application_id, params.email] headers: Authorization: "Bearer $env.ATS_API_KEY" body: application_id: "$params.application_id" email: "$params.email" respond: data: stage: "$.stage" next_step: "$.next_step" ``` `tools/book_interview.yml`: ```yaml description: Book an interview slot for an application at the interview stage. when_to_use: The candidate chose a slot from interview_slots and confirmed it. parameters: type: object properties: application_id: { type: string } email: { type: string } slot_id: { type: string } required: [application_id, email, slot_id] access: public request: method: POST base_url: "$env.ATS_API" path: /interviews requires: [params.application_id, params.email, params.slot_id] headers: Authorization: "Bearer $env.ATS_API_KEY" body: application_id: "$params.application_id" email: "$params.email" slot_id: "$params.slot_id" respond: data: interview: "$.interview" ``` `search_jobs` is a `GET` with a keyword and a location that returns each opening's title, place, schedule, published salary range and posting URL; a URL a tool returns is one the agent may send for the rest of the conversation. `interview_slots` takes the same application ID and email and returns free slots only when the application is at the interview stage. **Your backend checks that the application ID and the email belong together** before it returns or books anything. The model fills a tool's parameters, so that check lives in code, not in the prompt. Answer `404` whether the ID does not exist or the email does not match, so a wrong guess learns nothing. The tools use `POST` so the email travels in the body and stays out of URLs and access logs. And remember that **what a tool returns is what the model can repeat**: if your applicant tracking system keeps recruiter notes or scores next to the stage, the endpoint must leave them out. ## Knowledge: the process, in your words ```bash vatio kb create careers vatio kb write careers process process.md vatio kb write careers interviews interviews.md vatio kb write careers candidate-faq candidate-faq.md ``` A good entry is specific: ```markdown # How our process works ## Stages Received, In review, Interview, Final interview, Offer or Closed. Most applications move from In review within 10 working days. ## Applying to more than one role You can apply to up to three openings at once. Each one is reviewed separately. ## Video interviews 30 minutes with a recruiter. You get the link by email after booking. ``` Vatio does not read your careers site. If the answer lives on a page, put what the agent needs in an entry. Recruiters can edit entries from the inbox when the process changes, and every edit is kept as a version. ## CVs, and why screening stays with people Candidates send their CV as a PDF with a "is there anything for me?". The agent reads PDFs and images up to 8 MB, so it can see what kind of role the person is asking about and search the openings in that area. What it does not do is decide whether they qualify. That line is drawn in the instructions, not left to the model's tact: no fit, no ranking, no rejection, and a true answer ready for "am I good enough?". The CV stays in the conversation, where recruiters see it in the inbox; the agent cannot forward the file to your applicant tracking system, so the posting link is still how someone applies. This is a design choice, not a feature that makes a process compliant. Many jurisdictions regulate automated decisions about job candidates, how their personal data is processed and how long it is kept, and some require telling people they are talking to a machine (the agent says plainly that it is an assistant). Check what your local employment and data protection rules require before going live. ## Try it before any candidate does ```bash vatio push vatio chat "Do you have warehouse jobs near Leeds?" vatio chat "Status of AP-20931, email maria.r@mail.example" vatio chat --new "Status of AP-20931, my email is someone.else@mail.example" vatio chat --new "I have 5 years of experience, do you think I'll get the job?" vatio chat "The posting says competitive salary. What's the real number?" vatio chat show ``` The wrong email must reveal nothing, the chances question must get no opinion, and the salary question must go no further than the posting. Then add your phone as a test number on the inbox's **Test** page, send a CV as a PDF to the shared WhatsApp preview number and ask whether you are good enough. More on the channel in [An AI agent on WhatsApp](/guides/whatsapp-ai-agent). ## Make it better every week Once recruiters use the inbox, they **flag** any reply that was wrong and write what should have happened. `vatio flags` turns those notes into a document your coding agent fixes from, each flag becomes an eval case, and the flag is resolved when live passes it. Evals call your tools for real, so point them at a sandbox applicant tracking system with a test value (`--tests`) before a replay books a real interview. See [Improve your agent](/guides/improve-your-ai-agent). ## Go live ```bash vatio publish ``` Then connect your WhatsApp Business number from **Channels** in the inbox and switch it on, and add the widget to your careers page with one script tag. Interview reminders and job alerts still start in your applicant tracking system, which decides who gets one and when; on WhatsApp your backend can send each one through the [Messages API](https://vatio.ai/docs/api/messages), and the agent answers what candidates write back. ## Frequently asked questions ### Can an AI agent screen job candidates? It can read a CV, but this guide does not let it screen, and we recommend you do not either. The instructions forbid it from judging fit, ranking or rejecting anyone, and screening decisions stay with your recruiters. Many places regulate automated decisions about candidates, so check your local employment and data protection rules. ### How can candidates check their application status on WhatsApp? The candidate gives the application ID from their confirmation email and the email they applied with. A tool sends both to your applicant tracking system, and your backend only returns the stage when the two belong together. ### Can the agent schedule interviews? Yes. One tool reads free interview slots from your applicant tracking system or calendar API and another books the one the candidate picks, only for applications at the interview stage. Your system stays the one that confirms the booking. ### Will the agent talk about salary? Only the range published in the posting, if there is one. Anything beyond that, including negotiation, is listed under handoff so a recruiter takes it. ### Does the agent send interview reminders or job alerts? Yes, when your system asks for them. Your backend, which knows the interview, calls Vatio's Messages API and the conversation opens on WhatsApp: your own text, a brief the agent writes from, or an approved template once 24 hours have passed since the candidate last wrote, and the agent handles the reply knowing why it wrote. Job alerts to a list work the same way, one request per candidate; Vatio has no campaign dashboard, so your applicant tracking system still decides who hears about which job, and when.