I would like to pull your attention to method Runwithdocumentcontext() of NotesAgent class.
I personally missed this method somehow and found out about it just recently though it was released with IBM Lotus Notes 8.5.2.
It finally allows developers to pass a non-saved NotesDocument to a NotesAgent. Let me explain.
I believe all of you had a task where you needed to pass many constants/parameters/fields to a NotesAgent to let the agent to do some work. Earlier (prior LN 8.5.2) we had only two methods for that:
Notice, since these two methods work with NoteId it is required to save document to be able to pass it to NoteasAgent.
I usually created a temporary document, put required parameters there, saved document and then passed its NoteId to one of the methods mentioned above depends of what I need to rich.
However, the problem of this way was that later I had to clean up after myself - I had to remove that temporary document that I didn't need any more. It wasn't so easy task though. The NotesAgent.Run() method works with a current user's privileges and document deletion can be restricted. The same about NotesAgent.RunOnServer(noteid) in a local replica. Besides that if agent fails then temporary documents can stay in database as garbage. So, to be sure for 100% that I cleaned up everything I had to create a scheduled agent for that that is not the best option also - I personally do not like if database contains many scheduled agents, especially if you use some common template for tens of similar applications. Plus all these things about Server Security - sometimes (if you work for big companies with complex internal policies) it is a tricky thing to get permission to create any scheduled agents, you know :-)
But now, with this nice method NotesAgent.Runwithdocumentcontext(documentcontext as notesdocument, optional byval noteid as string) you can pass any number of parameters to a NotesAgent through a temporary document without need to save it and later delete.