Search2oSearch2o
Docs / Agent definition

Variables and namespaces

There are three kinds of variables, with three scopes: local, agent and conversation. The runtime also provides a few read-only names.

localone function, one runcity, rows, loop variablesany Python valueagent.xone agent, whole conversationagent.hasInit, agent.cacheJSON-serializable, savedconv.xall agents, whole conversationconv.order, conv.customerJSON-serializable, savedread-only: sys · command · result · excset with var; seed agent. and conv. values before reading them
Three scopes for variables

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 local variables. 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 that set the variable can read and write the variable; 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 the variable. Conversation variables are how agents hand work to each other: one agent leaves a result in conv.order, and the next agent picks the result up.

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. Seed the variable before use, for example "{ getattr(agent, 'count', 0) + 1 }".

Setting variables

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

Read-only namespaces

sys

The runtime provides sys. The following names are always present:

  • sys.inputs — the inputs the agent was started with, as a dict. For a search the dict is { "query": ... }. An invoke command passes any inputs it likes.
  • sys.query — the user's query, the same as sys.inputs['query'].
  • sys.secret[name] — reads a secret from the agent server's environment; see Security.

The following names are present only when an administrator enables them in the system variables configuration:

  • sys.userEmail — the email address of the user running the agent.
  • sys.userSession — a hash of the user's session, for keying per-session data.
  • sys.serverIp — the agent server's address as seen by the cloud, for logging.

command

command holds the values of the current command's fields that have been evaluated so far. A field may refer to a field written earlier in the same command as command.field.

Other names

  • inputs and query — the same as sys.inputs and sys.query.
  • result — the result of the most recent command that produces one.
  • exc — inside an onError block, the exception being handled.

sys, command, result, exc, env, agent, conv and onError are reserved and cannot be assigned.