Build

Agents

An agent is a saved set of decisions about a voice conversation: what it is for, how it opens, how it sounds and what it is able to do. Every call runs on one agent.

What an agent is made of

systemInstructionInstructions

Who the agent is, what it helps with and how it should speak. This is the part you will spend the most time on.

greetingModeGreeting

How the call opens: the model writes a line from greetingInstruction (generate), a fixed greetingText is spoken (static), or the agent waits for the caller (none).

voiceVoice

The voice engine, the language, the voice itself, and its speed, volume and emotion.

llmModel

The model that writes replies, its temperature and how long a reply may be.

variablesVariables

Named blanks in the instructions that each call fills in, such as the caller’s name.

toolIdsTools

Your HTTP endpoints the agent may call while it talks.

documentIdsKnowledge

The documents it answers from: price lists, policies, FAQs.

systemToolsBuilt-in tools

Things the agent may do on its own: end the call, switch language.

webhookUrlWebhook

A URL that is sent every event of this agent’s calls.

embedCall button

Whether its publishable key may start calls from a web page, and the limits on that.

Create an agent

Only name and systemInstruction are required. Whatever you leave out starts from the platform’s defaults, which you can read from Get the catalog.

curl -X POST "https://goblins-call-api.onrender.com/v1/agents" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk",
  "systemInstruction": "You answer calls for Sunrise Dental. Help callers book, move or cancel an appointment. Keep every reply to one or two short sentences.",
  "greetingInstruction": "Greet {{customer_name}} warmly in one short sentence.",
  "voice": {
    "language": "en"
  },
  "variables": {
    "customer_name": {
      "defaultValue": "there"
    }
  },
  "systemTools": {
    "endCall": true
  }
}'

The response carries the agent’s id. That is what you send as agentId to start a call.

Change an agent

Update an agent changes the fields you send and leaves the rest. voice, llm and stt are merged field by field, so you can change the speed without restating the voice. variables is replaced as a whole.

curl -X PATCH "https://goblins-call-api.onrender.com/v1/agents/ua_3f9a1c2b" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "voice": {
    "speed": 1.1
  }
}'

Writing instructions

The agent is heard, not read, and that changes what good instructions look like.

  • Ask for short replies. One or two sentences per turn keeps a conversation moving. llm.maxTokens also caps how long a reply can run.
  • Say what to do when it does not know. An agent that may say “I’ll have someone call you back” is more useful than one that guesses.
  • Name the tools. Mention a tool as @check_order_status where the instructions say when to use it. See Tools.
  • Leave blanks for what changes per caller. Write {{customer_name}} and fill it in on each call. See Variables.

What is added to your instructions

When a call starts, your instructions are combined with a few things you do not have to write yourself: how to run the tools you have switched on, how to use the built-in tools, and writing rules for the agent’s voice, such as how to write numbers so they are read out properly. To leave the writing rules out, save the agent with voice.speechRules set to false.

What an agent costs

Each agent has a costPerMinute, set by the platform, which is what a minute of its calls takes from your balance. See Pricing and billing.