Build

Variables

Variables let one agent serve every caller. You leave named blanks in the agent’s instructions, and each call fills them with what you know about that caller.

Define them on the agent

Write a variable as {{name}} wherever it should appear, and list it under variables with a default:

{
  "systemInstruction": "You are calling {{customer_name}} about order {{order_id}}. Confirm the delivery slot.",
  "greetingInstruction": "Greet {{customer_name}} by name and say you are calling from Sunrise Stores.",
  "variables": {
    "customer_name": { "defaultValue": "there", "description": "The caller's first name" },
    "order_id": { "defaultValue": "your recent order" }
  }
}

Variables are filled in everywhere the agent has text of its own:

• the instructions (systemInstruction)
• the greeting (greetingText and greetingInstruction)
• its tools: the URL, the headers and the body of each request

Fill them in on each call

Send variables when you start the call. Names and values are strings.

curl -X POST "https://goblins-call-api.onrender.com/v1/calls" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agentId": "ua_3f9a1c2b",
  "variables": {
    "customer_name": "Divya",
    "order_id": "A-1042"
  }
}'

A variable you do not send takes its default. One with neither a value nor a default is left as written, braces and all, so give every variable a default that still reads naturally.

Variables that are always there

Tools that run during a call can use two more, which come from the call itself:

These, and the variables the call was started with, always win over anything the model supplies as a tool argument. Your endpoint can look a caller up from {{call_id}} and trust that it is the real one. See Tools.

Where they end up

The variables a call started with are kept on the call as metadata.variables, so they come back when you read the call and in every webhook for it. Sending metadata.variables yourself does the same thing as variables; where a name is in both, the one in metadata is used.