client

core Go API

[TOC]

The Go implementation of the agent API should be considered the "reference" implementation. Our other implementations (python) seek to implement the same user-facing interfaces and pattern with language-specific concessions as needed.

The Agent API

Quick Summary

Derive your agent from a *client.BasicAgent, and fulfill the ManagedAgent interface.

type MyAgent struct {
  *client.BasicAgent
}

func (m *MyAgent) Setup() error {
  // Implement your agent setup here
  // Make any calls to ListenFor here
  return nil
}

func (m *MyAgent) Loop() (bool, error) {
  // Implement your agent's data processing here
  return true, nil //return true if you want to continue looping
  //return false, nil //return false if you want to stop loop
}

// Essential agent API for BB communication
func (a *MyAgent) Post(metadata []byte, data []byte, tags string...) error
func (a *MyAgent) Reply(post *client.Post, metadata []byte, data []byte, tags string...) error
func (a *MyAgent) ListenFor(tags...) <-chan *Post
func (a *MyAgent) Log(severity core.Log_Severity, msg string)

// Additional API provided by BasicAgent
func (a *MyAgent) Trace(post *client.Post) ([]*client.Post, error)

// Run your agent (must fulfill the managed agent interface)
my_agent := &MyAgent{
  BasicAgent: client.GetDefaultAgent(blackboard_address)
}
err := client.RunUntilComplete(my_agent)
if err != nil {
  log.Fatal(err)
}

Detailed Explanation

Importing the client package

We suggest the following for importing the client package:

import client "gitlab.com/hoffman-lab/core/cmd/client-apis/go"`

The BasicAgent type

To make an agent, embed a pointer to a BasicAgent into your structure.

type MyAgent struct {
  *client.BasicAgent
}

BasicAgent provides the essential components for an agent including but not limited to posting, replying, and receiving data from the blackboard. You are not required to utilize BasicAgent to communicate with the blackboard however we cannot provide support at this point for those more advanced use cases.

Agent lifecycle

BasicAgent actually runs several processes concurrently, which can leave dangling goroutines and unfreed memory if we're not careful. As a result, we have implemented an agent lifecycle that can handle this cleanup for you.

To utilize the lifecycle, you must implement two functions.

These allow your agent to fulfill the ManagedAgent interface.

func (a *MyAgent) Setup() error {
  return nil
}

func (a *MyAgent) Loop() (bool, error) {
  return true, nil
}

(This pattern is inspired by the Arduino lifecycle)

Setup is executed once, prior to any communication with the blackboard. Do not call any blackboard communication methods inside of setup. Although they will succeed, this interferes with proper message delivery using the ListenFor method we provide.

Any agent initialization you'd like to perform prior to communicating with the blackboard should be performed here. Additionally, any calls to ListenFor should be made in Setup.

Returning an error from Setup will prevent the agent from starting.

Loop will be executed infinitely many times until it is told to stop by returning false. Persistence can be achieved by always returning true. Returning an error in the second return parameter from a Loop does not itself cause the agent to stop executing.

Inside of the loop is where your agent should listen for messages, process data, and communicate with the blackboard.

An agent that has properly implemented a Setup and Loop method can then be managed using the RunUntilComplete function.

my_agent := &MyAgent{
  BasicAgent: client.GetDefaultAgent(bb_address),
}
err := client.RunUntilComplete(my_agent)
if err != nil {
  log.Fatal("agent returned error:", err)
}

The GetDefaultAgent function returns a properly initialized BasicAgent ready to connect to the blackboard running at bb_address.

Blackboard Communication

The core agent API is fundamentally three methods: Post, Reply, and ListenFor. These three methods provide all key functionality for multiagent systems.

Analogous to a real blackboard, post just means "put something on the blackboard".

tags := []string{"test-message"}
err := my_agent.Post([]byte("some metadata"), []byte("some data data"), tags...)

This version of core changes how messages are exchanged between agents.

We have ultimately done away with attributes and promises in favor of a tagging system.

Agents post their messages with a set of tags and other agents listen for a set of tags. Each matching message will surface into the appropriate ListenFor channel. (There are deep and obvious similarities here to traditional pub/sub architectures)

Messages will match if the incoming message contains at least the tags provided to ListenFor. E.g.,

ListenFor("test") matches Post(md, d, "test")
ListenFor("test") also matches Post(md, d, "test", "tag2")

ListenFor("test", "tag2") matches Post(md, d, "test", "tag2")
ListenFor("test", "tag2") does **not** match Post(md, d, "test")

This means that without care in tagging there can easily be agent "cross talk" particularly with multiple agents performing the same or similar tasks. This is intentional and by design and places a great deal of control and flexibility in the hands of the user although new users may find it challenging. Please utilize our issues page for feedback and assistance with the new tagging system if it is unclear, or some additional instruction, guidance, or debugging help is required.

Many agents will want to receive some data from the blackboard to begin executing. ListenFor will provide you with a go channel on which messages with matching tags will arrive. These can then be utilized as normal go channels to automatically receive data from the blackboard.

IMPORTANT: To ensure proper behavior, ListenFor must be called in Setup, before any messages have been sent to the blackboard.

Here is an example from our ping pong agents:

type PingAgent2 struct {
	prime_bb sync.Once // bootstraps the ping/pong routine by sending a ping message once
	pong_ch  <-chan *client.Post
	*client.BasicAgent
}

func (a *PingAgent2) Setup() error {
	a.pong_ch = a.ListenFor([]string{"pong-message"})
	return a.sendPing()
}

func (a *PingAgent2) Loop() (cont bool, err error) {
	select {
	case post := <-a.pong_ch:

		// channel has been closed externally
		if post == nil {
			return false, nil
		}

		if err := a.sendPing(); err != nil {
			return false, err
		}
	case <-time.After(10 * time.Second):
		a.Log(core.Log_Info, "ping agent heartbeat")
	}
	return true, nil
}

ListenFor returns a Post object. The post has metadata and data that can be used as desired, but importantly, the post object can be used to begin a "chain" of posts using the reply mechanism. A reply actually just shows up on the blackboard as a post, but you'll notice that it has one or more messages listed in the "replying_to" field. It also creates very logical and light links between messages on the blackboard that enable techniques such as tracing.

Here is an example from our Pong agent:

// Pong listens for Pings and replies with pongs
func (a *PongAgent) Loop() (cont bool, err error) {
	select {
	case post := <-a.ping_ch:

		if post == nil {
			return false, nil
		}

		time.Sleep(a.delay_ms)
		err := a.Reply([]*client.Post{post}, nil, nil, "pong-message")
		if err != nil {
			return false, err
		}
	case <-time.After(10 * time.Second):
		a.Log(core.Log_Info, "pong agent heartbeat")
	}

	return true, nil
}

func (a *BasicAgent) Trace(post *Post) ([]*Post, error) {

Tracing in a core blackboard allows an agent to retrieve messages via a chain of replies; effectively, we walk the "linked list" of messages and give them back to the tracer.

Here is an example from our (TODO) agent:

// TODO: this is an agent example that we should implement!

Tracing is not part of the core agent interface, however is a special feature of the core base agent.

NOTE: Tracing is a method that exists slightly outside of the core agent API and is a service provided by the core blackboard (some of the secret sauce of our implementation we hope). In fact, although we have placed it into Blackboard interface, certain blackboards implementations may wish to not provide or return useful tracing information.

Logging is, strictly speaking, not a necessary part of the core protocol, however logging is so ubiquitously useful during development, execution, and monitoring that we'd be hard pressed not to include it. Defining this message type allows us to separate messages meant for agents (posts) which may or may not be human readable, from posts that should be human-readable (logs).

func (a *BasicAgent) Log(severity core.LogSeverity, message string) ([]*Post, error) {

The default severity everyone should use is core.Log_Info. This is a bread and butter log message.

We encourage the following guidelines for the other severities:

core.Log_Debug:    should not appear during normal logging
core.Log_Info:     normal logging
core.Log_Warning:  possible with errors, but can continue
core.Log_Error:    normal operation is not occuring
core.Log_Critical: 🔥🔥🔥 (possibly trigger a halt and catch fire?)

If using the managed lifecycle, you don't need to worry about sending Hello and Goodbye messages. If you're implementing a more "raw" agent, these messages indicate an agent's first and last connection to the blackboard, and are one way to trigger the concurrent loops necessary to handle message delivery.

We recommend using the managed lifecycle, unless you've got a lot of time to debug.

If you're dead set on skipping the lifecycle, check out agent_pipe.go for an example of how you can do the management yourself.

Examples

We have implemented and will continue to add agents to the agents directory. These are excellent references for how we have implemented and understand our own API.

We recommend your start with looking at our ping pong agents: ping.go, pong.go

These can be executed against a blackboard using

core start server # start the blackboard
core start ping   # start the ping agent
core start pong   # start the pong agent

More advanced examples can be found in the network benchmark, and agent_pipe.go

Please check out the "basic agent" implementation if you need manage agent behavior using even lower-level API elements (out of scope for this documentation).