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's arguments then restrict the scope of matches within the overall document scope. 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 upon 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 within the underlying outline (e.g. to a new container), an agent can neither delete notes entirely nor create new. The latter is a deliberate safeguard against unintentional data loss.
Normally, attribute changes made to an alias changes the alias' original note. But, be aware that some attributes are 'intrinsic', meaning the original note may hold a different value for the attribute that that in any of its alias(es). With such attributes it may be necessary to use the 'original' designator to ensure the original note's value rather than the value of alias inside the agent is altered.
The 'Link type honouring operators' designator is also useful as it can be used in both the agent query and agent action to use a value stored in an attribute of agent. The allows either/both the query or action to be altered simply by editing attribute(s) in the agent itself. A useful manner of doing this is to make those attributes 'Displayed Attributes' in the agent.
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 is that adornments may be added to agent maps.
An agent may be a separator ($Separator). This option is set via the Properties Inspector's Prototype sub-tab. 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, Displayed Attributes and other note features although an agent may be used simply as a filter to gather—and act upon—aliases.
As an agent's output is primarily the effect of its 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 a separate 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' aspects like utility agents, 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 use the $Rule and $Edict attributes allowing it to apply changes to itself as well as its contained aliases.
Queries match both actual notes as well as their aliases. 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.