Tinderbox Forum

Document seems to not respect agent priorities, and today doesn't include seconds

Hi all,

I have two questions about the attached TBX file.

In the attached TBX document, there are two agents, each updating the text of a different respective notes, adding a timestamp line to each note on each agent update cycle.

I have two questions about this:

  1. One of the agents has $AgentPriority set to highest (0), and the other has $AgentPriority set to lowest (10). But as you can see, the agents are adding lines to their respective notes at the same rate. It seems to me that the high-priority agent should be adding lines at a much faster rate than the low-priority agent.

  2. The agents are printing the current time with a call to `date(today).format(“h:mm:s”). Does anyone know why the number of seconds printed is always zero?



agent-priority.tbx (54.4 KB)

You don’t see a difference as you’re using a minimal test set. Download the aTbRef source TBX and looks at the number of agents therein (c.100 IIRC) and re-run your experiment. The latter scenario is the sort of thing agent priority is designed to address, as well as a scenario where there are a lot of agents that query other agents and so there’s a lot of agent activity.

The agent priority allows you to dial the frequency of re-querying up or down - see here. What I should add to the latter article is than unless an agent is ‘off’ an agent is always on first creation of the agent and whenever you commit an edit to the query. IOW, when you edit the query in Get Info or the Action Inspector - the query runs when you press Return. Indeed in a very complex doc, e.g. not a new starter’s simple 50 note doc, it can be useful to disable a priority when working on a query. That avoids running an incomplete/wrong-syntax query by mistake.

I do stress for later readers that what I’m describing in the paragraph above is more expert-user issue. Agents aren’t hard to use and in small docs they run essentially instantaneously.

I’ll address the time issue in a separate reply as this is long enough already.

Edit: sidenote - you can think of Edicts as low-priority Rules.

1 Like

It is true that Tinderbox uses a date-time format for Date-type data. Tech folk will be familiar with the concept of a date-time in milliseconds based off a reference time. Of course the latter is stored under the hood - or computed internally with the app showing date and time in more human-friendly form.

Over it’s 17-odd year life Tinderbox has varied in its acknowledgement of a second-level time granularity. Some operators seem to use it, others don’t and elide the seconds giving a return like the one you note. although I’ve seen the odd mention of second-scope issues I think as a result it’s lightly tested as there’s no real use case - as yet. There are actions like seconds() for which I’m probably to blame - they were added in a completist way rather than because anyone asked deliberately for such an operator.

Are you asking about this and agent priorities simply by way of explanation or is there a real-world problem you’re trying to test?

HTH :slight_smile:

1 Like

Hi Mark,

Thanks for these great answers!

The seconds question is mostly curiosity. I often find myself grinding up against Tinderbox’s rough edges, like this one, and I want to know if it’s a limit in Tinderbox or in my understanding.

I’m very glad that Tinderbox supports finer-than-minute granularity generally, since I use timestamps, obtained from $Created, as UUIDs in some of my Tinderbox documents, and I often create more than one note per minute. (Given that Tinderbox does support fine time granularity, it strikes me as strange that today would be rounded to the minute, since this seems like it would require more work rather than less, but anyway…)

The agent-priority question does have a real-world problem behind it: I often find that for debugging it’s useful to have an action that only runs manually. This is especially true for multi-stage agent cascades, where one agent narrows the query results of another. I typically hack it by turning an agent on and off, using boolean guards, or use an edict for this. I was kind of hoping for low-priority agents to act like edicts, with update cycles so infrequent that for debugging purposes you can consider them to be manually run, so I was surprised to see the low-priority agent updating regularly.

Would you see any use for an agent priority level that means “manual-update only”? This strikes me as useful.

The way I do that is via a Stamp. It essentially is a manual-update-only agent. Ie:

  • You create and name a Stamp via the Cmd-1 inspector process. You have the action for the stamp be whatever the agent’s action would be;
  • Once you’ve saved it, you can call it up just with two or three keystrokes – Cmd-1, and then clicking on the relevant stamp from the menu;
  • The main difference is that stamps apply to selected notes only–which can be an advantage, in letting you limit or precisely specify the scope of what you want it to work on, or a minor disadvantage, in requiring you to do a Cmd-A “select all” step before running the stamp.

Main point is: there’s already the functional equivalent of a manual-update-only agent, just by a different name. At least that is my amateur understanding of the way stamps work – and the way I use them.


Or, you can have a stamp that toggles the Agent itself on and off


The last action can set priority to 0, 1, 4 or 10

IIRC, @mwra posted this suggested a few years ago in the other forum. I’ve often used his idea.

Or, in a complex document, you can have an agent that turns other agents on and off depending on external factors such as wall time.

1 Like

Thanks, James. That is a good approach.

One bit of missing functionality here is if you use agents just to group things or provide views on the data. Then you’re only relying on the query, not the action, which stamps can’t replicate.

Edit: Actually, stamps can replicated them, by storing the results of a find query in a list, as @mwra points out below.

Ah, good one — thanks, Paul. I’ll couple that with coloring so I can tell which agents are on and which are off.

I think others have covered this pretty well. I endorse both suggestions. Besides colour, I also sometimes use flag badges (sadly there’s no green flag so I use blue instead). It’s a matter of personal taste, but sometimes I find badges can be less visually intrusive.

Often overlooked is that (except in map view) the agent icon shows the on off state. When off, the thick bar at the bottom of the icon is hollow; for all ‘on’ priorities is it filled (i.e. the normal rendering).

There is no run-once agent. You can disable automatic agent updates (File menu)which essentially sets all agents to zero priority. The file menu option to update agents works whether auto updates are one and off, but is generally meant for the off state, it then runs every agent (that is not locally set to off) once. In the this manual mode, if using cascades of agents that look at other agents you may thus need to run the once-only command several times for the cascade to fully update. IOW is agent A looks at agent B which looks at agent C, then you would need to use ‘update now’ 3 times in order for C to reflect changes in A.

Otherwise there is no run-once agent state. As pointed out a Stamp acts like an once-only agent action - or rule - but the user must set the selection; i.e. there is not query.

However, you could make a stamp that uses a find(query) to populate a List-type attribute, use List.each() to apply an action and then reset the list to normal (i.e. no value).

1 Like

Thank you, Mark — very helpful!

Yes, for the debugging use case, turning off Update Agents Automatically gives me the behavior I’m looking for. Between that and the other suggestions, I think I have by bases covered.

Thanks everyone for the suggestions!

1 Like