Agent99


[!CAUTION]

⚠️ Under Development ⚠️

Initial release has no AI components - it's a generic client-server / request-response micro-services system using peer-to-peer messaging and centralized agent registry. Review The Changelog for version changes.

Agent99 - Ruby Framework for Intelligent Software Agents

[Comprehensive Documentation Website](https://madbomber.github.io/agent99/) 		Agent99 is a Ruby-based framework for building and managing intelligent software agents in a distributed system. Like the clever Agent 99 from Get Smart, your agents will be smart, adaptable, and ready to tackle any challenge through seamless peer-to-peer communication and centralized discovery.

Key Features

Table of Contents

Quick Start

Jump right in with our step-by-step guide:

  1. Prerequisites: Install message broker (NATS or RabbitMQ)
  2. Install Agent99: Add to Gemfile and bundle install
  3. Start Registry: Launch the central agent registry
  4. Create Your First Agent: Build a simple greeter agent
  5. Test Communication: Verify agents can discover and communicate

📖 Detailed walkthrough: Getting Started Guide

Prerequisites

Agent99 requires a message broker for inter-agent communication. Choose one:

# macOS
brew install nats-server

# Start NATS
nats-server

RabbitMQ

# macOS
brew install rabbitmq

# Start RabbitMQ
brew services start rabbitmq

📋 More installation options: Installation Guide

Architecture Overview

Agent99 Architecture

Agent99 follows a distributed architecture with three core components:

  • 🏛️ Central Registry: Service discovery and agent registration
  • 📡 Message Broker: Peer-to-peer communication backbone (NATS/AMQP)
  • 🤖 Agents: Independent services with specific capabilities

📚 Deep dive: Architecture Documentation

Installation

Add this line to your application's Gemfile:

gem 'agent99'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install agent99

Usage

Create your first agent in three simple steps:

1. Define Request Schema

class GreeterRequest < SimpleJsonSchemaBuilder::Base
  object do
    object :header, schema: Agent99::HeaderSchema
    string :name, required: true, examples: ["World"]
  end
end

2. Implement Agent Class

class GreeterAgent < Agent99::Base
  def info
    {
      name: self.class.to_s,
      type: :server,
      capabilities: ['greeter', 'hello_world'],
      request_schema: GreeterRequest.schema
    }
  end

  def process_request(payload)
    name = payload.dig(:name)
    send_response(result: "Hello, #{name}!")
  end
end

3. Run Your Agent

require 'agent99'
agent = GreeterAgent.new
agent.run

🎯 More examples: Usage Examples

Configuration

Configure Agent99 through environment variables:

Core Settings

  • AGENT99_REGISTRY_URL: Registry service URL (default: http://localhost:4567)
  • AGENT99_LOG_LEVEL: Logging verbosity (default: INFO)

NATS Configuration

  • NATS_URL: NATS server URL (default: nats://localhost:4222)
  • NATS_USER: Username for authentication
  • NATS_PASS: Password for authentication

AMQP/RabbitMQ Configuration

  • RABBITMQ_URL: RabbitMQ server URL (default: amqp://localhost:5672)
  • RABBITMQ_USER: Username (default: guest)
  • RABBITMQ_PASS: Password (default: guest)

📚 Complete configuration guide: Configuration Documentation

Agent Lifecycle

Agent Lifecycle

Agent99 manages the complete lifecycle of your agents:

  • 🎬 Initialization: Agent registers with the central registry
  • ⚡ Running: Agent processes requests and sends responses
  • ⏸️ Paused: Agent temporarily stops processing (control action)
  • 🔄 Updated: Agent receives new configuration or capabilities
  • 🛑 Shutdown: Agent gracefully disconnects and cleans up

🔄 Detailed lifecycle management: Agent Lifecycle Guide

Message Processing

Message Processing Flow

Agent99 handles three types of messages:

  • 📨 Requests: Incoming work for agents to process
  • 📤 Responses: Results sent back to requesters
  • 🎛️ Control: Management commands (pause, resume, update)

Each message is validated, routed, and processed with full error handling and logging.

⚙️ Message processing details: Message Processing Guide

Registry Integration

Agent Registry Process

The central registry enables dynamic service discovery:

  1. 📝 Registration: Agents announce their capabilities
  2. 🔍 Discovery: Find agents by capability or name
  3. 📋 Management: Monitor and control registered agents
  4. 🚪 Withdrawal: Clean removal from registry

The registry supports both HTTP REST API and direct client integration.

🏛️ Registry implementation: Registry Documentation

Examples

Explore real-world implementations:

💡 All examples: Examples Directory

Evolving Standards

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/MadBomber/agent99.

Roadmap

Short-term (v0.1.x)

  • 🔍 Enhanced Discovery: Semantic search with vector database (SQLite + embeddings)
  • 📋 Schema Validation: Complete request/response schema definitions
  • 🤖 AI Integration: RAG-enabled agents using prompts as tools
  • 📊 Monitoring: Built-in metrics and health checks

Medium-term (v0.2.x)

  • 🔐 Security: Authentication and authorization framework
  • ⚡ Performance: Connection pooling and message batching
  • 🌍 Multi-broker: Support for multiple message brokers simultaneously
  • 📈 Scaling: Load balancing and auto-scaling capabilities

Long-term (v1.0+)

  • 🧠 Intelligence: Built-in ML/AI capabilities
  • 🔗 Interoperability: Full Agent2Agent protocol compliance
  • ☁️ Cloud-native: Kubernetes operators and cloud integrations

⚠️ Breaking changes: Migration Guide v0.0.4

License

The gem is available as open source under the terms of the MIT License.