How can agents use the environment?

What is an Artifact?

ToBeCompleted

observeProperty

code,example

 observeProperty(String name, OpFeedbackParam<ArtifactObsProperty> prop)

What are the default artifacts at the disposal of agents?

By default, each workspace contains a basic set of predefined artifacts that provide core functionalities to the agents.

  • workspace artifact cartago.WorkspaceArtifact (see the Workspace API): the workspace artifact provides functionalities to create, dispose, lookup, link, focus artifacts of the workspace. It provides also operations to set roles and policies related to the RBAC security model.

  • node artifact cartago.NodeArtifact (see the Node API) provides functionalities to create new workspaces, to join local and remote workspaces

  • blackboard artifact cartago.tools.TupleSpace provides a tuple space that agents can exploit to communicate and coordinate with each other.

  • console artifact cartago.tools.Console provides functionalities to print messages on standard output.

How can an agent use and access the Manual of an Artifact?

An agent can use and access the Manual of an Artifact through the ManRepoArtifact Artifact.

How to store the Manual?

An agent can use the operation storeManual of the ManRepoArtifact as follows:

  storeManual(String artifactModelName, String uri)

How to get the Manual of an artifact of a certain type?

An agent can use the operation getManualContent of the ManRepoArtifact as follows:

  getManualContent(String artifactModelName, OpFeedbackParam<String> content)

How to consult the Manual of an artifact of a certain type?

An agent can use the operation consultManual of the ManRepoArtifact as follows:

  consultManual(String artifactModelName)

How can agent use and operate on a Node?

How to get the Id of a node?

An agent can get the Id of a node by using the operation getNodeId of the NodeArtifact where param is the parameter receiving the Node Id.

  getNodeId(OpFeedbackParam<NodeId> param)

How to enable Linking with Node?

An agent can enable linking with node by using the operation enableLinkingWithNode of the NodeArtifact where id is the Node Id, support is the kind of support and address is the address of the node to link with.

  enableLinkingWithNode(NodeId id, String support, String address)

How to shutdown a Node?

in a graceful way

An agent can shutdown a node by using the operation shutdownNode of the NodeArtifact calling the dispose routines of all the artifacts.

  shutdownNode()
and after one second shutdown the VM

by using the operation crash of the NodeArtifact

  crash()

How can an agent get information on the workspaces in a Node?

An agent can use and access the workspaces through the NodeArtifact

Working in workspaces

  • By default an agent, when launched, joins the default workspace on current node.

  • Agents can create, join and work in multiple workspace at a time. However there is always a current workspace, to which are routed actions with no artifact id or workspace id specified.

  • Agents can join workspaces that are hosted on remote nodes, by means of a joinRemoteWorkspace action. As soon as the join succeed, the interaction within remote workspaces is the same as local workspace.

How to get the workspaces of a Node?

By focusing on the Node Artifact

By focusing on the NodeArtifact, getting the observable property workspace(name, wspId)

By discovering a workspace by name

By using the operation lookupWorkspace on the NodeArtifact where workspaceName is the name of the workspace and aid is the output parameter receiving the workspace id

lookupWorkspace(String wspName, OpFeedbackParam<ArtifactId> aid)

How to join a workspace?

a local one

by using the operation joinWorkspace of the NodeArtifact where wspName is the workspace name and res is the output parameter receiving the workspace id

joinWorkspace(String wspName, OpFeedbackParam<WorkspaceId> res)
a local one, giving credentials

by using the operation joinWorkspace of the NodeArtifact where wspName is the workspace name, cred are the agent credentials, res is the output parameter receiving the workspace id.

  joinWorkspace(String wspName, AgentCredential cred, OpFeedbackParam<WorkspaceId> res)
a remote one

by using the operation joinRemoteWorkspace of the NodeArtifact where wspName is the workspace name, address is the address and res is the output parameter receiving the workspace id.

joinRemoteWorkspace(String wspName, String address, OpFeedbackParam<WorkspaceId> res)
a remote one with infraServiceType

by using the operation joinRemoteWorkspace of the NodeArtifact where wspName is the workspace name, address is the address, infraServiceType is the infrastructure service type (use /"default"/ to use default one), and res is the output parameter receiving the workspace id.

joinRemoteWorkspace(String wspName, String address, String infraServiceType, OpFeedbackParam<WorkspaceId> res)

Infrastructure options:

  • by default, Jason programs using CArtAgO environment create a standalone CArtAgO node, i.e. not accessible through the network

  • To install a CArtAgO node accessible also to remote agents further parameters can be specified to the c4jason.CartagoEnvironment:

    • c4jason.CartagoEnvironment("infrastructure"\{,WspName, protocol(ProtName, Address), …​}): installs an infrastructure layer specifying the protocols to support and the local address where to start the service;

    • c4jason.CartagoEnvironment("remote"\{,WspName, protocol(ProtName, Address), …​}): does not install any node – agents directly join the specified remote workspace;

    • c4jason.CartagoEnvironment("local"\{,WspName}): does not install any node – agents directly join the specified local workspace.

How to quit workspace?

An agent can qui a workspace by using the operation quitWorkspace of the WorkspaceArtifact that it wants to quit

  quitWorkspace(WorkspaceArtifact WspId)

How to create a workspace ?

in the local node.

An agent can create a workspace in the local node by using the operation createWorkspace(String name) of the NodeArtifact where name is the name of the workspace

in the local node, with a topology

An agent can create a workspace in the local node by using the operation createWorkspaceWithTopology(String name, String topologyClassName) of the NodeArtifact where name is the name of the workspace and topologyClassName is the topology

in the local one with a logger

An agent can create a workspace in the local node by using the operation createWorkspace(String wspName, ICartagoLogger logger) of the NodeArtifact where wspName is the workspace name and logger of type ICartagoLogger is the logger

How can an agent use and access artifacts within a Workspace?

An agent can use and access artifacts within a workspace through the WorkspaceArtifact

How to make agents invoque operations of the artifact?

  • In case of operation invocation with no specification of target artifact: the artifact is automatically selected from the workspace. If there are no artifacts providing such action, the action fails. if more than one artifact is found, artifacts created by the agent itself are considered first. If more than one artifact is found, one is selected non deterministically. Then, the rest of the artifacts are considered, and one is selected non deterministically.

  • In case of operation invocation with specification of a target artifact: This is done by adding the annotation [artifactid(Id)], where Id must be bound to the artifact identifier. Alternatively, the annotation [artifactname(Name)] can be used, where Name must be bound to the logic name of the artifact.

  • In case of operation invocation with specification of the target workspace: done by adding the annotation [wspid(WspID)], where WspID must be bound to the wsp identifier.

How to create or delete Artifacts?

Create a new artifact

by using the operation makeArtifact of the WorkspaceArtifact where name is the name of the artifact, template is the artifact template (type) and aid is the output parameter receiving the artifact id.

  makeArtifact(String artifactName, String templateName, OpFeedbackParam<ArtifactId> aid)
Create a new artifact with configuration

by using the operation makeArtifact of the WorkspaceArtifact where name is the name of the artifact, template is the artifact template (type), artifactconf the artifact configuration and aid is the output parameter receiving the artifact id.

makeArtifact(String artifactName, String templateName, ArtifactConfig artifactconf, OpFeedbackParam<ArtifactId>   aid)
Add an artifact factory

by using the operation addArtifactFactory of the WorkspaceArtifact where factory is the artifact factory.

  addArtifactFactory(ArtifactFactory factory)
Remove an existing artifact factory

by using the operation removeArtifactFactory of the WorkspaceArtifact where name is the factory name

  removeArtifactFactory(String name)
Dispose Artifact

by using the operation disposeArtifact of the WorkspaceArtifact where id is the artifact id.

  disposeArtifact(ArtifactId id)

How to get the artifacts within a workspace?

By focusing on the Workspace Artifact

By focusing on the Workspace Artifact, getting the observable property artifact(artifactName, templateName, id)

By discovering an artifact by name

Using the operation lookupArtifact of the WorkspaceArtifact where artifactName (string) is the name of the artifact, aid is the output parameter receiving the id of the artifact.

  lookupArtifact(String artifactName, OpFeedbackParam<ArtifactId> aid)
By discovering an artifact by type

Using the operation lookupArtifactByType of the WorkspaceArtifact where artifactName (string) is the name of the artifact, aid is the output parameter receiving the id of the artifact.

  lookupArtifactByType(String artifactType, OpFeedbackParam<ArtifactId> aid)

For instance lookupArtifactByType("cartago.WorkspaceArtifact",Id) in a jason program will return the id of WorkspaceArtifact in the current workspace, lookupArtifactByType("tool.Counter",Idbis) will return the id (in IdBis) of the artifact created in the application of type tool.Counter, i.e. the artifact of type Counter in package tool.

By getting the list of available artifact names

Using the operation getCurrentArtifacts of the WorkspaceArtifact where list is the output parameter receiving the list of the artifact names.

  getCurrentArtifacts(OpFeedbackParam<String[]> list)
By getting the current artifact list

Using the operation getArtifactList of the WorkspaceArtifact where artifacts is the output parameter receiving the list of the artifact ids.

  getArtifactList(OpFeedbackParam<ArtifactId[]> artifacts)

How to observe artifacts?

Start observing

Using the operation focus of the WorkspaceArtifact where aid is the artifact id on which ones wants to focus.

  focus(ArtifactId aid)
Start observing when available

Using the operation focusWhenAvailable of the WorkspaceArtifact where artName is the artifact name

  focusWhenAvailable(String artName)
Start observing for specific events

Using the operation focus of the WorkspaceArtifact where aid is the artifact id, filter is the filter to select which events to perceive

  focus(ArtifactId aid, IEventFilter filter)
Start observing for specific events when available

Using the operation focusWhenAvailable of the WorkspaceArtifact where artName is the artifact name, filter is the filter to select the events to perceive

  focusWhenAvailable(String artName, IEventFilter filter)

How to stop Observing artifacts?

Stop observing an artifact

Using the operation stopFocus of the WorkspaceArtifact where aid is the artifact id that one wants to stop focusing on

  stopFocus(ArtifactId aid)

Using the operation linkArtifacts of the WorkspaceArtifact where artifactOutId is the artifact id source of the link, artifactOutPort is the port of the source, artifactInId is the artifact id of the target of the link

  linkArtifacts(ArtifactId artifactOutId, String artifactOutPort, ArtifactId artifactInId)

How to add a specific rule-based management to a workspace?

Using the operation setWSPRuleEngine of the WorkspaceArtifact where man is the rule engine to add

  setWSPRuleEngine(AbstractWSPRuleEngine man)

How to add a specific topology to a workspace?

Using the operation setWorkspaceTopology of the WorkspaceArtifact

  setWorkspaceTopology(AbstractWorkspaceTopology topology)

COMMENT manuals management

create manual

  • createManual(String src, OpFeedbackParam<ArtifactId> aid)

create manual from file

  • createManualFromFile(String fname, OpFeedbackParam<ArtifactId> aid)

How to add RBAC to a workspace?

Setting a security manager

Using the operation setSecurityManager of the WorkspaceArtifact where man is the security manager

  setSecurityManager(IWorkspaceSecurityManager man)
Adding a role

Using the operation addRole of the WorkspaceArtifact where roleName is the role Name to add

  addRole(String roleName)
Removing a role, if it exists

Using the operation removeRole of the WorkspaceArtifact where roleName is the role Name to remove

  removeRole(String roleName)
Getting the current roles list

Using the operation getRoleList of the WorkspaceArtifact where list is the role list

  getRoleList(OpFeedbackParam<String[]> list)
Adding a policy to a role

Using the operation addRolePolicy of the WorkspaceArtifact where roleName is the role name, artifactName is the artifact name, policy is the policy

  addRolePolicy(String roleName, String  artifactName, IArtifactUsePolicy policy)
Removing a policy

Using the operation removeRolePolicy of the WorkspaceArtifact where roleName is the role Name, artifactName is the artifact name

  removeRolePolicy(String roleName, String  artifactName)
Setting the default use policy

Using the operation setDefaultRolePolicy of the WorkspaceArtifact where roleName is the role name, artName is the artifact name, policy is the policy to add

  setDefaultRolePolicy(String roleName, String artName, IArtifactUsePolicy policy)

How can an agent use the organization?

Being part of an organization means for an agent to be able to get the current state of the organization entity and to execute organizational actions on the organization entity. Actions and current state are brought to the agents by organisational artifacts: GroupBoard and SchemeBoard

How can an agent use Groups?

Agents may use groups by using the GroupBoard Artifact (see the GroupBoard API)

How to manage groups?

How to create a group?

An agent can create a group instance by using the makeArtifact operation using a GroupBoard artifact template ToBeCompleted

How to delete a group?

A group can be deleted by destroying the artifact (GrId) that manages it and then disposing the corresponding Artifact.

  destroy()[artifact_id(GrId)];
  disposeArtifact(GrId);
How to get the group specification of a group?

The group specification is accessible through the observable property mapped to specification(….) agent’s belief - annotated with artifact(artifact id) (a prolog like representation)

  group_specification(group type id, list of role, list of sub-groups, properties)

Each role in the list is: role(id,min cardinality, max cardinality, list of compatible roles, list of links), each link is: link(type, target, scopo) (see explanations)

How to enter a group?

  • for now the only way to enter a group is by adopting a role

How to manage roles within a group?

How to adopt a role?

An agent can try to adopt role in the group by calling the action adoptRole on the GroupBoard in charge of the management of the group

  adoptRole(String role)
How to leave a role?

An agent can try to leave/give up /role/in the group by executing the action leaveRole on the GroupBoard in charge of the management of the group

  leaveRole(String role)
How to know what roles are played in a group?

An agent can know the roles that are played in a group by accessing to the observable property mapped to an agent’s belief - annotated with the group artifact id - play with agent being the agent is playing the role in the group

  play(agent, role, group)

How to manage social scheme responsibilities of a group?

How to start a group being responsible of a social scheme?

An agent can start a group being responsible for the scheme schId by using the operation addScheme on the GroupBoard in charge on the management of the group

  addScheme(String schId)
How to stop a group being responsible of a social scheme?

An agent can finish a group being responsible for the scheme schId by using the operation removeScheme on the GroupBoard in charge on the management of the group

  removeScheme(String schId)
How to the scheme under the responsibility of a group?

An agent can get the list of schemes ids it is responsible for through the observable property mapped to the agent’s belief - annotated with artifact(artifact id) - schemes

  schemes(ListOfSchemes)

How to manage hierachies of groups?

How to set the parent of a group?

An agent can set a group becoming a subgroup of parentGroupId by using the operation setParentGroup

  setParentGroup(String parentGroupId)
How to get the hierarchy of a group?

An agent cat get the list of subgroup ids of a group through the observable properties mapped to the agent’s beliefs - annotated with artifact(artifact id) - subgroups

  subgroups(ListOfGroupIds)

An agent cat get the parent group id of a group through the observable properties mapped to the agent’s beliefs - annotated with artifact(artifact id) - parentGgroup

  parentGroup(GroupId)

How to manage ownership of a group?

  • ToBeCompleted

How to get the status of a group?

An agent can get the status (i.e. wether the group is well-formed or not) of a group through the observable property mapped to an agent’s belief - annotated with the group artifact id - formationStatus (values are ok and nok)

  formationStatus(OkOrNotOk)

How can an agent use social schemes?

see the SchemeBoard API

How to manage a social scheme?

How to create a scheme?

ToBeCompleted

How to delete a scheme?

A scheme can be deleted by destroying the artifact (SchId) that manages it and then disposing the corresponding Artifact.

  destroy()[artifact_id(SchId)];
  disposeArtifact(SchId);
How to get the scheme specification of a scheme?

The scheme specification is accessible through the observable property mapped to specification(….) agent’s belief - annotated with artifact(artifact id) (see SchemeBoard API) (see explanations)

  scheme_specification(id,goals tree starting by root goal,missions)
How to know which groups are responsible of a scheme?

An agent can get the list of groups responsible for a scheme through the observable property mapped to the agent’s beliefs - annotated with artifact(artifact id) - groups

  groups(ListOfGroups)
How to know that a scheme has been destroyed?

An agent can get the fact that an artifact has been destroyed through the belief destroyed

  destroyed(artifact id)

How to manage goals?

How to set a goal of a social scheme as achieved?

An agent can set a goal as achieved using the action goalAchieved

goalAchieved(String goal)

Note: verifications that the agent is committed to the goal and that the goal has been enabled throwing a normFailure in the case of breaking some regimentation

How to set an argument to a goal?

An agent can set a value for the goal argument var by using the action setArgumentValue

setArgumentValue(String goal, String var, Object value)
How to reset a goal and relaunch its achievement?

An agent can reset the status of a goal by using the action resetGoal

resetGoal(String goal)
How to get a goal state?

The status of a goal is accessible through the observable property mapped to the agent’s belief - annotated with artifact(artifact id) - goalState

  goalState(schId, goalId, list of committed agents, list of agents that achieved the goal, state)

The state refers to the goal status: waiting, enabled, satisfied).

How to manage missions?

How to commit to a mission?

An agent can try to commit to a mission in the scheme by using the action commitMission

commitMission(String mission)

Note: verifications of the mission max cardinality and mission permissions, throwing normFailure in the case of breaking some regimentation)

How to leave a mission?

An agent can leave its misseion in the scheme by using the action leaveMission

  leaveMission(String mission)

Note: verification that the agent is committed to the mission and that the mission’s goals have been satisfied throwing a normFailure in the case of breaking some regimentation

How to get the current mission commitments?

The current mission commitments are accessible through the observable property mapped to an agent’s belief - annotated with artifact(artifact id) - commitment telling that agent ag is committed to the mission in the scheme (we have as many obs prop as commitments)

  commitment(agent, mission, scheme)

How can an agent manage norms and obligations?

How to get the current obligations?

An agent can get current active obligation through the observable property mapped to an agent’s belief - annotated with artifact(artifact id) - obligation:

  obligation(agent,norm,goal,deadline)

How to get the status of a norm?

An agent can get the status of a norm thanks to organizational events mapped to the following agent’s beliefs: oblCreated (the obligation o is created), oblFulfilled (the obligation o is fulfilled), oblUnfulfilled (the obligation o is unfulfilled (e.g. by timeout), oblInactive (the obligation o is inactive (e.g. its condition does not hold anymore))

oblCreated(o)
oblFulfilled(o)
oblUnfulfilled(o)
oblInactive(o)

How to get the reason why a norm has failed?

An agent can get the failure reason f (e.g. due to some regimentation violation) of a norm thanks thanks to organizational events mapped to agent’s belief normFailure:

normFailure(f)