Build AI agents

Design your agent 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_typebudgetlocationtimelinequalified

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_idissue_typeresolutionticket_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_nameappointment_dateappointment_timetransferred

Review the draft

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

Accuracy

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

Conversation order

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

Safety

Make prohibited behavior and escalation conditions specific and testable.

Call behavior

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

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.