An agent is a persistent search query; it can also be thought of as a more powerful version of the Find view. The maximum scope of a query is every note (and agent, etc.) in the current TBX document. This is true even if more than one TBX is open in Tinderbox. The query arguments used then restrict the scope of matches within the document. Tinderbox has no mechanism for searching across multiple TBX documents.
An agent is a special note: it can have text, links, attributes, etc. as per a normal note but its children can only ever be aliases. These aliases are those of anything meeting the criteria of a query stored in the special $AgentQuery attribute. Thus an agent normally acts as a container for aliases. Agent queries can match notes, (including containers), separator notes, aliases, other agents but not map adornments. Adornments are the one exception to an agent's ability to query any object in the document.
As well as gathering aliases, an Agent can act on the aliased notes via the code stored in its $AgentAction attribute. As the query is run continuously, agents are also dynamic in their filtering. As notes alter they may change their match to the query and be added to or removed from the agent's child aliases. Whilst the agent's action code may cause a matched note's original to move, an agent cannot be made to delete notes entirely. The latter is a deliberate safeguard against unintentional data loss.
Agents may have regularity of their update cycle varied, including the ability to turn an agent off entirely. In the latter case, this means that when turned off the agent retains whatever children (aliases) it had at the last update cycle before it was turned off. The agent's action is not run when an agent is switched off.
Agents may not be turned into notes, nor notes into agents - both must initially be created as the type of object desired. Agents may not have children other than aliases created by the agent query. An exception, from v5.8.0, is that adornments may be added to agent maps.
An agent may be a separator. For an agent $Separator can't be set via the Create/Rename dialog - Info view must be used. As a separator, an agent is not visible in Map view but is visible in all other major views (Chart, etc.).
Meanwhile, an agent can have note text, key attributes and other note features although an agent may be used simply as an filter to gather - and act upon - aliases.
As an agent's output is primarily the effect of it's action on aliases, it does not matter where in a document the agent is placed. This is something new users often misunderstand. The choice of whether an agent is better placed amongst the 'content' of the document or hidden away in a separate branch of the outline will depend on the agent's role in the document. Viewing the source of this TBX, it will be seen some agents are within the main content - e.g. those re-stating the attribute listings via data type, etc., and others which are hidden away in the /UTILS branch of the outline. Indeed, when structuring a new TBX, it is often useful to place all 'content' - the data being worked on - as descendant from a single root level container, making it easy to hide away 'back of house' things like export templates, prototypes, etc.
On export, agent aliases are exported as discrete files, albeit sharing their original's text and most attributes (except intrinsic ones).
Like a note, an Agent can also have a $Rule attribute allowing it to apply changes to itself as well as its contained aliases.
Actions and rules may use simple arithmetic and logical expressions.
Originally, Tinderbox agents never searched aliases.Tinderbox 5 does search for aliases, but initially it was not always been clear whether the agent gathered an alias of the original note or an alias of the alias that satisfies the query. So, from v5.1.0, a note satisfies a query if:
- the note itself satisfies the query
or
- any alias of the note satisfies the query
Regardless of whether the note or one of its aliases satisfies the query, the agent makes a new alias of the original note.