Standard library - agent

module agent
  // module was added in PR#822

  type agent
  type options = map(data)

  // create agent descriptors
  def localAgent : string -> t
  def localPersistentAgent : string -> t
  def remoteAgent : string -> string -> string -> t
  def remotePersistentAgent : string -> string -> string -> t

  // change identity
  case currentToken
  case thisToken(data)
  type credentials = currentToken | thisToken
  def asUser : string -> credentials -> t -> t

  // call agents
  def call : t -> options -> data -> result(string, data)
module end

Create agent descriptors

  def localAgent : string -> t
  def localPersistentAgent : string -> t
  def remoteAgent : string -> string -> string -> t
  def remotePersistentAgent : string -> string -> string -> t

In the following, a local agent is from the same app as the caller, and a remote agent is from a different app. You can describe the normal (one-shot) version of the agent with

• localAgent(name) or
• remoteAgent(baseURL, app, name)

Here, the name is the module name, and baseURL designates the server where the agent can be found (see the env module for functions helping to construct base URLs). The app is the name of the application from which the agent is taken. These agents are “one-shot” agents, i.e. when they are called, a session is created for running the request, and after retrieving the result the session is shut down again. Because of this, the spreadsheet of this type of agent cannot store data across requests (you need to use the db or another external storage system for saving data).

There are also persistent agents:

• localPersistentAgent(name) or
• remotePersistentAgent(baseURL, app, name)

This type of agent does not shut the session down. Each time the agent is invoked, the request is fed into the same spreadsheet.

Change identity

  case currentToken
  case thisToken(data)
  type credentials = currentToken | thisToken

  def asUser : string -> credentials -> t -> t

The function asUser(userName, userCreds, descriptor) allows it to change the identity of the caller to userName and to pass credentials as proof.

Call agents

After creating the descriptor, you can call the agent with:

call(descriptor, opts, param)

Here, opts is a map with options (often empty, {}). The param is the single parameter the agent needs as input (often a map with a couple of fields).

Options:

• enforceSessionIsolation: if set to true, the agent is always executed in its own session. By default, local agents are tried to be executed in the same session as the caller (for speed), which is not as isolated as a separate session. Note that there are also other reasons to use a separated session (e.g. persistency, or running as a different user). As we can nowadays also spawn additional browser-based sessions, there is no guarantee that the session is created on the server.
• enforceServerExecution (since PR1657): if set to true, the agent is forced to run in amp. This also means that it is running in its own session, but it is advised to also specify enforceSessionIsolation as older versions of the stdlib do not know about this option.
• onceKey (since PR1657): if set to some("stringkey"), the result of the agent invocation is cached (per agent name and "stringkey"). For example, if the key is set to the _rmx_id of an agent that displays a record of the DB, the card isn’t recomputed if called later with the same key, and instead the cached version is taken. This feature is only available for local agents.

Examples

One-shot local agent:

agent.call(agent.localAgent("myTest"), {}, {x:"hello"})
 |> result.get

Call the local agent as somebody else (where token is the OAuth token of myFriend):