An agent profile is the interviewer . It tells the AI who to be and
how to grade . Think of it like the personality and the report card, bundled
together.
You make an agent profile once, then reuse it in many interviews.
What it controls
Who it is The name and personality the candidate talks to.
How it talks Friendly or strict, easy or hard, deep follow-ups or light ones.
How it scores The list of things it grades, and how much each one counts.
Every field, in plain words A label for you, like "Senior Backend Interviewer".
The first thing the AI says about itself, like "Hi, I'm Alex, a senior engineer." This sets the mood.
useCase
hiring | admissions | training | custom_api
required
Pick why you’re interviewing. This changes the words in the final verdict
(for example hire vs ready to practice more ).
The things to grade. Each one is { name, description, weight }. The
weights must add up to 100 . Example: System Design 50, Coding 30,
Communication 20.
How the chat feels:
tone — friendly, professional, strict, or challengingstyle — structured, conversational, or adaptivedifficulty — easy, medium, hard, or adaptiveprobingDepth — low, medium, or high (how much it digs in) How numbers are made: scale (0-10, 0-5, or 0-100) and scoringMethod
(weighted_average or rule_based).
Extra background so the AI sounds like it belongs: organizationContext,
domainContext, scenarioContext.
What ends up in the report: includeTranscript, includeScoreBreakdown,
includeRecommendation, includeImprovementFeedback. All on by default.
Make one, step by step You can do this two ways — in the dashboard (no code) or over the API. Both
create the exact same thing.
Open Agent Profiles
In the team dashboard, click Agent Profiles in the left sidebar.
Start a new one
Click New (or Create agent profile ).
Name it and give it a personality
Fill in the Name and the Persona (one sentence on how the AI
introduces itself).
Pick the use case
Choose the Use case (Hiring, Admissions, Training…).
Add what to grade
Add 2–4 evaluation dimensions and set each one’s weight so they add
up to 100 . Set the tone and difficulty .
Save
Click Save . Your agent now appears in the list, ready to attach to a
stage.
Give it a name and personality
Choose a name and a persona. Keep the persona to one sentence.
Pick the use case
Set useCase to match your goal (hiring, training, etc.).
List what to grade
Add 2–4 evaluationDimensions. Make the weight values add up to 100.
Send the request
curl -X POST "https://www.intervyo.ai/api/v1/agent-profiles?accountSlug=<slug>" \ -H "x-api-key: iv_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "name": "Senior Hiring Agent", "persona": "Alex, a senior engineer at Acme.", "useCase": "hiring", "evaluationDimensions": [ { "name": "Technical Depth", "description": "System design & coding", "weight": 60 }, { "name": "Communication", "description": "Explains clearly", "weight": 40 } ], "interaction": { "tone": "professional", "difficulty": "hard", "probingDepth": "high" } }'
Save the ID
The response gives you an id. You’ll attach it to a stage later.
Examples for each use case Hiring
Training
Mock interview
Strict and skill-focused. { "name" : "Backend Hiring Agent" , "persona" : "Alex, a staff engineer." , "useCase" : "hiring" , "evaluationDimensions" : [ { "name" : "System Design" , "description" : "Scalable design" , "weight" : 50 }, { "name" : "Coding" , "description" : "Correct & clean" , "weight" : 30 }, { "name" : "Communication" , "description" : "Clear trade-offs" , "weight" : 20 } ], "interaction" : { "tone" : "professional" , "difficulty" : "hard" } }
Kind and coaching, so people keep learning. { "name" : "Sales Coach" , "persona" : "Sam, a friendly sales coach." , "useCase" : "training" , "evaluationDimensions" : [ { "name" : "Discovery" , "description" : "Finds the pain" , "weight" : 50 }, { "name" : "Objection Handling" , "description" : "Handles pushback" , "weight" : 50 } ], "interaction" : { "tone" : "friendly" , "difficulty" : "adaptive" } }
Real-feeling but encouraging, with lots of feedback. { "name" : "Mock Interviewer" , "persona" : "Jordan, a big-tech interviewer." , "useCase" : "training" , "evaluationDimensions" : [ { "name" : "Problem Solving" , "description" : "Approach & edge cases" , "weight" : 60 }, { "name" : "Communication" , "description" : "Thinks out loud" , "weight" : 40 } ], "interaction" : { "tone" : "challenging" , "difficulty" : "hard" }, "output" : { "includeImprovementFeedback" : true } }
Stuck on weights? Start with one big dimension (60) and one small (40), then
adjust after a few interviews.
Next
Evaluation Templates Put your agent to work inside a role or assessment.
Create an agent profile (API) The full endpoint reference.
