AJAN Agent Template - aantakli/AJAN-service GitHub Wiki

An agent template is a template to instantiate new agents of this type. An agent template is described in RDF and consists of four components: a label to describe the template in an understandable way; 0 to n RDF resources referenced as initial knowledge that is stored in the agent KB after initialization; 1 to n endpoints through which an agent can be addressed from outside; 1 to n events that are generated by the endpoints and trigger the behaviors; 1 to n behaviors that execute the actual agent behavior in a separated threads.

The order of execution to execute an agent behavior is as follows:

Domain RDF Information -> Agent [ Endpoint -> Event <-> Behavior ] -> Domain Change

There are two special behaviors: 0 to 1 behavior that is executed immediately after creating an agent, so to speak the initial behavior; and 0 to 1 behavior that is executed when deleting an agent, for example to log off the agent from services, so to speak the final behavior.

To model agent templates either the AJAN editor (currently not available) or the Turtle/RDF definitions file can be used: AJAN-service/executionservice/use-case/agents/agent.ttl

@prefix : <http://localhost:8090/rdf4j/repositories/agents#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix ajan: <http://www.ajan.de/ajan-ns#> .

# ----------- Templates -----------

:ExampleAgent
	rdfs:label "Example Agent"^^xsd:string ;
	a ajan:AgentTemplate ;
	ajan:agentInitKnowledge :ExampleKnowledge1 ;
        ajan:agentInitKnowledge :ExampleKnowledge2 ;
	ajan:endpoint :ExecuteEndpoint ;
        ajan:event :ExecuteEvent ;
	ajan:behavior :ExampleBehavior ;
        ajan:initialBehavior :InitialBehavior ;
	ajan:finalBehavior :FinalBehavior .

With the predicate ajan:agentInitKnowledge in the agent template, information can be given to the instantiated agent in advance. This information must be contained in the RDF repository for agent templates. Alternatively, this information can also be entered in the agents.ttl.

@prefix : <http://localhost:8090/rdf4j/repositories/agents#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix test: <http://test/> .

# --------- InitKnowledge ---------

:ExampleKnowledge1
	test:test1 "Hallo1"^^xsd:string ;
	test:test2 "Hallo2"^^xsd:string .

:ExampleKnowledge2
	test:test3 "Hallo3"^^xsd:string .

An AJAN agent endpoint is an interface of the agent to its environment/domain. This interface can be used to send RDF information (e.g. via HTTP post) to the agent. Various available endpoints can be addressed via the keyword capability. If RDF information is received via such an endpoint, a defined event is generated within the agent, which in turn controls a behavior. Below is an example HTTP endpoint of an instantiated agent:

http://localhost:8080/ajan/agents/<Agent>?capability=<endpoint>

With the predicate ajan:endpoint in the agent template, an endpoint (e.g. HTTP) can be given to the instantiated agent. This endpoint must be contained in the RDF repository for agent templates. Alternatively, this endpoint can also be entered in the agents.ttl.

Below is an endpoint description for the following HTTP endpoint http://localhost:8080/ajan/agents/ExampleAgent?capability=execute of the ExampleAgent, which creates an ExampleEvent event inside the instantiated agent after receiving information via HTTP Post RDF

@prefix : <http://localhost:8090/rdf4j/repositories/agents#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix ajan: <http://www.ajan.de/ajan-ns#> .

# ----------- Endpoints -----------

:ExecuteEndpoint
	a ajan:Endpoint ;
	rdfs:label "Execute Endpoint" ;
	ajan:capability "execute";
	ajan:event :ExecuteEvent .

An agent event is an event that executes a behavior associated with it. Such an event can be created either by the previously described endpoints or by a behavior itself. Such an event contains RDF information as a default or named graph that an executed behavior can use for decision making. If an agent receives information via an endpoint RDF, a new event is created that contains exactly this information. The same applies to events created in Behavior, see chapter 7 SPARQL BT Events.

There are two main types of events: typical events; and so-called goals, which have preconditions and postconditions and if such an event was created by a behavior, this behavior waits until the event was processed by another behavior.

As already mentioned, typical events are different from goals. If a goal is created by an AJAN Behavior, this Behavior waits until the goal is processed. For a typical event the Behavior would instead continue with its execution directly.

If a goal is instantiated, bound variables, the so-called preconditions, must be given to it. Which variables must be bound, i.e. which variables are assigned is defined by the keyword ajan:variables. A ajan:Variable has a variable name (sp:varName) and a data type (ajan:dataType). If a goal was processed by a linked Behavior, the creator Behavior is notified and the agent state is validated with a SPARQL ASK query. If false is returned during validation, the goal was not achieved.

With the predicate ajan:event in the agent template, behaviors can be assigned to an instantiated agent. Those event definitions must be contained in the RDF repository for agent templates. Alternatively, this information can also be entered in the agents.ttl.

@prefix : <http://localhost:8090/rdf4j/repositories/agents#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix ajan: <http://www.ajan.de/ajan-ns#> .
@prefix sp: <http://spinrdf.org/sp#> .

# ----------- Events -----------

:ExecuteEvent
	a ajan:ModelEvent ;
	rdfs:label "e_executeEvent"^^xsd:string  .

# ----------- Goals ------------

:PositionGoal
	a ajan:Goal ;
	rdfs:label "g_positionGoal"^^xsd:string ;
	ajan:variables (
		[ a ajan:Variable ;
		  sp:varName "part" ;
		  ajan:dataType rdfs:Resource ]
		[ a ajan:Variable ;
		  sp:varName "tool" ;
		  ajan:dataType rdfs:Resource ]
		[ a ajan:Variable ;
		  sp:varName "operation" ;
		  ajan:dataType xsd:string ]
	) ;
	ajan:condition """
		ASK
		WHERE {
			?s ?p ?o .
		}"""^^xsd:string .

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix test: <http://test/> .

agents:ExampleEvent {
	test:GoalPart rdf:value ?partValue .
}

PREFIX sp: <http://spinrdf.org/sp#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX agents: <http://localhost:8090/rdf4j/repositories/agents#>

agents:PositionGoal {
        ?part sp:varName "part".
	?part rdf:value ?partValue .
	?tool sp:varName "tool".
	?tool rdf:value ?toolValue .
	?operation sp:varName "operation".
	?operation rdf:value ?operationValue .
}

An AJAN Behavior connects one or more events to a SPARQL-BT using the keyword ajan:trigger. Exceptions are Initial (ajan:InitialBehavior) and Final (ajan:FinalBehavior) Behaviors, which do not need an event to be executed, because they are executed directly after the agent instantiation or termination. The keyword ajan:trigger is in those cases not needed.

With the predicate ajan:behavior, ajan:initialBehavior or ajan:finalBehavior in the agent template, behaviors can be assigned to an instantiated agent. Those behavior definitions must be contained in the RDF repository for agent templates. Alternatively, this information can also be entered in the agents.ttl.

@prefix behaviors: <http://localhost:8090/rdf4j/repositories/behaviors#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix ajan: <http://www.ajan.de/ajan-ns#> .

# ----------- Behaviors -----------

:InitialBehavior
	a ajan:InitialBehavior ;
	rdfs:label "Initial Behavior" ;
	ajan:bt behaviors:InitialBehavior .

:FinalBehavior
	a ajan:FinalBehavior ;
	rdfs:label "Final Behavior" ;
	ajan:bt behaviors:FinalBehavior .

:ExampleBehavior
	a ajan:Behavior ;
	rdfs:label "Example Behavior"^^xsd:string ;
	ajan:trigger :ExecuteEvent ;
	ajan:bt behaviors:ExampleBehavior .