Tinderbox Forum

Conditional AgentAction to create new child agents

I’m doing some music analysis, part of it is examining the genres’ scene in certain countries. I’m looking to create a treemap view to see an overview of the size of each country’s scene based on the number of prominent local bands.

I’ve only started exploring Agents, so I’m not quite sure what are the limits or possibilities for Agents.

All bands have a filled attribute, $Country. But I need to sort them out without creating a new agent every time I introduce a band from a new country. So I’m looking into a possibility to create an Agent with a query that looks at $Country, and creates a new agent based on its child.

General idea:
Create an agent called “aCountries”
“aCountries” query looks at $Country.
If $Country is not empty, look at the children of “aCountry”.
If the instance of $Country is not present, create a child agent under “aCountry” with $Name=(“Country”); query: $Country=(“Country”).
Else, file the alias under the available child.

An example to better illustrate:
I have an agent “aCountries”. At the moment it has a child agent, “USA”; query: $Country=(“USA”). All notes with $Country=USA are the children of this agent (grandchildren of “aCountries”).

Now, I’ve added a new band from Sweden, so “aCountries” sees that $Country is not empty, but it doesn’t have a child agent named “Sweden”. It creates an agent as its child; $Name=(“Sweden”); query: $Country=(“Sweden”).

I’m not quite sure what my AgentAction or Query for “aCountries” should be. I’m particularly held out by the condition.

That works but correct syntax for the query (thus not causing Tinderbox to guess your intent) is:


Note the == operator for checking equality. The parentheses don’t do anything useful here so are omitted as cruft.

An agent per country? So possibly 193 agent all running at max update speed. I wonder if that is ideal. I suspect some countries don’t have big musical output, but still. You might want to make these agent use a lower $AgentPriority.

You can create an agent in action code using createAgent(). Althuogh there isn’t (I believe) an explicit test for a note/agent pre-existing, the createAgent() won’t do anything if the the desired item already existing (i.e. no harm arises).

You can’t create an agent under an agent. The item/path aCountry would need to be a (container) note.

Given that above, I’m not sure you are describing that correctly. An agent can only match (alias) another agent but it cannot have child notes only aliases of items matching the query. The distinction is important to understand before you try to build nested agents.

The use of agents in this context seems fairly heavy-handed. Can you restate your problem statement? What exactly are you looking to know or understand?

When a new band had been added?
How many bands are in a given country?
How many genres are in a band?

Crosstabs, attribute browsers, dashboards, etc., might be a better approach.

Agree, the Attribute Browser view might be a more useful approach to avoid having tons of agents.

From the wording of the first post I feel like the concept of agent and that of container are confused/being used too interchangeably.

Are you trying to make sure each note has an attribute value for $Country? Are you trying to collect all notes that have no attribute value for $Country?

Start with a simple statement of what you are trying to do in this particular case and help will arrive!

Thank you for your comments. I’ll start by refining my problem statement. I want to categorise the bands by their country of origin for further examination, also to get a relative size on each country’s scene. A more general idea to to group notes based on their attributes, which is a basic use of an agent.

My scope is pretty narrow, probably looking at about a dozen or so countries, but the number of bands per country is unknown at this time.

Say I’m looking at the history of progressive rock. I add “Pink Floyd” as a note, $Country=UK. I have to create an agent that queries $Country=UK. Now I add “Rush”, $Country=Canada. So I have to create another agent that queries $Country=Canada. I can create these agents manually whenever a new country is introduced, but I’m wondering if there is a way to automate this process.

I see that I’ve indeed misunderstood the concept of an agent. Correct me if I’m wrong; Agents act like smart groups, queries are the search parameters. Within the agent, you can also run a series of actions via AgentAction, similar to smart rules. However, I cannot nest an agent under another agent unless the query specifically looks for it.

It seems to be incorrect to create an parent agent to nest other agents that doesn’t fall under the query. Instead, I should be creating a container (in the form of a note?) to nest multiple agents.

But my general question still remains; is it possible to automate the creation of an agent via a new value entry in an attribute?

1 Like

Correct. An agent is NOT a container. You can not nest agents. If an agent returns another agent because another agent matched an agent’s query then that other agent would appear as an alias in the agent’s results.

As for your use of agents, again, I think they’re overkilled with what you appear to want to do; moreover, they will not give you the numerical analysis you want. In this case, Tinderbox views will be your friend.

You could use:

Attribute Browser



Here is a sample file to give you an idea of what I’m thinking. Also, see the Edict in the Fodler’s. This helps you keep your drop-down lists complete as you add new genres or bands.

1 Like

I’m not sure what the master definition of a smart group is, but essentially, Yes. The query tests all notes (queries can use scoping query terms to limit the number of notes tested) and creates an (child) alias for each note it matches. N.B. an alias in-scope of an out-of-scope original note will still make a match. Matched items only generate a single listing (i.e. alias). so if a note and 3 of its aliases all match the query, the item is listed once. By comparison, in a find(query) action, the process lists the paths od all 4 matches. For agent use, the de-duping makes sense: list (and optionally act on) all the items matching the query.

There is no such think as a ‘smart’’ rule. Rules are rules. Edicts are essentially rules, but applied less aggressively. A rule is simply an action applied by a note/alias to itself. In truth ‘smart’ is generally confusing as it has no consistent meaning for all readers. If you mean ‘smart’ as experienced in some other app’s terminology, by all means mention the app, though be aware the wide range of users here (i.e.v using the same tool but for different purposes) means few may also have used app referred to.

The Agent’s $AgentAction is better compared a (container) note’s OnAdd action. Every time the agent runs, i.e. all the time by default, it adds an alias—as a child to the agent—for each matched item. The agents action is run on the added (OnAdd!) aliases.

In fact, as it runs a lot ,the agent is clever enough to not delete all aliases after each run. Rather, on run #2 onwards, it adds new aliases and deleted those for now non-matching items; aliases of still-matching aliases are retained. The agent action runs on the new and retained aliases but the OnAdd metaphor still holds good.

Absolutely not. An agent can only contain aliases or items matching its query.

Yes. An agent is only ever an (outline) container if it has alias(es) matching its query. Notes however, can be notes or containers. The latter are just notes with nested objects.

Note too that map adornments cannot be containers. Indeed, they are only seen in map view.

I see that @satikusala has already expanded on the Attribute Browser view (‘AB view’) which I think is really what you want to be doing.

Though it doesn’t, IIRC, get into AB view you might still find this demo data of interest: Beatles records: demo with example TBXs

The other thing you can do is add a display expression, powered by an $Edict, to your countries. The count in the [ ] is the number of bands from that country.

TBX L - International Band Research.tbx (140.4 KB)

This might be better approached using Attribute Browser.

  1. Focus the attribute browser on bands, either by selecting the container that holds all the bands, or by searching the document (as an agent would) for all the bands.

  2. Examine these notes broken down by $Country. So, for England, you’d have the Beatles and the Stones, from Canada you’d have Rush and Bachman-Turner Overdrive.

  3. If you ran across ONUKA and added it to your bands, the attribute browser would automatically add a new section for bands from Ukraine.

I think this will be much easier than creating new agents!

1 Like

First of all, thank you for all your responses. You have given me resources and suggestions to dive into for a while. One of the first things I explored in Tinderbox is agents, so I believe it has coloured my approach. Considering there are other options available in TB, I agree my use of agents is fairly heavy-handed.

On the finer points.

Apologies for being unclear. Yes I was thinking of Devonthink’s smart rule when I wrote it. I need to run some experiments with $AgentActions to iron out the details.

Thanks for the link. It helps to have an example file that is similar to my work. It also gave me an idea to prepare the majority of my data on a spreadsheet and import them into TB. It didn’t cross my mind until now to look at the example files consolidated in this forum as a tutorial tool.

I’ve not encountered this option before, I will look up $edict in the documentation.

I did not expect a music recommendation here!

Again, thank you for all your help! You have gone above what was asked in my original question. Couldn’t ask for a better support forum.


Here here!!! This is the best community I’ve ever had the pleasure and opportunity to participate with in my life.

1 Like

Thanks for all that. sorry for apparent pedantry, but your reference to DEVONthink is useful. Tinderbox doesn’t use this ‘smart’ notion at all because, effectively, you the user configure everything. You get a lot of control but by design intent you set up the file. In this context though ‘smart’ equates best to a Tinderbox agent - a report/container that always lists things matching the users criteria (here, the agent’s query).

A note’s edict is stored in $Edict. more on edicts.

If doing spreadsheet based import see Setting up for Tab-Delimited Import and Spreadsheet Import: CSV and Tab-Delimited Text.

Another useful import texnique os pasting test into a note’s $Text and Exploding Notes.