Tandem Tales Agent Protocol
A Tandem Tales agent connects to the server via a TLS encrypted socket (on port 9005, by default) and plays a single interactive story session. All messages to and from the server are formatted as JSON and terminated by a new line character.
- Starting a Session:
- As soon as a new socket is established, the server sends the Connect message that lists the available worlds and partners.
- When the agent is ready to play, it sends the Join message with the details of who it is and the settings for the game it wants to play.
- Once the server has found a compatible partner, it starts a new session and sends the Start message to both agents, which tells them their roles, about the story world, and the world’s initial state.
- During a Session:
- The game master goes first.
- On the game master’s turn, the game master can
SUCCEEDorFAILany number of actions that do not require the player’s consent. The game master canPASScontrol to the player. The game master canPROPOSEan action if it requires the consent of the player and a non-player character, and then play immediately passes to the player. - The player always chooses one action and then passes control back to the
game master. If the game master’s last action was to
PROPOSEan action, the player must choose whether it willSUCCEEDorFAIL. If the game master’s last action was toPASS, the player canPROPOSEany action that requires the player’s consent orPASScontrol back to the game master without choosing an action. - Each time a turn happens, the server sends an Update message to both agents, which has the history of turns taken so far, the current state, and the choices that agent can make. An agent knows it is their turn if their Update message has choices listed.
- When it is an agent’s turn, they make a choice by sending a Choice message to the server with the index of a choice from their last Update.
- At any time during the session, an agent can send a Report message to the server to record their answer to a question.
- Ending a Session:
- If the story reaches one of its pre-defined endings, the Update message sent to both agents will include an Ending object.
- Either agent may end the session early by sending a Stop message. Once an agent sends a Stop message, it should not send any more messages to the server, but it may stay connected to wait for the End message.
- If an agent disconnects from the server, it is treated as if it had sent a Stop message.
- The server sends a Stop message to the agents when it is time for a session to end. This happens when the story reaches a pre-defined ending, when one agent stops the session early, or when the server is shutting down and needs to end all sessions early.
- When an agent receives a Stop message (but has not yet sent one), it cannot send any more Choice messages, but it can still send Report messages to answer questions. Once an agent sends its Stop message, it cannot send any more messages to the server, but it may stay connected to wait for the End message.
- Once the server has sent a Stop message to both agents, and once both agents have sent a Stop message to the server (or effectively sent one by disconnecting), the server sends the End message to both agents to tell them the session ID number and let them know it is time to disconnect.
If an agent does something that is not allowed, the server may send an Error message explaining the problem. Depending on the error, it may also disconnect the agent.
Messages
Messages are encoded in JSON. All messages include the key type which defines
the type of message as a string that starts with a capital letter. Messages are
always a single JSON object followed by a new line character. If a message
contains a new line character, it should be encoded.
Connect Message
{
"type": "Connect",
"version": "1.0.0",
"worlds": [
{
"name": "tutorial",
"title": "Tutorial",
"description": "A simple story about buying a drink that will teach you how to play."
}
],
"agents": [
{
"name": "random",
"title": "Random",
"description": "An agent that makes random choices."
}
],
"available": [
{
"agent": "random",
"world": "tutorial"
}
]
}
The Connect message is sent from the server to the client as soon as a new
socket is opened.
versiongives the server’s version number as a string.worldsis an array of objects describing which worlds the server has publicly listed as available. Each has aname,title, anddescription.agentsis an array of objects describing which agent types the server has publicly listed as available. Each has aname,title, anddescription.availableis an array of objects listing agents who are currently connected and looking for partners to play in specific worlds. Each has anagentandworld.
Join Message
{
"type": "Join",
"name": "web",
"password": "dummy",
"world": "tutorial",
"role": "PLAYER",
"partner": "random"
}
The Join message is sent from the client to the server when the client is
ready to start its session.
namegives the client’s agent type. It does not need to be unique.passwordgives the client’s password. A password is only required if the client’s name is reserved on the server.worldis the name of the story world the client wants to play in. If this is missing ornull, the client is willing to play in any world.roleis the role the client wants to have in the story. It can bePLAYERorGAME_MASTER. If this is missing ornull, the client is willing to play as either role.partneris the agent type the client wants to play with. If this is missing ornull, the client is willing to play with any partner.
Start Message
{
"type": "Start",
"role": "GAME_MASTER",
"world": # World object #
}
The Start message is sent from the server to the client once the server has
found a compatible pair of agents and started a new session.
roleis the client’s role in the story. It will be eitherPLAYERorGAME_MASTER.worldis a World object.
Update Message
{
"type": "Update",
"status": # Status object #
}
An Update message is sent from the server to the client each time the state of
the world changes.
statusis a Status object.
Choice Message
{
"type": "Choice",
"index": 3
}
A Choice message is sent from the client to the server when it is the client’s
turn to notify the server which turn the agent wants to take.
indexis the array index (starting at 0) of a choice from the most recent Update message sent to the agent.
Report Message
{
"type": "Report",
"item": "structure",
"value": "4",
"comment": "strongly agree"
}
A Report message is sent from the client to the server any time after the
server sends the Start message and before the client sends
their Stop message. It is used by the client to answer
questions about the story or play experience.
itemis the name of the question the client is answering.valueis the client’s answer to the question as a string.commentis a comment on the value as a string.
Stop Message
{
"type": "Stop",
"role": "PLAYER",
"message": "End the session early."
}
{
"type": "Stop",
"message": "The story has ended.",
"ending": # Ending object
}
A Stop message can be sent by either the server or client. It can only be sent
by either party after the server has sent the Start message.
The client can end the session early by sending this message. The server sends
this message if the story reaches one of its pre-defined
endings, if the client’s partner ended the session early or
disconnected, or if the server needs to end the session early (i.e. because it
is shutting down).
roleidentifies which client ended the session early. This should be missing ornullif the story reached a pre-defined ending or if the server is ending the session early.messageis an explanation for why the session is ending.endingis an Ending object. This should be set if the message is coming from the server and the story reached a pre-defined ending; otherwise, it should be missing ornull.
End Message
{
"type": "End",
"session": "MWD7D5R590"
}
The End message is sent by the server to the client once the session is
complete and the client can disconnect.
sessionis a unique ID string that identifies the session in the server logs.
Error Message
{
"type": "Error",
"message": "The message could not be parsed as a JSON object."
}
An Error message is sent from the server to the client if it cannot parse the
client’s message or if the message has invalid values (i.e. if the client sends
a Choice message at the wrong time or with an invalid index).
messageis a string that explains the problem.
Objects
Objects are encoded in JSON. If an object is being sent as part of a Message and contains a new line character, the new line character should be encoded to avoid terminating the message prematurely.
Action Object
{
"id": 0,
"name": "go(Player, Shop)",
"signature": # Signature object #,
"consenting": [ # Entity objects # ],
"description": "The player enters the shop.",
"code": "0001"
}
An Action object defines:
- An
idnumber. All actions in a story world are numbered sequentially starting at 0. - A
name, which is the symbol used to refer to that action. - A
signature, which is a Signature object. - An array of
consentingcharacters, which is an array of Entities that represent the characters in the story who are taking the action. Characters only appear in this array if they are taking the action on purpose. Anattackaction would not list the victim in this array, since the victim is not taking the action on purpose. - A
descriptionas a short natural language phrase. - A
codestring, which is always composed of0s and1s and uniquely identifies the action from other actions in the story world.
Assignment Object
{
"variable": # Variable object #,
"value": # Value object #,
"visible": true,
"description": "The player is outside the shop.",
"code": "011"
}
An Assignment object defines:
- A
variablefrom the story world. - The
valueassigned to that variable, which is a Value object. - Whether this assignment is currently
visibleto the client, as a Boolean. All values are always visible to the game master, because the game master always has accurate knowledge of the current state of the story world. If the player cannot currently observe this assignment’s variable, then the value will be its last known value, which may not be its actual value. - A
descriptionas a short natural language sentence. - A
codestring, which is always composed of0s and1s and uniquely identifies the value assigned to the variable.
Constant Object
{
"type": "Constant",
"value": true
}
A Constant object defines:
- A
value, which represents a fixed value for this constant. Values includenull, the Boolean valuestrueandfalseand numbers. This key is missing ornullif the constant representsnull.
Ending Object
{
"id": 3,
"name": "bought(Coffee)",
"signature": # Signature object #,
"description": "The player purchased a coffee.",
"code": "100"
}
An Ending object defines:
- An
idnumber. All endings in a story world are numbered sequentially starting at 0. - A
name, which is the symbol used to refer to that ending. - A
signature, which is a Signature object. - A
descriptionas a short natural language phrase. - A
codestring, which is always composed of0s and1s and uniquely identifies the ending from other endings in the story world.
Entity Object
{
"type": "Entity",
"id": 1,
"name": "Barista",
"description": "the barista",
"code": "010"
}
An Entity object defines:
- An
idnumber. All entities in a story world are numbered sequentially starting at 0. - A
name, which is the symbol used to refer to that entity. - A
descriptionas a short natural language phrase. - A
codestring, which is always composed of0s and1s and uniquely identifies the entity from other values in the story world.
Signature Object
{
"name": "at",
"arguments": [ # Value objects # ]
}
A signature is a structure that defines a unique, parameterized object in a
story world. Variables, Actions, and
Endings have signatures. It defines:
- A
name, which is a relationship that applies to the signature’s arguments. - An array of
arguments, which are Value objects.
State Object
{
"assignments": [ # Assignment objects # ],
"description": "You are standing outside your favorite corner store. ...",
"code": "011100001000000"
}
A State object defines:
- An array of Assignment objects that give a value for each of the variables in a story world.
- A natural language
descriptionof the current state or what has changed since the previous state. - A
codestring, which is always composed of0s and1s and uniquely identifies the state from other possible states the story could be in.
Status Object
{
"role": "GAME_MASTER",
"history": [ # Turn objects # ],
"state": # State object #,
"ending": # Ending object #,
"descriptions": [ # Entity objects # ],
"choices": [ # Turn objects # ]
}
A Status object defines:
- The
rolethe client this object was sent to is playing in the story world. - The
historyof Turns taken so far in the story. - The current
stateof the story world. - The
endingof the story, if one has been reached. This will be missing or null if the story has not yet ended. - The
descriptionsof objects currently visible to the client. Descriptions are sent as Entity objects so they can be matched by their names and ID numbers, but thedescriptionkey will be a longer, more detailed description than the short phrase usually given to an entity. - The
choicescurrently available to the client, as an array of Turn objects. This array will be missing,null, or empty if it is not currently the client’s turn.
Turn Object
{
"role": "PLAYER",
"type": "PROPOSE",
"action": # Action object #,
"description": "The player offers some money to the barista.",
"code": "1000111"
}
A Turn object defines:
- The
rolewho took (or will take) this turn. - The
typeof action, which is eitherSUCCEED,FAIL,PROPOSEorPASS. - The
actionthat happens as part of this turn. This will be missing ornullif the type isPASS. - A
descriptionas a short natural language sentence. - A
codestring, which is always composed of0s and1s and uniquely identifies the turn from other possible turns.
There are four turn types:
SUCCEEDmeans the action occurs and is narrated.FAILmeans the action does not occur, but an attempt at the action is narrated.PROPOSEmeans the action requires the other client to agree to it. The other client will need to chooseSUCCEEDorFAIL.PASSmeans no action occurs and the client gives control of the story to its partner.
Value Objects
The following are considered Value objects:
Variable Object
{
"type": "Variable",
"id": 0,
"name": "at(Player)",
"signature": # Signature object #,
"encoding": "entity3",
"description": "the player's location"
}
A Variable object defines:
- An
idnumber. All variables in a story world are numbered sequentially starting at 0. - A
name, which is the symbol used to refer to that variable. - A
signature, which is a Signature object. - An
encoding, which defines the type of values that variable can have. - A
descriptionas a short natural language phrase.
World Object
{
"name": "tutorial",
"title": "Tutorial",
"description": "A simple story about buying a drink that will teach you how to play.",
"entities": [ # Entity objects # ],
"variables": [ # Variable objects # ],
"actions": [ # Action objects # ],
"endings": [ # Ending objects # ]
}
A story World object defines:
- The
name,title, anddescriptionof the story world as strings. - An array of Entity objects defining the objects that exist in the story world.
- An array of Variable objects defining the variables that make up the story world’s state.
- An array of Action objects defining the actions which can change the story world’s state.
- An array of Ending objects defining the possible endings that a story in this world can reach.