agent99 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eeb28a9ea8730c5ff33d5722f4dad0d0bcec6a54d58784203d1c147b64b17223
-  data.tar.gz: c27cb24f7ee720f758b94a32bd5d33e1ea5a92dc490022122cc40eaaa736620e
+  metadata.gz: e269eac0e8a38fef70f8db9d0487fb3b723d5b928350f396cb8eae852f446897
+  data.tar.gz: e13090c1235e35de5c8665d7a7f6e6f0aee3a9aae999b82b1d925bdc07efcb4c
 SHA512:
-  metadata.gz: dc796885c649aa669f77954eb25c5a9e8667d5aff6958054b53ca589fd3e620bb03ba3fce5a4b707bc6d2bd67ee2672291d1e4a0e0ff32b5d1d06912766492b0
-  data.tar.gz: f01c4e6d5a3353c722f87c965faaa6abede17ed57861a9b4fc82829e0c5a33d4bb483eb47420b9cef22bd697fb17d2e7e437bf9a2e5314fc07ab208bfb9d374d
+  metadata.gz: 3546e420df4bb94fa6ec09cbbc4b6e735b6ceebb937f9a6438d69b7fecdeea39fa38108620d9327ca6053218e303ed77284de02886f18dce367f4b6ecb10e588
+  data.tar.gz: 5fb72619e4321a2db1cfcee0d959cdd7206efb21eead25dba81381008c6d893eb39fbb6205857851f34275a01a421c1c193694c874e21a12b1876de0da2e1ce9

data/CHANGELOG.md

@@ -1,8 +1,25 @@
-## [Unreleased]
+# The Changelog
 
+## [Unreleased]
 
 ## Released
 
+### [0.0.3] - 2024-12-08
+
+- Document advanced features and update examples
+- Add AgentWatcher and ExampleAgent implementations
+- Update control actions documentation for Agent99
+- Add request flow diagram and update messaging docs
+- Update schema documentation for improved clarity
+- Reorganize documentation and update architecture details
+- Update API reference with detailed implementation guidelines
+- Extend agent lifecycle documentation
+- Enhance agent discovery documentation and registry logic
+- Add KaosSpy example agent
+- Update README links to lowercase for consistency
+- Add documentation for Agent99 framework
+- Add Sinatra dependency and document registry processes
+
 ### [0.0.2] - 2024-12-07
 
 - Added examples/control.rb

data/README.md

@@ -1,6 +1,6 @@
 # Agent99 Framework (AFW)
 
-**Under Development**  Initial release has no AI components - its just a generic client-server / request-response micro-services system using a peer-to-peer messaging broker and a centralized agent registry.
+**Under Development**  Initial release has no AI components - its just a generic client-server / request-response micro-services system using a peer-to-peer messaging broker and a centralized agent registry.  To keep up with the version changes review [The Changelog](./CHANGELOG.md) file.
 
 Agent99 is a Ruby-based framework for building and managing AI agents in a distributed system. It provides a robust foundation for creating intelligent agents that can communicate, discover each other, and perform various tasks.
 
@@ -55,6 +55,8 @@ Whether you’re a seasoned Ruby developer or just getting started, Agent99 prov
 - Registry Integration: Register and discover agents through a central registry
 - Error Handling and Logging: Built-in error management and logging capabilities
 - Control Actions: Pause, resume, update configuration, and request status of agents
+- Dynamic Agent Loading: Support for runtime loading and deployment of new agents
+- Multi-Agent Processing: Run multiple agents within the same process using thread isolation
 
 ## Installation
 
@@ -138,4 +140,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/MadBom
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/docs/README.md

@@ -0,0 +1,57 @@
+# Agent99 Framework Documentation
+
+Welcome to the Agent99 Framework documentation! Below is a table of contents and brief summaries of each markdown file available in this directory.  Explore each document for more detailed information on the Agent99 Framework and how to effectively utilize it in your projects!
+
+## Table of Contents
+
+1. **[Agent Discovery](agent_discovery.md)**
+      - This document explains how agents within the Agent99 framework discover each other based on their declared capabilities, including the registration and querying processes involved.
+
+2. **[Agent Lifecycle](agent_lifecycle.md)**
+      - Learn about the various stages an agent undergoes during its lifetime, from creation and initialization to running and graceful shutdown.
+
+3. **[Agent Registry Processes](agent_registry_processes.md)**
+      - This file details the processes handled by the Agent registry, including registration, discovery, and withdrawal of agents, along with example code to illustrate these concepts.
+
+4. **[API Reference](api_reference.md)**
+      - The API Reference provides comprehensive details about public methods and classes within Agent99, ensuring developers can leverage its full capabilities.
+
+5. **[Architecture Overview](architecture_overview.md)**
+      - An overview of the architecture of Agent99, describing its microservices-oriented structure, communication workflows, and how agents operate within the system.
+
+6. **[Configuration](configuration.md)**
+      - Discover how to configure agents using environment variables, including important settings such as the registry base URL.
+
+7. **[Control Actions](control_actions.md)**
+      - This document lists the control actions available to agents, such as shutdown, pause, and resume, along with instructions on how to create custom actions.
+
+8. **[Custom Agent Implementation](custom_agent_implementation.md)**
+      - Guidelines on creating custom agents, including subclassing, defining schemas, and implementing request and response handling.
+
+9. **[Error Handling and Logging](error_handling_and_logging.md)**
+      - Understanding the error handling mechanisms in Agent99, as well as how to configure logging for better monitoring and debugging.
+
+10. **[Extending the Framework](extending_the_framework.md)**
+      - Instructions on how to extend Agent99 by implementing custom modules, defining new message types, and using hooks for additional functionality.
+
+11. **[Message Processing](message_processing.md)**
+      - This document outlines the different message types supported by Agent99, how they are processed, and the importance of schema validation.
+
+12. **[Messaging Systems](messaging_systems.md)**
+      - Overview of the messaging protocols supported by Agent99, including AMQP and NATS, and guidance on how to switch between them.
+
+13. **[Advanced Features](advanced_features.md)**
+      - Learn about dynamic agent loading, multi-agent processing, and best practices for running multiple agents within the same process.
+
+14. **[Performance Considerations](performance_considerations.md)**
+      - Best practices for ensuring optimal performance within the framework, including optimization techniques and profiling performance.
+
+15. **[Schema Definition](schema_definition.md)**
+      - Detailed instructions on how to define schemas using `SimpleJsonSchemaBuilder`, with examples to guide you through the process.
+
+16. **[Security](security.md)**
+      - Recommendations on implementing security measures within Agent99, focusing on message encryption and access control.
+
+17. **[Troubleshooting](troubleshooting.md)**
+      - Common issues encountered while using Agent99 and suggested steps for debugging, including examining logs and configuration settings.
+

data/docs/advanced_features.md

@@ -0,0 +1,110 @@
+# Agent99 Framework
+
+## Advanced Features
+
+Ruby supports dynamic loading and deployment of libraries at runtime.  Agent99 takes advantage of this ability through the `AgentWatcher` system. This powerful feature allows you to:
+
+- Monitor a directory for new agent files
+- Automatically load and instantiate new agents when detected
+- Run multiple agents within the same process
+- Manage agent lifecycle independently
+
+### Using AgentWatcher
+
+The `AgentWatcher` (found in `examples/agent_watcher.rb`) provides a framework for dynamically loading and running agents:
+
+1. Start the AgentWatcher:
+```ruby
+watcher = AgentWatcher.new
+watcher.run
+```
+
+2. Deploy new agents by copying their .rb files to the watched directory (default: './agents'):
+```bash
+cp my_new_agent.rb agents/
+```
+
+The AgentWatcher will:
+- Detect the new file
+- Load the agent class
+- Instantiate the agent
+- Run it in a separate thread
+
+### Example Implementation
+
+```ruby
+class MyDynamicAgent < Agent99::Base
+  TYPE = :server
+  
+  def capabilities = ['my_capability']
+  
+  def receive_request
+    # Handle requests
+    send_response(status: 'success')
+  end
+end
+```
+
+## Multi-Agent Processing
+
+Agent99 supports running multiple agents within the same process, with each agent running in its own thread. This approach:
+
+- Reduces resource overhead compared to separate processes
+- Maintains isolation between agents
+- Allows efficient inter-agent communication
+- Simplifies agent management
+
+### Benefits
+
+1. **Resource Efficiency**: Share common resources while maintaining agent isolation
+2. **Simplified Deployment**: Manage multiple agents through a single process
+3. **Enhanced Communication**: Direct inter-agent communication within the same process
+4. **Centralized Management**: Monitor and control multiple agents from a single point
+
+### Implementation Considerations
+
+When running multiple agents in the same process:
+
+1. Each agent runs in its own thread for isolation
+2. Agents can still communicate through the standard messaging system
+3. Errors in one agent won't affect others
+4. Resource sharing is handled automatically by the framework
+
+### Example Setup
+
+Using AgentWatcher to manage multiple agents:
+
+```ruby
+# Start the watcher
+watcher = AgentWatcher.new
+watcher.run
+
+# Deploy multiple agents
+cp agent1.rb agents/
+cp agent2.rb agents/
+cp agent3.rb agents/
+```
+
+Each agent will run independently in its own thread while sharing the same process space.
+
+## Best Practices
+
+1. **Error Handling**
+    - Implement proper error handling in each agent
+    - Use the built-in logging system
+    - Monitor agent health through status checks
+
+2. **Resource Management**
+    - Monitor memory usage when running many agents
+    - Implement proper cleanup in the `fini` method
+    - Use appropriate thread pool sizes
+
+3. **Deployment**
+    - Use meaningful file names for easy identification
+    - Maintain clear separation of concerns between agents
+    - Document agent dependencies and requirements
+
+4. **Monitoring**
+    - Implement health checks in your agents
+    - Use logging for debugging and monitoring
+    - Set up appropriate alerting for critical agents

data/docs/agent_discovery.md

@@ -0,0 +1,62 @@
+# Agent99 Framework
+
+## Agent Discovery
+
+Agents within the Agent99 Framework can efficiently discover one another based on their declared capabilities. This feature fosters dynamic interactions that enhance the collaborative functionality of the agents.
+
+### Overview
+
+The agent discovery process involves the following steps:
+
+1. **Registration**: Agents register their capabilities with a central registry upon startup.
+2. **Discovery**: When an agent needs to discover other agents, it queries the registry for agents with specific capabilities.
+3. **Response**: The registry responds with a list of available agents, allowing them to interact based on their capabilities.
+
+### Declaring Capabilities
+
+Each agent must implement the `capabilities` method to declare its capabilities as an array of strings:
+
+```ruby
+def capabilities
+  ['process_image', 'face_detection']
+end
+```
+
+**Note**: The discovery mechanism is based on an exact match (case insensitive) between the requested capability and the entries in the agent's capabilities array. For example, if an agent declares its capabilities as mentioned above, a discovery request for `'FACE_DETECTION'` will successfully match.
+
+### Discovery API
+
+To find other agents, use the `discover_agent` method. Here are some usage examples:
+
+```ruby
+# Find a single agent with a specific capability
+agent = discover_agent(capability: 'face_detection')
+
+# Find multiple agents 
+agents = discover_agent(capability: 'process_image', how_many: 3)
+
+# Find all agents with a specific capability
+all_agents = discover_agent(capability: 'process_image', all: true)
+```
+
+### Important Note on Capabilities
+
+- **Single Capability**: A seeking agent can only request one kind of capability at a time.
+- **Semantics-Based Capabilities**: The development roadmap includes enhancements towards semantic-based capabilities that could allow for more complex interactions between agents in the future.  This would be a change from the current Array of Strings to a single String that is a description of the services the agent provides.  This would be consistent with the way in which LLMs currently find Tools for augmented generation.
+
+### Registry Configuration
+
+The registry client comes with default settings, which you can override as needed:
+
+- **URL**: Default is `http://localhost:4567` (you can override this using the `REGISTRY_BASE_URL` environment variable).
+- **Interface**: Supports a standard HTTP REST interface.
+- **Reconnection**: Automatic reconnection handling is provided to ensure reliable communication.
+
+### Best Practices
+
+1. **Check Discovery Success**: Always verify if agent discovery succeeded before attempting to establish communication with the discovered agent.
+2. **Use Specific Capability Names**: This ensures that the correct agents are matched during the discovery process, avoiding ambiguity.
+3. **Implement Multiple Capabilities**: Consider declaring multiple capabilities per agent to enhance its versatility and improve interaction possibilities.
+
+With these guidelines, you can effectively implement and utilize the agent discovery feature within the Agent99 Framework, ensuring robust and dynamic interactions among agents based on their declared capabilities.
+

data/docs/agent_lifecycle.md

@@ -0,0 +1,137 @@
+# Agent99 Framework
+
+## Agent Lifecycle
+
+The lifecycle of an agent within Agent99 consists of several key stages that are managed through dedicated lifecycle methods. Understanding these stages and their corresponding methods is crucial for proper agent implementation.
+
+### Lifecycle Stages
+
+1. **Creation**: An agent is instantiated through the `Agent99::Base` class.
+2. **Initialization**: The agent sets up resources and establishes connections.
+3. **Running**: The agent processes messages and performs its designated tasks.
+4. **Shutdown**: The agent performs cleanup and gracefully terminates.
+
+### Core Lifecycle Methods
+
+#### The `init` Method
+
+The `init` method is called automatically after the agent has been registered but before it starts processing messages. Its primary purpose is to perform any additional setup required for the agent following the default initialization provided by the `Agent99::Base` class. This may include:
+
+- Setting up initial state
+- Establishing connections to other agents or resources
+- Discovering dependencies or agents to communicate with
+- Sending initial messages to specific agents
+
+Here’s an example implementation:
+
+```ruby
+def init  
+  @state      = initialize_state
+  @resources  = setup_resources
+end
+```
+
+#### Custom Initialization
+
+Agents can choose to either use the default behavior provided by the `Agent99::Base` class or implement their own `initialize` method to customize the `logger`, `message_client`, and `registry_client` attributes. For instance:
+
+1. **Using Defaults**: If you do not define an `initialize` method in your agent class, it will inherit the defaults:
+
+```ruby
+class MyAgent < Agent99::Base
+  # Inherits default logger, message_client, and registry_client
+end
+```
+
+2. **Customizing Initialization**: If you need custom initialization, you can ignore the `init` method and override the `initialize` method:
+
+```ruby
+class MyCustomAgent < Agent99::Base
+  def initialize(
+      registry_client:  CustomRegistryClient.new,
+      message_client:   CustomMessageClient.new,
+      logger:           Logger.new('custom_agent.log')
+    )
+    super  # Registers the Agent and setups its message queue
+
+    # Additional state or resource initialization required
+    # by the new agent
+  end
+end
+```
+
+In this case, the custom agent not need the `init` method to perform any additional setup.
+
+#### The `fini` Method
+
+The `fini` method is setup to be invoked when the `exit` method is called within `initialize` method by the `on_exit { fini }` hook.
+
+The `fini` method ensures proper cleanup during agent shutdown:
+
+The default `fini` method does:
+- Withdrawing from the registry
+- Closing message queue connections
+
+If your agent requires additional cleanup or state presistence you should implement a custom `fini` method to do things like:
+- Cleaning up resources
+- Saving state (if required)
+- Releasing system resources
+
+Example implementation:
+
+```ruby
+def fini
+  save_state if @state
+  cleanup_resources
+  deregister_from_registry
+  
+  super  # Always call super last for proper framework cleanup
+end
+```
+
+### Best Practices
+
+1. **Proper Method Ordering**:
+   - Always call `super` first in `initialize`.
+   - Always call `super` last in `fini`.
+   - This order ensures proper framework initialization and cleanup.
+
+2. **Resource Management**:
+   - Initialize all resources in `init` or `initialize`.
+   - Clean up all resources in `fini`.
+   - Handle cleanup idempotently.
+
+3. **Error Handling**:
+   - Implement robust error handling in all methods.
+   - Ensure `fini` can handle partial initialization states.
+   - Log all significant lifecycle events.
+
+4. **State Management**:
+   - Initialize state clearly.
+   - Save or cleanup state properly in `fini`.
+   - Consider persistence needs.
+
+### Important Considerations
+
+- Agents can be implemented as stand-alone processes.
+- When an agent is implemented within the context of a larger application process, the agent should be "run" within its own thread.
+    ```ruby
+    begin
+      my_agent = MyAgent.new
+      Thread.new { my_agent.run }
+    end
+    ```
+- Agents handle only one request message at a time.
+- The `fini` method is called automatically during graceful shutdowns.
+
+### Framework Integration
+
+The Agent99 framework automatically manages the lifecycle of agents:
+
+1. Calls `init` (if present) after agent creation.
+2. Monitors agent health during operation.
+3. Calls `fini` during shutdown (`on_exit {fini}`).
+4. Handles cleanup if initialization fails.
+
+This automated lifecycle management ensures reliable agent operation within the framework.
+

data/docs/agent_registry_processes.md

@@ -0,0 +1,102 @@
+# Agent99 Framework
+
+## Agent Registry Processes
+
+In the Agent99 framework, an instance of the `Agent99::RegistryClient` class is responsible for registering agent capabilities with a centralized registry.  `examples/registry.rb` is a Sinatra web-app example of what a centralized regristry service should be. 
+
+The registration process is transparent to a new instance of an `Agent99::Base` class.
+
+First thing: start the registry.rb Sinatra app and the peer-to-peer messaging network.  The default is the `AmqpMessageClient` class.
+
+If you do not have the RabbitMQ server installed on your Macthen then grab it using `brew install rabbitmq-server` and while you are installing software do `brew install boxes` as well since the `chief_agent.rb` example uses that little CLI tool to highlight some text in the terminal.
+
+```bash
+git clone ssh://git@github.com/MadBomber/agent99
+brew install rabbitmq-server boxes
+gem install agent99
+
+cd agent99/examples
+./start_rabbitmq_and_registry.sh
+```
+
+Now go into `irb` in a different terminal window and try this code ...
+
+```ruby
+require 'agent99'
+
+# Define the Schema for the Agent's request payload
+
+class MyAgentRequest < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+
+    string :greeting, required: false,  examples: ["Hello"]
+    string :name,     required: true,   examples: ["World"]
+  end
+end
+
+# Define the new Agent ....
+
+class MyAgent < Agent99::Base
+  REQUEST_SCHEMA    = MyAgentRequest.schema
+  def capabilities  = %w[ greeter hello_world ]
+end
+
+# You may create multiple instances of the agent if needed
+
+my_agent = MyAgent.new
+
+I, [2024-12-07T14:42:08.140286 #36471]  INFO -- : Registered Agent MyAgent with ID: 9e735449-582f-46e2-8f11-371e584d0f08
+I, [2024-12-07T14:42:08.141978 #36471]  INFO -- : Created queue for agent_id: 9e735449-582f-46e2-8f11-371e584d0f08
+  #=>
+#<MyAgent:0x000000011d4d2e48
+...
+
+# The agent as an ID and an address in the peer-to-peer network
+
+my_agent.id
+  #=> "9e735449-582f-46e2-8f11-371e584d0f08"
+```
+
+The image below shows how the `Agent99::Base` class uses dependency injection in its constructor method to bring in an instance of the `RegristryClient` class to provide an interface to the centralized regristery service.
+
+![Agent Register, Discover and Withdraw Processes](diagrams/agent_registry_processes.png)
+
+The above image also show the other services provided via the RegistryClient class.
+
+The example centralized regristry service provides three processes:
+
+1. Registration Process:
+     - MyAgent initializes the RegistryClient
+     - RegistryClient sends a POST request to the Central Registry
+     - Central Registry responds with a UUID
+     - RegistryClient returns the UUID to MyAgent
+2. Discovery Process:
+     - MyAgent requests discovery of agents with a specific capability
+     - RegistryClient sends a GET request to the Central Registry
+     - Central Registry responds with matching agents
+     - RegistryClient returns the matching agents to MyAgent
+3. Withdrawal Process:
+     - MyAgent requests withdrawal using its UUID
+     - RegistryClient sends a DELETE request to the Central Registry
+     - Central Registry responds with a 204 No Content
+     - RegistryClient confirms the withdrawal to MyAgent
+
+Like the register process, the withdraw process is also transparent.  Its executed on any exit via the public method `fini` in the base class' `on_exit {...}` handler.  Calling `exit` for any reason within your agent class will withdraw it from the central registry and remove its message queue from peer-to-peer messaging network.
+
+The discover process is primary business logic for your agent class.  You must call the `@registry_client.discover(capability: "whatever")` method directly within the agents process.
+
+For example suppose your agent needs to work with other agents that provide the "pne", "twp" and "three" services.  That is 3 outside agents.  You can do this in the `init` method for you agent.
+
+```ruby
+class MyAgent < Agent99::Base
+  def init
+    @agnet_1 = discover_agent(capability: 'one')
+    @agnet_2 = discover_agent(capability: 'two')
+    @agnet_3 = discover_agent(capability: 'three')
+  end
+end
+```
+
+`discover_agent` is the `Agent99::Base` method that links to the registry client's instance to do the discovery via the central registry.  Other parameters to `discover_agent` allow's you agent to specify `how_many` agents having the specify capability you want returned.  The default is 1.  If you want all the agents capable of providing the requested service use the `all: true` parameter with the `discover_agent` method.
+

data/docs/api_reference.md

@@ -0,0 +1,136 @@
+# Agent99 Framework API Reference
+
+## Agent Implementation Requirements
+
+When creating a new agent by subclassing `Agent99::Base`, you must implement certain methods and may optionally override others.
+
+### Required Methods
+
+#### `capabilities`
+Returns an array of strings describing the agent's capabilities.
+```ruby
+def capabilities
+  ['process_image', 'face_detection']
+end
+```
+
+#### `receive_request`
+Handles incoming request messages. Must be implemented if the agent accepts requests.
+```ruby
+def receive_request
+  # Process the request message in @payload
+  # Access message data via @payload[:data]
+  # Send response using send_response(response_data)
+end
+```
+
+### Optional Methods
+
+#### `init`
+Called after registration but before message processing begins. Use for additional setup.
+```ruby
+def init
+  @state = initialize_state
+  @resources = setup_resources
+end
+```
+
+#### `fini`
+Called during shutdown. Override to add custom cleanup.
+```ruby
+def fini
+  cleanup_resources
+  save_state if @state
+  super  # Always call super last
+end
+```
+
+#### `receive_response`
+Handles incoming response messages. Override if the agent processes responses.
+```ruby
+def receive_response
+  # Process the response message in @payload
+end
+```
+
+## Message Client Interface
+
+To implement a custom message client, create a class that implements these methods:
+
+### Required Methods
+
+#### `initialize(logger: Logger.new($stdout))`
+Sets up the messaging connection.
+
+#### `setup(agent_id:, logger:)`
+Initializes message queues/topics for the agent.
+- Returns: queue/topic identifier
+
+#### `listen_for_messages(queue, request_handler:, response_handler:, control_handler:)`
+Starts listening for messages.
+- `queue`: Queue/topic to listen on
+- `request_handler`: Lambda for handling requests
+- `response_handler`: Lambda for handling responses
+- `control_handler`: Lambda for handling control messages
+
+#### `publish(message)`
+Publishes a message.
+- `message`: Hash containing the message with :header and payload
+- Returns: Hash with :success and optional :error
+
+#### `delete_queue(queue_name)`
+Cleans up agent's message queue/topic.
+
+## Registry Client Interface
+
+To implement a custom registry client, create a class that implements these methods:
+
+### Required Methods
+
+#### `initialize(base_url: ENV.fetch('REGISTRY_BASE_URL', 'http://localhost:4567'), logger: Logger.new($stdout))`
+Sets up the registry connection.
+
+#### `register(name:, capabilities:)`
+Registers an agent with the registry.
+- Returns: UUID string for the agent
+
+#### `withdraw(id)`
+Removes an agent from the registry.
+
+## Base Class Public Methods
+
+The `Agent99::Base` class provides these public methods:
+
+#### `run`
+Starts the agent's message processing loop.
+
+#### `discover_agent(capability:, how_many: 1, all: false)`
+Finds other agents by capability.
+- Returns: Array of agent information hashes
+
+#### `send_response(response)`
+Sends a response message.
+- `response`: Hash containing the response data
+
+## Message Types
+
+Messages in Agent99 must include a `:header` with:
+- `:type`: One of "request", "response", or "control"
+- `:to_uuid`: Destination agent's UUID
+- `:from_uuid`: Sending agent's UUID
+- `:event_uuid`: UUID to link request to response
+- `:timestamp`: Integer (`Agent99::Timestamp.new.to_i`)
+
+Example request message structure:
+```ruby
+{
+  header: {
+    type:       'request',
+    to_uuid:    ,
+    from_uuid:  ,
+    event_uuid: ,
+    timestamp:  ,
+  },
+  # agent specific parameters
+}
+```