SMAS 2.0b

A Primer

7. Macros and Functions for Creating an Application

In this section the user will find the list of the basic function allowing to create simple simulations.

defagent name &key redefine ...............................................macro

name: name of the agent
redefine: controls whether the agent can be redefined (t) or not (nil)

If the redefine option is not chosen then it is not possible to reload a file containing the definitions of the agents. Allowing to redefine the agent allow to reload the definition file as many times as needed, which is a good idea when designing a new application.

? (defagent MUL-1 :redefine t)

defskill skill-name agent-name &key static-function dynamic-function ..macro

skill-name: name qualifying the skill. This name will be specified in incoming messages requesting the help of the agent.
agent-name: the name of the agent
static-function: the name of a function which will implement the static part of the skill
dynamic-function: the name of a function that will implement the dynamic part of the skill, if needed.

The dynamic part is not required for simple actions that do not lead to setting up subcontracts.

? (defskill MULTIPLY MUL-1 :static-fcn static-multiply)

defscenario name &rest steps ................................................macro

name: a symbol qualifying the scenario. It will appear in the scenario scroll-down list of the control panel.
steps: a list of steps specifying what to do at what time. A step has the following syntax:

(<date> <message-type> <target-agent> {<action>} <arg-list> 
                       {<protocol><timeout>})

where

date: an integer specifying the logical time message-type: type of the message to be delivered

:request speciafying a message which needs an answer
:inform specifying a message which does not require any answer
:internal deposits the message directly into the input-messages of the target agent.

target-agent: name of the agent to process the message
action: name of a skill of the target agent
arg-list: a list containing arguments for the specified skill
protocol: an optional argument specifying the protocol governing the exchange (default is :basic-protocol, but :contract-net can be specified)
timeout: an optional number specifying a timeout delay

Example:

(defscenario SC-2
   (1  MUL-1 :request MULTIPLY (6 6))  
   (3  MARCOS :inform (\"Station S-23 is down\"))
   (5  FACTORIAL :request SEND-REQUEST ((MUL-2 MULTIPLY (3 4) :basic-protocol)))
   (12 PROXY :request SEND-REQUEST ((FACTORIAL DUMB-FACTORIAL (5))))
   (15 PROXY :internal SEND-INFORM ((ALL INFORM (\"All is well\"))))
   (17 EXPERT-SYSTEM :internal SEND-INFORM 
                      ((MARCOS INFORM (\"All is up and running again\"))))
   (21 EXPERT-SYSTEM :internal SEND-REQUEST 
                      ((MARCOS ASK (\"What time is it?\")))))

All defined scenario names will appear in the pull-down list of the control panel.

create-subtask agent ..........................................................function

agent: agent name

The function simply creates a new task identifyer, e.g., ST-23.

send-subtask agent &key to action args delay repeat-count................function
task-id timeout protocol

agent: name of the agent
to: name of the target agent to which the message is sent. If the symbol ALL is used, then the message is broadcasted to all the existing agents
action: requested skill
args: arguments for the requested skill
delay: time added to the subtask creation delay for determining at what time the message will be sent (default is 0)
repeat-count: number of time the message is being resent after a timeout error
task-id: subtask identifyer (if not present, an adentifyer is assigned by calling create-subtask)
timeout: timeout demay (default 0)
protocol: :basic-protocol or :contract-net

The send-subtask function is used in the skills to issue subcontracts. If the subcontractor is known, then the message can be directed to a particular agent using the basic protocol, otherwise it is possible to broadcast a message using the contract-net. Various parameters can be specified while doing that. If they are not specified, then reasonable default values are used instead.

Example:

The following call broadcasts a request for multiplying 2 numbers, using the contract-net protocol.

(send-subtask agent :to 'ALL :action 'multiply :args (list answer res) 
                             :protocol :contract-net)

update-environment agent environment .....................................function

agent: name of the agent
environment: content of the environment

The function is a facility to let the user handle the environment (agent memory) as the value of the environment variable. The variable is recorded at the agent level, and is persistent.

pending-subtasks? agent .....................................................function

agent: name of the agent

Returns the number of pending subtasks for a given agent. If asked from the functions implementing a skill for a given agent, then the number is at least 1, the one corresponding to the current process. In that case, if the answer is exactly one, it means that no other subtasks is being processed for the agent, and thus the skill can invoque the dynamic-exit function.

static-exit agent arg ..........................................................function

agent: name of the agent
arg: value to be returned

dynamic-exit agent result &optional delay .................................function

agent: agent name
result: the value to be returned to the calling agent
delay: an additional delay to be added to the *dynamic-exit-delay* parameter

When the agent calls this function from within the dynamic part of a skill, then SMAS buils an answer message to be returned to the sender of the initiating message, the message is put into the :delayed-output tray and the status of the agent is changed from :waiting-for-answer to :busy.

Copyrignt Jean-Paul Barthès@UTC, 1998 Last update, Jan 99