Matchmaker Programmer Guide

Advertising with the Matchmaker

The following public operations require an advertisement as part of their arguments:

advertise | unadvertise

getAgent | getAgentAdv

getAgents | getAgentsAdv

For these operations, the Matchmaker expects a KQML message of the form:

Basic KQML Message Form

(tell
   :operation <name of operation>
   :advertisement <advertisement here>)

For a complete description of all the Matchmaker's operations, see Actions Performed by the Matchmaker.

An advertisement takes the following form. The variables in bold are required; the rest are optional:

Sample Advertisement

( advertisement 
  :name "getInformation" 
  :ontology "weather" 
  :queryLanguage "gin v0.01" 
  :requiredFieldCategories 
   (listof 
    (category 
     :name "primary-keys" 
     :fields (listof (cfield "city" "string")) 
     :attributes (listof )))
  :optionalFieldCategories (listof ) 
  :constraintFieldCategories  (listof ) 
  :outputOnlyFieldCategories 
   (listof 
    (category 
     :name "output" 
     :fields (listof (cfield "weather" "string")) 
     :attributes (listof )))
  :responseIncludesFieldCategories 
   (listof "primary-keys" "output") 
  :postConditions 
   (listof 'true 'false) 
  :agentName "WeatherCNNAgent" 
  :contactPerson "Massimo_Paolucci" 
  :email "paolucci@cs.cmu.edu" 
  :agentDescription "The_weather_following_CNN" 
  :sampleQuery "" 
  :url "http://www.cs.cmu.edu/~softagents/a-match/queryWeatherAgent.html" 
  :host "artemis.cimds.ri.cmu.edu" 
  :port "9328" 
)

This sample advertisement, called "getInformation," is one of the CNN Weather Agent's advertised capabilities. The advertisement uses the "weather" ontology to interpret queries from other agents.

Under "requiredFieldCategories," the advertisement specifies "city" as the ontological variable and "string" as the syntactical variable. These are the input variables. Because the agent advertisement uses the "weather" ontology to interpret input data, the agent will not only accept "city" type as input but also "location," since "location" and "city" are related in the weather ontology.

Under "outputOnlyFieldCategories," the advertisement specifies "weather" as the ontological variable and "string" as the syntactical variable. The agent will thus provide as output the requested city name's "weather" in the form of a "string."

In addition, please note:

The Matchmaker uses the "ontology" field, the "requiredFieldCategories," and the "outputOnlyFieldCategories" to perform its matching operations. The other variables of an advertisement do not contribute to the Matchmaker's matching engine.

The "requiredFieldCategories" variables may be under-specified. This is useful if you do not want to overdetermine the user's input terms.

Only the advertisement variables in bold above are required.

The last six variables of an advertisement (i.e., agentName, contactPerson, email, agentDescription, sampleQuery, url, host, and port) are recommended.

There should be no spaces betweeen the double quotes of an advertisement.

Description of Required and Recommended Variables

Required Variables: name | ontology | requiredFieldCategories

outputOnlyFieldCategories

VARIABLE	DESCRIPTION
name	Name of advertisement
ontology	The ontology domain (e.g., weather, travel) for this advertisement
requiredFieldCategories	The input variables, including ontological type and syntactical type, that the advertisement recognizes
outputOnlyFieldCategories	The output variables, including ontological type and syntactical type, that the advertisement generates in response to a query

Recommended Variables

agentName | contactPerson | email

agentDescription | sampleQuery

url | host | port

VARIABLE	DESCRIPTION
agentName	The name of the agent
contactPerson	Your name
email	Your email address
agentDescription	A short description (in natural language) of your agent's capabilities
sampleQuery	A sample input string to the agent
url	The web address of the agent
host	The host name your agent is running on
port	The port number your agent uses