Agent Introduction

In this Lesson

You will learn the role that agents play and how they transform product development.


An agent provides the data and function for a scene. If the scene is a skin then the agent is the muscle that brings it to life. Agents live in the space between scenes and datasources ( or other services ).

Given its location in the technology stack one might assume that the Agent pulls everything together and controls what takes place but that would be an invalid assumption. In fact, the opposite is true. Agents don’t control anything. They don’t even know what a scene is – but we are getting ahead of ourselves.

Program control structures

To understand what an agent is we should first look at how an agent behaves. Once you know how an agent behaves you will be better equipped to understand its form and function.

Let’s talk about program control structures: those bits of code in a program that choreograph the dance.

Let’s imagine that we were asked to create a program for the following design. The colors represent the 4 types of information in the Party Pool data model.

Any program that implements this design would have to be aware of the 4 types of information and ensure that the proper information is displayed when a party or menu item is selected. If a fifth type of information were introduced to the model ( such as party staff assignments, or budgets ) then the program would have to be modified to incorporate the new information.

In short, the program is in control and its control mechanisms must be adjusted when the data model expands or contracts.

This approach has the data model in two places

  1. In the database itself
  2. In application code
    [ party #7 has been selected so I need to find the menu items for party 7, find the guests for party 7, find the … ]

The product team needs to keep these in sync at all times and that takes a fair amount of work – especially as the product changes over time. This occurs because the application is trying to be in control.

The controlling model

Let’s take another look at the approach we just described but let’s reframe the discussion as though we were dealing with real people instead of some arcane technology that creates everything from ones and zeros.

Imagine that we have 4 information experts – people who are experts on one specific piece of the information model.

Now let’s introduce a 5th person, the Party Controller

When Kim is asked to select a party she does something like this

  1. There are 10 parties available. I think I’ll choose #7.
  2. The party guidelines tell me that 4 pieces of information are needed for each party
    • Hey Kerrin! Go get the party name, location, host, and contact information for party #7.

    • Jim, please give me list of the menu item names for party #7 and can you sort them by the order in which they will be served to the guests?
    • Brandon, can you provide me with the name and email address of each guest invited to party #7? I don’t need their RSVP response.
    • Jamie, no one has asked about a menu item yet, so please put away all your food information.

Kim was asked to be in control and she is doing it. She is acting like the data model control mechanisms in the application program and telling everyone exactly what to do. She is following the party guidelines. [ the database model ]

If the company hires a new expert that deals with staffing then the party guidelines would need to be modified [ the database model ] and Kim would need to be re-educated on how to control the party selection process [ the application code ].

What would it feel like if the application code simply stopped trying to be in control? Perhaps it would feel more like a party.

The Party Model

Soiree takes a different approach. It treats the data model more like a party.

When you host a party you might provide food, entertainment, and music but you probably would never tell your guests how to talk with each other. The conversation among your guests is spontaneous and free flowing. You probably have many conversations taking place – all on different topics and all taking place at the same time. Each person may participate in a conversation if they hear one that interests them.

What you might do, if you are bold enough, is to suggest a topic of conversation such as Hey everybody what do you think about those { fill in your favorite sports team }?. At which point everyone starts telling you exactly what they think of your team.

Now let’s return to our example but let’s ask Kim to be a party facilitator instead of a party controller

Kim’s party selection process would look something like this

  1. There are 10 parties available. I think I’ll choose #7.
  2. Hey everybody, what about party #7?
    Anyone in the room may add their voice to the conversation
    • Kerrin brings the party summary information
    • Jim adds the menu items
    • Brandon provides the guest list
    • Jamie does not contribute anything because she is more interested in talking about a specific menu item and no has mentioned one of those [ she waits expectantly ]

Agents are like the guests in the room that are simply adding their voice to the topic of conversation.


Agents are Java classes that contain the data and processing portion of a Soiree solution. They exist to provide their data and services to the the skin [ scenes ] but they do not control things. Agents are simply event handlers that respond to requests coming from the environment in which they run. You can think of an agent as puzzle piece that can be added to the picture being created by a scene.

Agents operate within a conversation and each conversation may contain one or more topics [ entity keys ]. Agents can participate in the current topic of conversation and they may also change the topic of conversation. Returning to the previous example we might see the following agents adding their content to the scene.

The PartySelector can request that the conversation topic be changed to party #7 and when that occurs all other agents focus their data to that party. Focusing to the topic means:

  • If they have data that is associated with the topic they offer it.
  • If they do not have any data for the current topic they offer no data (and remove any data they had previously been offered).


The topics in a conversation are called the conversation’s context. A conversation’s context is used by the Pump to coordinate the activity of the agents.

Agents must formally declare their use of context. There are 4 only possible declarations.

  • Subscribe
    The agent reads a value from context
  • Publish
    The agent writes a value to context
  • Key
    The agent uses the context value to uniquely identify the information it provides to a scene
  • Create
    The agent is capable of creating the context value
The key is the information an agent focuses on. Example: An agent with a key of ‘party id’ focuses on a party.

Here are the definitions that would be in effect for some of the agents described in the previous graphic.

  • The PartySelector agent
    • Publish: party id
      This agent lets others know when a party is selected.
  • The GuestList agent
    • Subscribe: party id
      This agent needs to know which party is currently in context.
    • Key: party id
      The party id uniquely identifies the set of menu items displayed by this agent.
  • The Party agent
    • Subscribe: party id
      This agent needs to know which party is currently in context.
    • Key: party id
      The party id uniquely identifies the party displayed by this agent.
    • If the Party agent also possessed the ability to create new parties then it would include these declarations
      • Publish: party id
        The new party id must be placed into context when a new party is created because creating a party is equivalent to selecting a party.
      • Create: party id
        Creating a party causes a new party id to be generated.
Important Info
All agents are peers with equal authority to change context.

Agent Types

There are two general types of agents

  • Single-Row
    These agents contain information about a single entity.
    For example, one party.
  • Multi-Row
    These agents contain a list of information.
    For example, a list of parties.

Agent Modes

Agents have a notion of operational modes.

  • View Mode
    This is when an agent is prepared to display information from the system.
  • Add Mode
    This is when an agent is prepared to add information to the system.
  • Change Mode
    This is when an agent is prepared to update information contained in the system.

Each agent may offer zero or more modes. At runtime an agent may be used in one of its modes. For example, one scene may use the agent in add mode while another scene uses the same agent in view mode.

Agent Nodes

Agents store all their data content as nodes in the same way that datasources store their content as values.

The amount of data that an agent can offer is totally up to you. An agent can offer:

  • No nodes at all
    These would be agents that offer services but do not need to offer any information to the scenes.
  • One node
    For example, you could have an agent that provides just the partyName value and nothing else.
  • Many nodes

Agent Events

Agents can advertise events they can handle. A very common event is the delete event. For example, an agent may be displaying information in view mode and also provide a delete event that can be used to delete the information that is being displayed.

Another common event is a select event. Agents that contain a list of information may offer a select event that allows someone to choose one of the items in the list.

An agent can offer an unlimited number of events which are used to trigger some type of specialized processing required by your design.

Each agent may offer zero or more events.

Agent Conduits

Agents can advertise their ability to have information dropped on them [ think drag and drop – not being crushed by an anvil. ]. They do this by offering a conduit.

A conduit acts like a pipe into which something can be dropped.

Each conduit has

  • A name
    The name is used to suggest the type of action that will take place when something is dropped.
  • An optional list of entities
    If entities are specified then only those entities will be accepted into the conduit. If the list is empty then any entity may be slid down the pipe.

For example, a conduit named Add Menu Item may accept a FoodItem entity. The agent would then take the food item from the conduit and add it to the party.

Each agent may offer zero or more conduits.


A scheme is the agent’s public contract . A scheme is used in three ways

  1. The scheme is a definition used by designers to know what an agent offers to a scene
  2. The scheme is a Java class used as data container for the agent’s node and context values
  3. The scheme class is used by the Pump to understand how to weave an agent into a conversation

The scheme nodes, events, and conduits are passed between the scheme and the Soiree client

How agents are started

Agents are attached to scenes and scene layers. When a scene, or scene layer is activated it pulls the attached agents into the conversation. This means that the skin, not the agent, is in control of the flow of the user experience. There are exceptions. An agent can influence workflow but those capabilities are advanced topics beyond the scope of this lesson.

The Pump

The Pump is the environment where agents run. When an agent receives a request it is receiving it from the Pump. It is called a pump because, like a hydraulic system, it makes things move and provides the power that makes heavy lifting easy.

The Pump is a subprocess within SxServer dedicated to the task of ensuring all agents are woven into the conversation and are well behaved. Agents can be thrown out of the conversation if they are not well behaved citizens. [ perhaps you should have called it the Bouncer ]

The Pump is infused with heavy doses of special sauce which is beyond the scope of this lesson. The savor of the sauce is this: it provides the choreographed interplay between agents so that you don’t have to write any code to coordinate their activity. You can add or remove agents without having to ‘wire them together’. You just invite them to the party and good things happen.

Removing the necessity of writing choreography code, or glue code, removes a lot time and complexity from the development process. [ thank you Pump, I’m beginning to see your power ]

The Pump is the party facilitator.

Pump Me Up
The pump provides designers with the ability to build the solution by simply dropping agents into the scene. Without the Pump the user interface would become another engineering/coding task.

Emergent Data Model

An agent is a data model with attitude.
Agents often contain data that represents some portion of the data model. The yellow FoodItem agent represents a single item from the FoodCatalog table. The green GuestList agent represents a collection of all the guests invited to the party. Agents that represent these real-world entities are like living breathing objects. When added to the scene they begin contributing their content. When removed from the scene their contribution leaves but the conversation can continue just fine without them.

Extending the data model to include Staff Assignments is trivial. You create a new table, create an agent that represents the data and then add the agent to the scene.

Removing information from the data model is also trivial. Simply remove the agents and tables.

This ability to easily add or remove information from the data model is what is known as an emergent data model. The operational data model shows up, or emerges, at the very last moment – literally – as the information is combined and displayed on the screen.

The data model does not ‘exist’ in the code you write. It ‘appears’ as the agents come together.

Agents are Egotistical

Agents think the world revolves around them, not because they think themselves special, but because they are clueless.

When agents look around the room all they see is themselves. As agents are running in the Pump they think they are the only one there because

  • Agents cannot see each other
  • Agents cannot interact with each other
  • [ ok, you just killed off the party metaphor ]

Just because agents are unaware of each other does not mean they don’t work together. The Pump ensures that they do.

Agent isolation exists for the following reasons

  1. Knowing about another agent is a form of interdependence
  2. If agents are dependent on each other they must exist together
  3. If agents must exist together you cannot freely add or remove individual agents
  4. If you cannot add or remove individual agents you have reverted to hand-wiring services together

Agents are also totally unaware that scenes exist. Remember, agents do not control anything. Agents are invited to the party by Scenes. The scene decides which agent it wants to invite and the Pump ensures they show up on time. The scene knows about the agent but the agent knows nothing about scenes.

If agents knew about scenes

  1. It would be a form of interdependence
  2. If agents were dependent on a scene they must exist together
  3. If they must exist together it would be impossible to use an agent in more than one scene
  4. If you cannot use an agent in more than one scene you could never use an agent more than once

Agent Reuse

A single agent may be reused by adding it to multiple scenes or scene layers. For example, an agent that provides the party name and party host can be added to any scene that needs either of those values.

Engineers can enhance or harm an agent’s reuse potential
However, just because agents can be reused does not mean all agents are reusable. The engineering team must pay attention to the principles of cohesion and coupling. If you are not aware of cohesion and coupling you should search them out and learn more about them. The short version is this

  • Cohesion
    Cohesion refers to the degree to which the elements of a module belong together.
    High cohesion is good and low cohesion is bad.
  • Coupling
    Coupling is the degree of interdependence between two or more modules.
    Tight coupling is bad and loose coupling is good.

These factors determine how readily something can be reused. They also determine how easily a product can be modified when changes are needed.

A well designed agent should contain only one type of information. The trick is knowing what one type means. One could suggest that all party information is one type of information and therefore belongs together in a single agent. A better suggestion would be to understand that a party itself contains multiple sub-types of information and align your agents to those.

Follow the Database Model
A good place to start is to align your agents with the database model.
A well designed relational database model has already split information into tables that represent highly cohesive units of information. So consider making agents that access a single table.

Follow Purpose
Look for ways to reduce the focus of your agent to meet a specific purpose – especially if that purpose has the potential for being frequently reused. This may mean an agent offers only a sub-set of the columns in a table. It may also mean that an agent offers no data at all and offers only events or conduits.

Objects at the Surface

Object oriented programming presents an interesting paradox. Engineers create objects that contain data and process so they can interact with them as real ‘things’. These objects are used all the time in the murky depths of the engineering realm and help make life in that world much better.

This same power is brought up a level in things like web services where capability is wrapped up in a nicely bundled objects that can be called by anyone. There are even service oriented architectures where the idea is to have as many of these services working together as possible.

However, as these objects get closer to the surface of the application – when they rise to the place where you actually want to use them for the benefit of the ultimate consumer – we then wire them together with procedural code.


But not in Soiree.

Agents bring the power of objects to everyone.
Soiree’s agents are large grain objects. They bring the power of object orientation all the way up to the surface where even non-programmers can reap the benefits of these self-aware, self-absorbed, little creatures.

Objects at the surface can transform your team, your timelines, your cost structures, and your customer satisfaction.

So, now you have met Soiree agents. We will discuss some advanced agent topics in later lessons.