> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Configure AI interview agents for conducting candidate assessments

## Overview

Agents (also called Interview Templates) are AI-powered interviewers that conduct conversations with candidates. Each agent can be customized with specific questions, voice characteristics, instructions and focus.

## Resource Structure

```jsonc theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Technical Screening Agent",
  "instructions": "Evaluates technical skills for software engineering roles",
  "voiceId": "ALEX",
  "type": "ONLINE",
  "focus": "SCREENING",
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000", // Required if type is PHONE
  "backgroundSound": "OFFICE", // "OFFICE" or "OFF" — applies to all agent types
  "questions": [
    "Tell me about your experience with React and modern frontend development",
    "Explain how you would design a scalable microservices architecture",
    "Describe a challenging technical problem you solved recently",
  ],
  "duration": 30, // in minutes (max 180)
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
}
```

## Creating Agents

```javascript theme={null}
const agent = await fetch("https://api.instaview.sk/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Senior Frontend Developer",
    voiceId: "ALEX",
    type: "ONLINE",
    focus: "SCREENING",
    questions: [
      "Can you describe your experience with React?",
      "How do you optimize for performance?",
    ],
    duration: 30,
  }),
});
```

<Info>
  **Best Practice**: For production integrations, always implement request timeouts.

  ```javascript theme={null}
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), 10000); // 10s timeout

  try {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
      signal: controller.signal,
    });
  } finally {
    clearTimeout(timeoutId);
  }

  ```
</Info>

## Voice Options

| Voice      | Gender | Description                                    |
| ---------- | ------ | ---------------------------------------------- |
| `ALEX`     | Male   | Clear, neutral, business-appropriate (English) |
| `PETER`    | Male   | Professional, executive tone (English)         |
| `MIRIAM`   | Female | Professional, clear (English)                  |
| `SUE`      | Female | Warm, approachable tone (localized as Zuzka)   |
| `VIERA`    | Female | Clear, articulate (Slovak/Czech optimized)     |
| `CASANDRA` | Female | Professional, clear                            |
| `SILVIA`   | Female | Clear, neutral                                 |
| `MICHAEL`  | Male   | Professional (localized as Michal)             |
| `LUKE`     | Male   | Young, energetic (localized as Lukáš)          |
| `EMMA`     | Female | Warm, friendly (localized as Ema)              |
| `SARAH`    | Female | Professional, clear (localized as Sára)        |
| `EVA`      | Female | Clear, articulate                              |

<Info>
  **Duration**: The `duration` field is specified in minutes. The maximum
  allowed duration is 180 minutes (3 hours).
</Info>

## Background Sound

`backgroundSound` controls the ambient noise played to candidates during calls. It can be set on create or updated at any time via `PATCH /agents/{id}`.

| Value    | Description                           |
| -------- | ------------------------------------- |
| `OFFICE` | Subtle office ambient noise (default) |
| `OFF`    | Complete silence                      |

## Agent Focus Options

The `focus` field determines the agent's specialization and interview style:

<Tabs>
  <Tab title="SCREENING">
    Initial candidate screening - Basic qualifications - Availability - Salary
    expectations
  </Tab>

  <Tab title="OUTREACH">
    Proactive candidate engagement - Role introduction - Initial interest check

    * Company presentation
  </Tab>

  <Tab title="GENERIC">
    General purpose interview - Flexible questioning - adaptable to various
    contexts
  </Tab>

  <Tab title="LANGUAGE_TEST">
    Language proficiency assessment - Vocabulary and grammar - Fluency
    verification - Comprehension check
  </Tab>
</Tabs>

## Best Practices

<CardGroup cols={2}>
  <Card title="Clear Questions" icon="question">
    Write specific, open-ended questions
  </Card>

  <Card title="Appropriate Duration" icon="clock">
    15-30 minutes for most interviews
  </Card>

  <Card title="Test First" icon="flask">
    Test agents before using in production
  </Card>

  <Card title="Iterate" icon="rotate">
    Refine based on interview quality
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Interviews" icon="microphone" href="/guides/resources/interviews">
    Use agents to conduct interviews
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    View complete Agents API reference
  </Card>
</CardGroup>