Agent99

[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 🌐 Agent Discovery - Find agents by capabilities 📡 Peer-to-Peer Messaging - AMQP & NATS support 🔄 Message Processing - Requests, responses & control 📋 Registry Integration - Centralized agent registry ⚡ Control Actions - Pause, resume, update agents 🔧 Lifecycle Management - Easy setup & teardown 🚀 Multi-Agent Processing - Thread isolation support 📊 Error Handling & Logging - Built-in management

• Quick Start
• Prerequisites
• Architecture Overview
• Installation
• Usage
• Configuration
• Agent Lifecycle
• Message Processing
• Registry Integration
• Examples
• Evolving Standards
• Contributing
• Roadmap
• License

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

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

# macOS
brew install nats-server

# Start NATS
nats-server

# macOS
brew install rabbitmq

# Start RabbitMQ
brew services start rabbitmq

📋 More installation options: Installation Guide

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

Add this line to your application's Gemfile:

gem 'agent99'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install agent99

Create your first agent in three simple steps:

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

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

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

🎯 More examples: Usage Examples

Configure Agent99 through environment variables:

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

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

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

📚 Complete configuration guide: Configuration Documentation

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

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

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

Explore real-world implementations:

• 🚀 Demo Runner: Complete working system
• 👋 Greeter Agent: Simple request-response
• 🔄 Multi-Agent System: Coordinated agents
• 📊 Monitoring Dashboard: Agent status monitoring

💡 All examples: Examples Directory

• agntcy.org - Agency protocol initiative
• Agent2Agent - Linux Foundation protocol

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

• 🔍 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

• 🔐 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

• 🧠 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

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