Variables

There are three kinds of variables, with three scopes: local, agent and conversation. Two more names, result and exc, are set by the runtime. The read-only namespaces const, sys and command are on their own page.

Local variables

Local variables are set and read without a prefix. A local variable lives in the function that set it and disappears when that function returns. Function arguments and for loop variables are locals. A local variable can hold any Python value.

Agent variables

Agent variables are written agent.name. An agent variable lives for the whole conversation. Every function of the agent can read and write it; other agents cannot. Use agent variables for state that a follow-up query should find again: whether initialization has run, a cached lookup, the user's last choice.

Conversation variables

Conversation variables are written conv.name. A conversation variable lives for the whole conversation, and any agent that runs in the conversation can read and write it. Conversation variables are how agents hand work to each other: one agent leaves a result in conv.order, and the next agent reads it.

Agent and conversation variables are saved with the conversation, so their values must be JSON serializable. Reading a variable that has never been set raises an error. sys.exists(scope, name) answers whether the variable exists first, so a variable can be seeded on first use: "{ (agent.count if sys.exists('agent', 'count') else 0) + 1 }".

Setting variables

The var command sets variables of all three kinds. It can also set one element of an existing list or dict: "totals['q3']": "{ ... }". Once set, a variable can be read in any dynamic string.

Validation refuses an expression that reads a local variable nothing before it can have set, and a prompt that does the same; see Python expressions.

result and exc

The runtime sets two names that an agent reads but cannot assign:

• result: the result of the most recent command that produces one.
• exc: inside an onError block, the exception being handled; see Error handling.

Reserved names

sys, command, result, exc, agent, conv, const and onError are reserved and cannot be assigned, nor used as argument or loop variable names. Python keywords cannot be variable names either.