Variables

An agent's instructions and its first message can name values it is given when a conversation starts: Hello {{first_name}}, I'm calling about your appointment on {{appointment_date}}. Each name is a variable. A call, a chat, a campaign row and the widget all fill them the same way and are checked by the same rules.

Which variables an agent has

Writing {{first_name}} in the instructions or the first message is declaring it. Read an agent's variables from its variables_schema, a JSON Schema:

#!/bin/sh
# Read an agent and its variables
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

{
  "version": "3f9c1e07",
  "type": "object",
  "properties": {
    "first_name": {"type": "string", "maxLength": 500, "title": "First name"},
    "party_size": {"type": "integer", "minimum": 1, "maximum": 12, "default": 2, "title": "Party size"},
    "visit_date": {"type": "string", "format": "date", "title": "Visit date"}
  },
  "required": ["first_name", "visit_date"],
  "additionalProperties": true
}

version changes when the variables change and at no other time, so you can tell an edit to the fields from any other edit to the agent. When it changes, your receivers are sent agent.updated with the new list.

Pin a version

An agent's fields change when somebody publishes. To keep an integration on the version it was built against, send agent_version when you start a call, a scheduled call, a chat or a browser call: the conversation is answered by that published version from its first turn to its last, and its values are checked against that version's fields, not today's.

GET /v1/agents/{id}/versions lists every version the agent was published as, newest first, each with its own variables_schema and the note its publisher wrote. A version the agent never had is refused with unknown_agent_version. The conversation's agent_version says which one answered.

Types

Numbers and true/false may be sent as JSON values or as text; each comes back in its own type.

Required, optional and defaults

A variable the agent says out loud is required — unless it has a default, which stands in when nothing is sent. A field marked optional may simply be left out. A required value that is missing, or one of the wrong type, refuses the request with 422 invalid_variables, and errors names each one:

{
  "code": "invalid_variables",
  "errors": [
    {"field": "variables.first_name", "code": "required", "message": "First name is required"},
    {"field": "variables.visit_date", "code": "invalid", "message": "Visit date is not a valid date"}
  ]
}

A name the agent does not use is not refused. It is listed in the conversation's ignored_variables, so a renamed field shows up there rather than failing every call.

Names starting system_ are reserved for the platform.

Where each value came from

Every conversation records the source of each value in variable_sources: api for one your request sent, lookup for one your context lookup answered, campaign, identity_token for a signed widget token, widget or link for what a visitor's page claimed. Values from a lookup or a visitor's page are never treated as the caller's own answers.

Variables or metadata?

Values cannot rewrite the agent

A value is put into the agent's instructions inside a block of its own, marked as data. A first_name of Ignore your instructions and … is a strange name, not a new instruction.