a2a-ruby

A2A Ruby SDK

The A2A Ruby SDK provides a complete implementation of Google's Agent2Agent (A2A) Protocol for Ruby applications. It enables seamless agent-to-agent communication via JSON-RPC 2.0, gRPC, and HTTP+JSON transports.

Features

• 🚀 Complete A2A Protocol Support - Full implementation of the A2A specification
• 🔄 Multiple Transports - JSON-RPC 2.0, gRPC, and HTTP+JSON support
• 📡 Streaming & Events - Server-Sent Events for real-time communication
• 🔐 Security First - OAuth 2.0, JWT, API Key, and mTLS authentication
• 📋 Task Management - Complete task lifecycle with push notifications
• 🎯 Agent Cards - Self-describing agent capabilities and discovery
• 🛠 Rails Integration - Seamless Rails engine integration
• 📊 Production Ready - Comprehensive logging, metrics, and error handling

Installation

Add this line to your application's Gemfile:

gem 'a2a-ruby'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install a2a-ruby

Quick Start

Client Usage

require 'a2a'

# Create a client
client = A2A::Client::HttpClient.new("https://agent.example.com/a2a")

# Send a message
message = A2A::Types::Message.new(
  message_id: SecureRandom.uuid,
  role: "user",
  parts: [
    A2A::Types::TextPart.new(text: "Hello, agent!")
  ]
)

# Get response (streaming or blocking)
client.send_message(message) do |response|
  case response
  when A2A::Types::Message
    puts "Agent replied: #{response.parts.first.text}"
  when A2A::Types::Task
    puts "Task created: #{response.id}"
  end
end

Server Usage

class MyAgentController < ApplicationController
  include A2A::Server::Agent
  
  # Define agent skills
  a2a_skill "greeting" do |skill|
    skill.description = "Greet users in different languages"
    skill.tags = ["greeting", "conversation", "multilingual"]
    skill.examples = ["Hello", "Say hi in Spanish"]
  end
  
  # Define A2A methods
  a2a_method "greet" do |params|
    language = params[:language] || "en"
    name = params[:name] || "there"
    
    greeting = case language
    when "es" then "¡Hola"
    when "fr" then "Bonjour"
    else "Hello"
    end
    
    {
      message: "#{greeting}, #{name}!",
      language: language
    }
  end
  
  # Handle streaming responses
  a2a_method "chat", streaming: true do |params|
    Enumerator.new do |yielder|
      # Yield task status updates
      yielder << A2A::Types::TaskStatusUpdateEvent.new(
        task_id: params[:task_id],
        context_id: params[:context_id],
        status: A2A::Types::TaskStatus.new(state: "working")
      )
      
      # Process and yield response
      response = process_chat(params[:message])
      yielder << A2A::Types::Message.new(
        message_id: SecureRandom.uuid,
        role: "agent",
        parts: [A2A::Types::TextPart.new(text: response)]
      )
    end
  end
end

Rails Integration

# config/routes.rb
Rails.application.routes.draw do
  mount A2A::Engine => "/a2a"
end

# The engine automatically provides:
# POST /a2a/rpc          - JSON-RPC endpoint
# GET  /a2a/agent-card   - Agent card discovery
# GET  /a2a/capabilities - Capabilities endpoint

Configuration

A2A.configure do |config|
  config.protocol_version = "0.3.0"
  config.default_transport = "JSONRPC"
  config.streaming_enabled = true
  config.push_notifications_enabled = true
  config.default_timeout = 30
  config.log_level = :info
end

Documentation

Essential Guides:

• Getting Started - Installation and first steps
• Integration Guide - Rails, Sinatra, and plain Ruby integration
• API Reference - Complete API documentation
• Configuration - Configuration options
• Troubleshooting - Common issues, errors, and FAQ

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/a2aproject/a2a-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the A2A Ruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.