# Design your agent with AI

> Generate an AI voice agent configuration from plain language, review its conversation flow and guardrails, then create the agent with the HeyRik API.

Source: https://www.heyrik.com/docs/guides/design-with-ai

Turn a plain-language idea into a structured draft, review every decision, and publish only when the behavior is right.

8 minute read Practical examples included

`POST /agents/generate` turns a plain-language use case into a draft configuration. It does not create or save an agent. Treat the result as a useful first version that still needs human review.

**AI accelerates structure—not accountability.**

You remain responsible for factual knowledge, safe behavior, escalation rules, and the final experience.

## Describe the agent’s job

A good description includes the role, audience, desired outcome, tone, and constraints.

Avoid

### Too vague

Create a sales agent.

Recommended

### Useful description

Create a friendly inbound clinic receptionist that answers opening-hour questions, collects the caller’s name and preferred appointment time, and transfers urgent medical questions to a person. It must never give medical advice.

**Generate request**

```
curl -X POST https://server.heyrik.com/api/v1/agents/generate \
  -H "Authorization: Bearer $HEYRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A friendly inbound clinic receptionist that answers opening-hour questions, collects the caller name and preferred appointment time, and transfers urgent medical questions to a person. Never give medical advice.",
    "category": "healthcare"
  }'
```

## Understand the generated output

The draft comes back in the exact shape POST /agents accepts — ordered prompt\_sections (persona, language restrictions, phased flow, guardrails, closing), a greeting, input\_variables declared for every {{placeholder}} it writes (each with a default), and extracted\_variables to capture after the call. Nothing is live yet.

**Example generated draft**

```
{
  "data": {
    "name": "Clinic Receptionist",
    "language": "en-IN",
    "greeting": "Hello, thank you for calling {{company_name}}. How may I help?",
    "config": {
      "personality": "Friendly",
      "languages": ["en-IN"],
      "prompt_sections": [
        {
          "order": 0,
          "title": "Identity & Purpose",
          "content": "You are the receptionist for {{company_name}}. Help with opening hours and appointment requests."
        },
        {
          "order": 1,
          "title": "Language Restrictions",
          "content": "Speak only English. Code-switch for numbers, dates and times."
        },
        {
          "order": 2,
          "title": "Conversational Flow",
          "content": "Understand the request. For appointments, collect name, preferred date, and preferred time — one question at a time."
        },
        {
          "order": 3,
          "title": "Guardrails",
          "content": "Never provide medical advice. Transfer urgent or clinical questions to a person."
        }
      ],
      "input_variables": [
        { "name": "company_name", "default": "the clinic", "description": "the clinic/brand — fills {{company_name}}; falls back to the default when not supplied" }
      ],
      "extracted_variables": [
        { "name": "caller_name", "description": "Caller’s full name" },
        { "name": "preferred_time", "description": "Requested appointment time" }
      ]
    }
  }
}
```

## More agent creation examples

Describe the outcome and constraints clearly so the generated draft starts in the right direction.

Sales

### Real-estate lead qualifier

Qualify inbound property leads by property type, budget, location, and timeline. Never invent price or availability. Arrange a senior-agent follow-up for qualified leads.

`property_type``budget``location``timeline``qualified`

Support

### Order support agent

Answer order and return questions from approved policies. Collect the order ID, call the order-status API, and create a support ticket when the request needs manual review.

`order_id``issue_type``resolution``ticket_id`

Reception

### Clinic receptionist

Answer clinic-hour questions and collect appointment preferences. Never provide medical advice. Transfer urgent or clinical questions to a person.

`caller_name``appointment_date``appointment_time``transferred`

## Review the draft

Review in a predictable order so important decisions are not hidden inside the wording.

1

### Accuracy

Remove assumptions. Add approved operating hours, policies, and limits through the knowledge base.

2

### Conversation order

Ensure the questions follow the caller’s mental model and do not request everything in one turn.

3

### Safety

Make prohibited behavior and escalation conditions specific and testable.

4

### Call behavior

Set silence prompts, maximum duration, transfer rules, and end-call phrases.

5

### Inputs & outputs

Check input\_variables — the {{placeholders}} the greeting and prompt use — each have a sensible default so nothing leaks, and that extracted\_variables capture the post-call data your application actually needs.

## Create the reviewed agent

Send the reviewed draft to POST /agents only after it reflects the behavior you want.

**Create**

```
curl -X POST https://server.heyrik.com/api/v1/agents \
  -H "Authorization: Bearer $HEYRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d @reviewed-agent.json
```

**Created agent**

```
{
  "data": {
    "id": "agc_clinic_42",
    "name": "Clinic Receptionist",
    "language": "en-IN",
    "created_at": "2026-07-28T10:20:00.000Z"
  }
}
```

**Next step**

Add the clinic’s approved knowledge, assign a phone number, and run controlled test calls before sending real traffic.