## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links 
## note.0= [[trex/Tutorials/Interactive execution and visualization|Interactive execution and visualization]]
## descriptive title for the tutorial
## title =An introduction to Agent Actions
## multi-line description to be displayed in search 
## description = In this tutorial you will learn about a standard T-REX model element (an AgentAction) for encapsulating modular, goal-achieving behaviors.
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=[[trex/Tutorials/Create and test your first action|Create and test your first action]]
## next.1.link=
## what level user is this tutorial for 
## level= IntermediateCategory
## keywords =
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TableOfContents(4)>>
== What is an Agent Action and why is it useful? ==
An AgentAction is a T-REX abstraction for a software component that can be activated to pursue a goal, and is inactive when not pursuing a goal. There are various synonyms in regular use in agent architectures - skill, action, behavior. 

An AgentAction is a goal-directed behavior that can be durative (i.e. runs for an extended period of time), and should be pre-emptable. The nice thing about AgentActions is that they act as behavioral building blocks from which more sophisticated tasks can be accomplished. As an implementer of such an action, you can focus on a well bounded problem. As a user of an action it provides a powerful abstraction of what would otherwise be an excessive amount of detail.

== The state model for an action ==
In T-REX, the running state of an Agent Action is a state variable that changes over time. We can express that we want the action to be active, or indeed that we want it to be inactive. Each is a desired value for the state of an action. These semantics naturally map to a timeline. For background material on timelines see [[http://code.google.com/p/trex-autonomy/wiki/CTP#Timelines_and_Tokens|this]].

The figure below illustrates the states and transitions for an Agent Action. Broadly speaking, the action oscillates between Active and Inactive states. In all cases, states may be further qualified with action specific parameters as indicated.

{{attachment:action_state_diagram.png}}

An action can be inactive for a number of reasons:
 * It is inactive because the action completed successfully. This is indicated by a 'Success' sub-state of inactive states.
 * It is inactive because the action aborted (initiated by the action implementation). This is indicated by the 'Aborted' sub-state.
 * It is inactive because the action was preempted (initiated by the executive). This is indicated by the sub-state 'Preempted'.
 * It starts out inactive. In this case it is 'undefined', which just means that no statement is made about the prior running state of the action.

The notion of parametric qualifications to action states is a useful way to provide feedback to the executive on deactivation. More on that later.

== AgentAction class declaration ==
T-REX directly supports actions in a number of ways. Most importantly, an AgentAction is a first class citizen in T-REX, available as an NDDL foundation class in the model file [[https://trex-autonomy.googlecode.com/svn/trunk/agent/base/TREX.nddl|TREX.nddl]]. For more detailed information on NDDL you should review material [[ http://code.google.com/p/europa-pso/wiki/NDDLReference|here]]. 

The inactive sub-states are modeled with the enumerated type:
{{{
enum ResultStatus {UNDEFINED, SUCCESS, ABORTED, PREEMPTED};
}}}
Below is the '''AgentAction''' class declaration, derived from an '''AgentTimeline''':
{{{
/**
 * Encapsulate Actions that have a state of active or inactive
 */
class AgentAction extends AgentTimeline {

  predicate Inactive{
    ResultStatus status;
  }

  predicate Active{
    int dispatch_time; // The time at which the goal was dispatched
    int max_duration; // If duration exceeds this, the token should be preempted.

    // Parameter constraints for internal use only
    dispatch_time <= start;
    start < MISSION_END;
    trex_behavior(object);
  }

  AgentAction(Mode _mode){
    super(_mode, "Inactive", false);
  }
};
}}}
The 2 main states - Active and Inactive - are captured by 2 [[http://code.google.com/p/europa-pso/wiki/NDDLReference#Predicate_Declaration|predicates]]. The sub-states for Inactive are indicated by the '''status''' parameter in the '''Inactive''' predicate declaration. 
{{{
  predicate Inactive{
    ResultStatus status;
  }
}}}
The '''Active''' predicate includes a number of additional parameters pertinent to execution. The dispatch_time will be set by the executive when the goal is dispatched. You can learn more about dispatching timelines[[http://code.google.com/p/trex-autonomy/wiki/TimelinesAndExecution|here]]. It is up to you to constrain the '''max_duration''' parameter. If the '''Active''' state persists without interruption for more than '''max_duration''' ticks, then the action should be preempted. Notice that the start time for all actions must occur before the mission ends. This constraint ensures that goals to activate an action are included by the planner if they can occur within the reactors planning horizon. This is a detail that can be safely ignored for now.
{{{
  predicate Active{
    int dispatch_time; // The time at which the goal was dispatched
    int max_duration; // If duration exceeds this, the token should be preempted.

    // Parameter constraints for internal use only
    dispatch_time <= start;
    start < MISSION_END;
    trex_behavior(object);
  }
}}}
== Agent Action construction ==
As with all NDDL classes, an AgentAction has a [[http://code.google.com/p/europa-pso/wiki/NDDLReference#Composition_and_Construction|constructor]]:
{{{
  AgentAction(Mode _mode){
    super(_mode, "Inactive", false);
  }
}}}
In this case, the ''_mode'' indicates if the action is internal or external to the reactor in which it is instantiated. The notion of a reactor and the concepts of internal vs. external timelines are introduced [[http://code.google.com/p/trex-autonomy/wiki/DivideAndConquer|here]]. The default value for an AgentAction is '''Inactive''', as indicated in the call to the super class constructor.

We will be modeling with AgentActions alot in the coming tutorials.
## AUTOGENERATED DO NOT DELETE 
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE