agent99 0.0.2 → 0.0.4

data/docs/schema_definition.md

@@ -0,0 +1,78 @@
+# Agent99 Framework
+
+## Schema Definition
+
+Agent99 uses `SimpleJsonSchemaBuilder` for defining message schemas. This gem was chosen for its Ruby-like DSL that makes schema definitions readable and maintainable, while still producing JSON Schema compatible output.
+
+### Header Schema
+
+All messages in Agent99 must include a header that conforms to this schema:
+
+```ruby
+class Agent99::HeaderSchema < SimpleJsonSchemaBuilder::Base
+  object do
+    string :type,       required: true, 
+                          enum: %w[request response control]
+    string  :to_uuid,   required: true
+    string  :from_uuid, required: true
+    string  :event_uuid,required: true
+    integer :timestamp, required: true
+  end
+end
+```
+
+### Request Schema Example
+
+Define your agent's request schema by inheriting from SimpleJsonSchemaBuilder::Base:
+
+```ruby
+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
+```
+
+In this example, the agent has two parameters that it uses from the request message: greeting and name; however, greeting is not required.  **The Agent99 framework will use the first item in the examples array as a default for optional parameters.**
+
+### Automatic Schema Validation
+
+Agent99 automatically validates incoming request messages against your agent's REQUEST_SCHEMA:
+
+1. When a request arrives, the framework checks if your agent class defines REQUEST_SCHEMA
+2. If defined, the message is validated before reaching your receive_request method
+3. If validation fails:
+   - An error response is automatically sent back to the requester
+   - Your receive_request method is not called
+   - The validation errors are logged
+
+Example validation error response:
+
+```ruby
+{
+  header: {
+    type:       'error',
+    to_uuid:    original_from_uuid,
+    from_uuid:  agent_id,
+    event_uuid: original_event_uuid,
+    timestamp:  current_timestamp
+  },
+  errors: ['Required property "name" not found in request']
+}
+```
+
+### Why SimpleJsonSchemaBuilder?
+
+SimpleJsonSchemaBuilder was chosen for Agent99 because it:
+
+1. Provides a Ruby-native DSL for schema definition
+2. Generates standard JSON Schema output
+3. Supports schema composition and reuse
+4. Includes built-in validation
+5. Has excellent performance characteristics
+6. Maintains type safety through static analysis
+
+The gem allows us to define schemas that are both human-readable and machine-validatable, while staying within the Ruby ecosystem.
+

data/docs/security.md

@@ -0,0 +1,9 @@
+# Agent99 Framework
+
+## Security
+
+While Agent99 focuses on communication efficiency, it is recommended to implement security measures like:
+
+- Encrypting messages in transit.
+- Using secure protocols for messaging (e.g., AMQPS or NATS with TLS).
+- Implementing access control mechanisms for sensitive operations.

data/docs/troubleshooting.md

@@ -0,0 +1,11 @@
+# Agent99 Framework
+
+## Troubleshooting
+
+Common issues may include:
+
+- Failed registrations: Ensure that your registry URL is correctly configured.
+- Message routing issues: Verify routing keys and message schemata.
+- Unhandled exceptions: Check logs for details.
+
+For effective debugging, use the logging facilities provided and monitor agent activities.

data/docs/what_is_an_agent.md

@@ -0,0 +1,293 @@
+# What is an Agent?
+
+An agent is a self-contained piece of code designed to perform a specific function or service. Unlike general-purpose classes or modules, agents can be autonomous entities that focus on doing one thing well. They embody the Single Responsibility Principle (SRP) by design.
+
+I will be using the Ruby programming language and the agent99 gem specifically to illustrate aspects of what I think good software agents should look like.  I choose Ruby because:
+
+- Ruby allows developers to create elegant and expressive AI applications.
+- It promotes paradigm shifts, challenging the Python status quo in AI development.
+- Developers who value clarity can find their niche in Ruby's design.
+- Ruby's metaprogramming capabilities pave the way for creative AI solutions.
+- Greater integration of Ruby-based frameworks makes them viable choices in the AI landscape.
+- Ruby's object-oriented style leads to more modular and testable code.
+- Ruby inspires a community that often prefers its syntax over Python's.
+
+## Getting Started with Agent99
+
+The `agent99` is a Ruby gem that serves as a framework for developing and managing software agents, allowing for the execution and communication of these agents in a distributed environment. It implements a reference protocol that supports agent registration, discovery, and messaging through a centralized registry and a messaging system like AMQP or NATS. Each agent, derived from the `Agent99::Base` class, is designed to perform specific tasks as defined by its capabilities, adhering to the Single Responsibility Principle (SRP) for enhanced maintainability and testability. The framework facilitates modular agent interactions, enabling developers to build innovative applications while taking advantage of Ruby’s expressive syntax and metaprogramming features. The library emphasizes best practices in software design, including error handling and lifecycle management for robust agent operations.
+
+To install the Agent99 gem, simply run:
+
+```bash
+gem install agent99
+```
+
+The [documentation](https://github.com/MadBomber/agent99/blob/main/docs/README.md) provides a comprehensive overview of the framework, but here, we will explore definitions of software agents and the Single Responsibility Principle (SRP), along with how Agent99 distinguishes itself in agent management and description.
+
+## What Is a Reference Implementation?
+
+The Agent99 gem implements a protocol in Ruby that can be replicated in other programming languages. This interoperability allows software agents, given they support the Agent99 protocol, to mix and match regardless of the language they were built in.
+
+## Understanding Software Agents and the Single Responsibility Principle
+
+Software agents and the Single Responsibility Principle (SRP) are crucial in contemporary software development. They decompose complex systems into manageable, autonomous components, while SRP promotes the creation of maintainable, testable, and adaptable systems. Utilizing both can boost code quality and nurture agility in development teams, particularly in AI, automation, and microservices contexts.
+
+## What Are Software Agents?
+
+In simple terms, a software agent is a designated piece of code that performs a single function effectively. Within the Agent99 framework, agents are instances of subclasses derived from the **Agent99::Base** class. These instances can be running in their own separate process or groups of instances of different Agent99 instances can run within separate Threads in a single process.
+
+Here's a simple example of an Agent99 agent class running in an independent process:
+
+```ruby
+# File: example_agent.rb
+
+require 'agent99'
+
+class ExampleAgent < Agent99::Base
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :server,
+      capabilities:     %w[ rubber_stamp yes_man example ],
+      # request_schema:   {}, # ExampleRequest.schema,
+      # response_schema:  {}, # Agent99::RESPONSE.schema
+      # control_schema:   {}, # Agent99::CONTROL.schema
+      # error_schema:     {}, # Agent99::ERROR.schema
+    }
+  end  
+
+  def receive_request
+    logger.info "Example agent received request: #{payload}"
+    send_response(status: 'success')
+  end
+end
+
+ExampleAgent.new.run
+```
+
+```base
+ruby example_agent.rb
+```
+
+Each agent subclass is responsible for specific methods that define its unique capabilities and how it handles requests.  The `info` method provides a comprehensive information packet about the agent. It returns a hash containing key details that are crucial for agent registration and discovery within the system.  The **:capabilities** entry in the `info` packet in an Array of Strings - synonyms - for the thing that the agent does.
+
+For a server type agent, the only methods that are required to be defined, as in the ExampleAgent class above, are its **info** and its **receive_request** methods. Everything else from initialization, registration, message dispatching, and graceful shutdown are handled by the default methods within the **Agent99::Base** class.
+
+More complex agents will require methods like **receive_response** and **receive_control** and potentially custom implementations of **init**, **initialize**, or **fini** may be necessary for managing state or resources.
+
+> **RoadMap:** Currently, the Agent99 implementation defines the **capabilities** value as an `Array(String)`, with plans to enhance this functionality into descriptive unstructured text akin to defining tools for functional callbacks in LLM processing using semantic search.
+
+## The Single Responsibility Principle (SRP)
+
+The Single Responsibility Principle, part of the SOLID principles of object-oriented design, asserts that a class or module should have only one reason to change. This means it should fulfill a single job or responsibility effectively.
+
+### Why SRP Matters
+
+1. **Maintainability:** Code is easier to read and modify, leading to more maintainable systems.
+2. **Testability:** Isolated responsibilities facilitate independent unit testing.
+3. **Flexibility:** Minimal impact on other parts of the system when modifying one responsibility, reducing the risk of bugs.
+
+### Applying SRP in Software Development
+
+Implementing SRP involves:
+
+- **Identifying Responsibilities:** Break down functionalities into specific tasks; each class or module should focus on a particular duty.
+- **Modular Design:** Create a loosely coupled system to enhance separation of concerns.
+- **Utilizing Design Patterns:** Harness design patterns like Observer, Strategy, and Factory to ensure clear interfaces and responsibilities.
+
+## Alignment of Agents and SRP
+
+The notion of software agents naturally corresponds with the SRP. Each agent can be a distinct class or module that encapsulates a specific functionality. For instance:
+
+- An order processing agent focuses solely on order management.
+- A notification agent manages the sending of alerts or messages without getting involved in order processing logic.
+
+Designing agents with SRP in mind fosters modularity and reusability, allowing changes to one agent without affecting others and supporting more robust architecture.
+
+## Agent99 as a Reference Framework
+
+In its current iteration, the Agent99 Framework does not differ conceptually from other microservice architecture implementations. It enables centralized registration where agents list their capabilities for other agents or applications to discover. Agent communications occur via a distributed messaging system. The agent99 Ruby gem currently uses AMQP (via the Bunny gem and the RabbitMQ broker) and the NATS-server.
+
+### Agent Structure
+
+Agents in Agent99 inherit from **Agent99::Base**, which offers core functionality through crucial modules:
+
+- **HeaderManagement:** Handles message header processing.
+- **AgentDiscovery:** Facilitates capability advertisement and discovery.
+- **ControlActions:** Manages control messages.
+- **AgentLifecycle:** Oversees agent startup and shutdown functionality.
+- **MessageProcessing:** Manages message dispatch and handling.
+
+Every agent must define its type (server, client, or hybrid) and capabilities. The framework supports three message types: requests, responses, and control messages.
+
+```ruby
+class Agent99::Base
+  include Agent99::HeaderManagement
+  include Agent99::AgentDiscovery
+  include Agent99::ControlActions
+  include Agent99::AgentLifecycle
+  include Agent99::MessageProcessing
+
+  MESSAGE_TYPES = %w[request response control]
+
+  attr_reader :id, :capabilities, :name, :payload, :header, :logger, :queue
+  attr_accessor :registry_client, :message_client
+
+  ###################################################
+  private
+
+  def handle_error(message, error)
+    logger.error "#{message}: #{error.message}"
+    logger.debug error.backtrace.join("\n")
+  end
+
+  # the final rescue block
+  rescue StandardError => e
+    handle_error("Unhandled error in Agent99::Base", e)
+    exit(2)
+end
+```
+
+### Centralized Registry
+
+The registry service tracks agent availability and capabilities through a **RegistryClient**. A web-based application serves as the central registry, with a Sinatra implementation found in the `examples/registry.rb` file. Its primary function is to maintain a data store of registered agents.
+
+It supports three core operations:
+
+#### 1. Register
+
+![Central Registry Process](/assets/images/agent_registry_process.png)
+
+Agents register by providing their information (e.g., name and capabilities) to the registry service. Here's how registration works in practice:
+
+```ruby
+class WeatherAgent < Agent99::Base
+  TYPE = :server
+
+  def capabilities
+    %w[get_temperature get_forecast]
+  end
+
+  def receive_request(message)
+    case message.payload[:action]
+    when 'get_temperature'
+      send_response({ temperature: 72, unit: 'F' })
+    when 'get_forecast'
+      send_response({ forecast: 'Sunny with a chance of rain' })
+    end
+  end
+end
+
+# Start the agent
+WeatherAgent.new.run
+```
+
+Upon successful registration, agents receive a universally unique ID (UUID) that identifies them in the system. The registration process is handled automatically by the Agent99 framework when you call `run`.
+
+#### 2. Discover
+
+Agents can query the registry to discover capabilities. The discovery operation retrieves information about agents offering specific capabilities via an HTTP GET request.
+
+#### 3. Withdraw
+
+When an agent needs to exit the system, it withdraws its registration using its UUID, removing it from the available agents list through an HTTP DELETE request.
+
+### Messaging Network
+
+The Ruby implementation of Agent99 currently focuses on AMQP messaging systems. Messages are formatted as JSON structures that adhere to defined schemas, allowing the **MessageClient** to validate messages effortlessly.
+
+Messages are validated against defined schemas, and invalid messages return to the sender without invoking agent-specific processes.
+
+Message types within the framework include:
+
+#### Request Messages
+
+These messages are validated against an agent-defined schema and include:
+
+- A header with routing information.
+- Agent-specific elements with their types and examples.
+
+Requests are handled by the `receive_request` handler in target agents.
+
+Here's an example of a request message schema using the [SimpleJsonSchemaBuilder gem](https://github.com/mooktakim/simple_json_schema_builder)
+
+```ruby
+# examples/maxwell_request.rb
+
+require 'agent99/header_schema'
+
+class MaxwellRequest < SimpleJsonSchemaBuilder::Base
+  object do
+    object :header, schema: Agent99::HeaderSchema
+
+    string :greeting, required: false, examples: ["Hello"]
+    string :name,     required: true,  examples: ["World"]
+  end
+end
+```
+
+This schema defines a `MaxwellRequest` with a header (using the `Agent99::HeaderSchema`), an optional greeting, and a required name. A valid JSON message conforming to this schema might look like:
+
+```json
+{
+  "header": {
+    "from_uuid": "123e4567-e89b-12d3-a456-426614174000",
+    "to_uuid": "987e6543-e21b-12d3-a456-426614174000",
+    "message_id": "msg-001",
+    "correlation_id": "corr-001",
+    "timestamp": "2023-04-01T12:00:00Z"
+  },
+  "greeting": "Hello",
+  "name": "Agent99"
+}
+```
+
+Using such schemas ensures that messages are well-structured and contain all necessary information before being processed by agents.
+
+Here is how the **MaxwellAgent** associates itself with its specific request schema:
+
+```ruby
+# examples/maxwell_agent86.rb
+
+require 'agent99'
+require_relative 'maxwell_request'
+
+class MaxwellAgent86 < Agent99::Base
+  def info
+    {
+      # ...
+      request_schema: MaxwellRequest.schema,
+      # ...
+    }
+  end
+```
+
+When an agent subclass defines a **:request_schema** in its `info`, the message processing of the **Agent99::Base** validates all incoming requests against the schema. If there are errors, those errors are returned to the sender without presenting the request message to the agent's custom **receive_request** method.
+
+#### Response Messages
+
+Responses are routed back to the requesting agent and include:
+
+- The original message header in reverse.
+- The response payload.
+- Status information.
+
+Responses are processed by the `receive_response` method.
+
+#### Control Messages
+
+Control messages manage agent lifecycles and configurations and include commands such as:
+
+- **shutdown:** Stop the agent.
+- **pause/resume:** Temporarily suspend or resume operations.
+- **update_config:** Modify agent configurations.
+- **status:** Query agent state.
+- **response:** Handle control operation results.
+
+Messages are queued with a 60-second TTL (Time To Live) to prevent buildup from inactive agents.
+
+## Additional Resources
+
+For further exploration, check out the documentation of the current Ruby implementation at [GitHub](https://github.com/MadBomber/agent99).
+
+Contributions to this initial Ruby reference implementation are welcome! It would be exciting to see additional language implementations.

data/examples/README.md

@@ -45,6 +45,49 @@ This file implements a simple registry service for AI agents using Sinatra.
   - DELETE `/withdraw/:uuid`: Withdraws an agent from the registry
   - GET `/`: Lists all registered agents
 
+### 5. control_agent.rb
+
+Example use of control messages.
+
+### 6. kaos_spy.rb
+  - Agent 99 was kinnapped by KAOS and forced to reveal the secrets of Control's centralized registry and communications network.
+  - The KAOS spy raided hacked the registry, stole the records for all of Control's agents in the field and DOX'ed them on social media.
+  - That was not enough for KAOS.  Knowing the secret UUID for each agent, KAOS proceeded to turn off the communication network one queue at a time.
+  - Get Smart -- Get Security
+
+### 7. agent_watcher.rb
+
+This file implements an agent watcher that dynamically loads and runs new agents.
+
+- Class: `AgentWatcher < Agent99::Base`
+- Functionality: Monitors a specified directory for new Ruby files and loads them as agents
+- Key features:
+  - Watches a configurable directory (default: './agents')
+  - Detects new .rb files added to the watched directory
+  - Dynamically loads new files as Ruby agents
+  - Instantiates and runs each new agent in a separate thread
+  - Handles errors during the loading and running process
+  - Terminates all loaded agents when the watcher is stopped
+- Key methods:
+  - `init`: Sets up the file watcher
+  - `setup_watcher`: Configures the directory listener
+  - `handle_new_agent`: Processes newly detected agent files
+
+### 8. example_agent.rb
+
+This file provides a simple example agent that can be dynamically loaded by the AgentWatcher.
+
+- Class: `ExampleAgent < Agent99::Base`
+- Functionality: Demonstrates a basic agent that can be dynamically loaded
+- Key features:
+  - Defines capabilities as a rubber stamp and yes-man
+  - Responds to all requests with a success status
+- Key methods:
+  - `capabilities`: Defines the agent's capabilities
+  - `receive_request`: Handles incoming requests and sends a response
+
+Note: To use the example_agent.rb, first run the AgentWatcher, then copy example_agent.rb into the 'agents' directory. The AgentWatcher will automatically detect, load, and run the new agent.
+
 ## Usage
 
 From the examples directory you will need to start three different processes.  You will want to keep them all in the forgound so it would be best to start them in different terminal windows.

data/examples/agent_watcher.rb

@@ -0,0 +1,106 @@
+#!/usr/bin/env ruby
+# examples/agent_watcher.rb
+#
+# This file defines an AgentWatcher class that monitors a specified directory
+# for new Ruby files and dynamically loads and runs them as agents.
+
+# When running, the AgentWatcher does the following:
+# 1. Watches the directory specified by AGENT_WATCH_PATH (default: './agents')
+# 2. Detects when new .rb files are added to the watched directory
+# 3. Attempts to load each new file as a Ruby agent
+# 4. If successful, instantiates the agent and runs it in a separate thread
+#
+# When example_agent.rb is copied into the agents directory:
+# 1. The AgentWatcher detects the new file
+# 2. It attempts to load the file and extract the agent class
+# 3. If the class is a subclass of Agent99::Base, it instantiates the agent
+# 4. The new agent is then run in a separate thread
+# 5. Any errors during this process are logged for debugging
+#
+# When AgentWatcher is terminated, it first terminates all of the
+# agents that it has previously loaded and then terminates itself.
+
+
+require 'listen'
+
+require_relative '../lib/agent99'
+
+class AgentWatcher < Agent99::Base
+  TYPE = :client
+
+  def capabilities = {
+    info: {
+      capabilities: %w[ launch_agents watcher launcher ]
+    }
+  }
+
+  def init
+    @watch_path = ENV.fetch('AGENT_WATCH_PATH', './agents')
+    setup_watcher
+  end
+
+  private
+
+  def setup_watcher
+    @listener = Listen.to(@watch_path) do |modified, added, removed|
+      added.each do |file|
+        handle_new_agent(file)
+      end
+    end
+    
+    # Start listening in a separate thread
+    @listener.start
+  end
+
+  def handle_new_agent(file)
+    return unless File.extname(file) == '.rb'
+    
+    begin
+      # Load the new agent file
+      require file
+      
+      # Extract the class name from the file name
+      class_name = File.basename(file, '.rb')
+                      .split('_')
+                      .map(&:capitalize)
+                      .join
+      
+      # Get the class object
+      agent_class = Object.const_get(class_name)
+      
+      # Verify it's an Agent99::Base subclass
+      return unless agent_class < Agent99::Base
+      
+      # Create and run the new agent in a thread
+      Thread.new do
+        begin
+          agent = agent_class.new
+          agent.run
+        rescue StandardError => e
+          logger.error "Error running agent #{class_name}: #{e.message}"
+          logger.debug e.backtrace.join("\n")
+        end
+      end
+      
+      logger.info "Successfully launched agent: #{class_name}"
+    
+    rescue LoadError => e
+      logger.error "Failed to load agent file #{file}: #{e.message}"
+    
+    rescue NameError => e
+      logger.error "Failed to instantiate agent class from #{file}: #{e.message}"
+    
+    rescue StandardError => e
+      logger.error "Unexpected error handling #{file}: #{e.message}"
+      logger.debug e.backtrace.join("\n")
+    end
+  end
+
+  def fini
+    @listener&.stop
+    super
+  end
+end
+
+watcher = AgentWatcher.new
+watcher.run

data/examples/chief_agent.rb

@@ -14,7 +14,23 @@
 require_relative '../lib/agent99'
 
 class ChiefAgent < Agent99::Base
-  TYPE = :client
+  # this information is made available when the agent
+  # registers with the central registry service.  It is
+  # made available during the discovery process.
+  #
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :client,
+      capabilities:     ['Chief of Control'],
+      # request_schema:   ChiefRequest.schema,
+      # response_schema:  {}, # Agent99::RESPONSE.schema
+      # control_schema:   {}, # Agent99::CONTROL.schema
+      # error_schema:     {}, # Agent99::ERROR.schema
+    }
+  end
+
+
 
   # init is called at the end of the initialization process.
   # It may be only something that a :client type agent would do.
@@ -82,11 +98,6 @@ class ChiefAgent < Agent99::Base
 
     exit(0)
   end
-
-
-  def capabilities
-    ['Chief of Control']
-  end
 end
 
 

data/examples/control.rb

@@ -4,7 +4,21 @@
 require_relative '../lib/agent99'
 
 class Control < Agent99::Base
-  TYPE = :hybrid
+  # this information is made available when the agent
+  # registers with the central registry service.  It is
+  # made available during the discovery process.
+  #
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :hybrid,
+      capabilities:     ['control', 'headquarters', 'secret underground base'],
+      # request_schema:   ControlRequest.schema,
+      # response_schema:  {}, # Agent99::RESPONSE.schema
+      # control_schema:   {}, # Agent99::CONTROL.schema
+      # error_schema:     {}, # Agent99::ERROR.schema
+    }
+  end
 
   attr_accessor :statuses
 
@@ -14,11 +28,6 @@ class Control < Agent99::Base
   end
 
 
-  def capabilities
-    ['control', 'headquarters', 'secret underground base']
-  end
-
-
   def send_control_message(message:, payload: {})
     @agents.each do |agent|
       response = @message_client.publish(
@@ -48,7 +57,7 @@ class Control < Agent99::Base
 
 
   def stop_all
-    send_control_message(message: 'stop')
+    send_control_message(message: 'shutdown')
   end
 
   def get_all_status

data/examples/example_agent.rb

@@ -0,0 +1,39 @@
+# examples/example_agent.rb
+#
+# NOTE: This agent is meant to be loaded
+#       by the agent_watcher.rb be file.
+#       To do that first have AgentWatcher running
+#       then `cp example_agent.rb agents`
+#       AgentWatcher will see the new file arrive
+#       in the `agents` folder, will determine that the
+#       new file contains an Agent99 subclass, will
+#       load it, create a new instance of the class and
+#       finally run the new instance within its own
+#       thread as part of the AgentWatcher process.
+#
+
+require_relative '../../lib/agent99'
+
+class ExampleAgent < Agent99::Base
+  # this information is made available when the agent
+  # registers with the central registry service.  It is
+  # made available during the discovery process.
+  #
+  def info
+    {
+      name:             self.class.to_s,
+      type:             :server,
+      capabilities:     %w[ rubber_stamp yes_man example ],
+      # request_schema:   {}, # ExampleRequest.schema,
+      # response_schema:  {}, # Agent99::RESPONSE.schema
+      # control_schema:   {}, # Agent99::CONTROL.schema
+      # error_schema:     {}, # Agent99::ERROR.schema
+    }
+  end  
+
+  
+  def receive_request
+    logger.info "Example agent received request: #{payload}"
+    send_response(status: 'success')
+  end
+end