a2a-ruby 1.0.0

data/lib/a2a/rails/generators/templates/agent_readme.md

@@ -0,0 +1,200 @@
+# <%= class_name.humanize %> A2A Agent
+
+<%= agent_description %>
+
+## Overview
+
+This agent provides A2A (Agent2Agent) protocol endpoints for <%= class_name.humanize.downcase %> functionality. It was generated using the A2A Ruby SDK Rails generator.
+
+## Endpoints
+
+### Agent Card
+- **URL**: `<%= agent_card_path %>`
+- **Method**: GET
+- **Description**: Returns the agent card with capabilities and interface information
+
+### JSON-RPC Interface
+- **URL**: `<%= rpc_path %>`
+- **Method**: POST
+- **Content-Type**: application/json
+- **Description**: Handles A2A JSON-RPC method calls
+
+## Skills and Capabilities
+
+<% if skills.any? %>
+This agent provides the following skills:
+
+<% skills.each do |skill| %>
+### <%= skill.humanize %>
+- **Method**: `<%= skill.underscore %>`
+- **Description**: <%= skill.humanize %> functionality
+- **Tags**: `<%= skill %>`, `generated`
+
+<% end %>
+<% else %>
+### Default Processing
+- **Method**: `process`
+- **Description**: Default <%= class_name.humanize.downcase %> processing functionality
+- **Tags**: `<%= class_name.underscore %>`, `default`
+<% end %>
+
+### Status
+- **Method**: `status`
+- **Description**: Get agent status and health information
+- **Tags**: `status`, `health`
+
+## Usage Examples
+
+### Get Agent Card
+```bash
+curl -X GET <%= agent_card_path %>
+```
+
+### Call Agent Method
+```bash
+curl -X POST <%= rpc_path %> \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "status",
+    "params": {},
+    "id": 1
+  }'
+```
+
+<% if skills.any? %>
+<% skills.first(2).each do |skill| %>
+### <%= skill.humanize %> Example
+```bash
+curl -X POST <%= rpc_path %> \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "<%= skill.underscore %>",
+    "params": {
+      "action": "<%= skill %>"
+    },
+    "id": 1
+  }'
+```
+<% end %>
+<% end %>
+
+<% if with_authentication? %>
+## Authentication
+
+This agent requires authentication for certain methods:
+
+<% authentication_methods.each do |method| %>
+- `<%= method %>` - Requires valid authentication
+<% end %>
+
+### Authentication Example
+```bash
+curl -X POST <%= rpc_path %> \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "<%= authentication_methods.first %>",
+    "params": {},
+    "id": 1
+  }'
+```
+<% end %>
+
+## Development
+
+### Customizing the Agent
+
+1. **Add New Skills**: Define new skills using the `a2a_skill` DSL in the controller
+2. **Implement Methods**: Add method implementations using the `a2a_method` DSL
+3. **Configure Authentication**: Customize authentication requirements using `a2a_authenticate`
+
+### Example: Adding a New Skill
+
+```ruby
+# In <%= controller_file_path %>
+
+a2a_skill "new_feature" do |skill|
+  skill.description = "Description of the new feature"
+  skill.tags = ["new", "feature"]
+  skill.examples = [
+    {
+      input: { param: "value" },
+      output: { result: "success" }
+    }
+  ]
+end
+
+a2a_method "new_feature" do |params|
+  # Implement your logic here
+  {
+    result: "Feature implemented",
+    params: params,
+    timestamp: Time.current.iso8601
+  }
+end
+```
+
+### Testing
+
+Run the generated tests:
+
+```bash
+# RSpec
+bundle exec rspec spec/controllers/<%= namespace ? "#{namespace}/" : "" %><%= file_name %>_controller_spec.rb
+
+# Or Rails test
+bundle exec rails test test/controllers/<%= namespace ? "#{namespace}/" : "" %><%= file_name %>_controller_test.rb
+```
+
+### Debugging
+
+Use the Rails console to test your agent:
+
+```ruby
+# Start Rails console
+rails console
+
+# Test agent methods directly
+controller = <%= controller_class_name %>.new
+controller.request = ActionDispatch::Request.new({})
+
+# Generate agent card
+card = controller.send(:generate_agent_card)
+puts JSON.pretty_generate(card.to_h)
+
+# Test method execution
+result = controller.send(:handle_a2a_request, 
+  A2A::Protocol::JsonRpc::Request.new(
+    jsonrpc: "2.0",
+    method: "status",
+    params: {},
+    id: 1
+  )
+)
+puts JSON.pretty_generate(result)
+```
+
+## Configuration
+
+The agent inherits configuration from `config/initializers/a2a.rb`. You can customize:
+
+- Authentication requirements
+- Middleware settings
+- Storage backends
+- Logging levels
+
+## Documentation
+
+- [A2A Protocol Specification](https://a2a-protocol.org/)
+- [A2A Ruby SDK Documentation](https://a2a-protocol.org/sdk/ruby/)
+- [Rails Integration Guide](https://a2a-protocol.org/sdk/ruby/rails/)
+
+## Support
+
+For issues and questions:
+- Check the [A2A Ruby SDK Issues](https://github.com/a2aproject/a2a-ruby/issues)
+- Review the [Rails Integration Documentation](https://a2a-protocol.org/sdk/ruby/rails/)
+- Join the [A2A Community](https://a2a-protocol.org/community/)

data/lib/a2a/rails/generators/templates/create_a2a_push_notification_configs.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+class Create<%= table_prefix.classify %>PushNotificationConfigs < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= push_notification_configs_table_name %>, id: false do |t|
+      # Primary key
+      <% if postgresql? %>
+      t.uuid :id, primary_key: true, default: "gen_random_uuid()"
+      t.uuid :task_id, null: false
+      <% else %>
+      t.string :id, primary_key: true, limit: 36, null: false
+      t.string :task_id, limit: 36, null: false
+      <% end %>
+      
+      # Push notification configuration
+      t.string :url, null: false
+      t.string :token, null: true
+      t.<%= json_column_type %> :authentication, null: true, default: -> { 
+        <% if postgresql? %>
+        "'{}'::jsonb"
+        <% else %>
+        "'{}'"
+        <% end %>
+      }
+      
+      # Configuration metadata
+      t.<%= json_column_type %> :metadata, null: true, default: -> { 
+        <% if postgresql? %>
+        "'{}'::jsonb"
+        <% else %>
+        "'{}'"
+        <% end %>
+      }
+      
+      # Status tracking
+      t.boolean :active, null: false, default: true
+      t.integer :retry_count, null: false, default: 0
+      t.datetime :last_success_at, null: true
+      t.datetime :last_failure_at, null: true
+      t.text :last_error, null: true
+      
+      # Timestamps
+      t.timestamps null: false
+      
+      # Soft delete support
+      t.datetime :deleted_at, null: true
+    end
+
+    <% if with_indexes? %>
+    # Add indexes for performance
+    add_index :<%= push_notification_configs_table_name %>, :id, unique: true
+    add_index :<%= push_notification_configs_table_name %>, :task_id
+    add_index :<%= push_notification_configs_table_name %>, :active
+    add_index :<%= push_notification_configs_table_name %>, :created_at
+    add_index :<%= push_notification_configs_table_name %>, :deleted_at
+    
+    <% if postgresql? %>
+    # PostgreSQL-specific indexes for JSON columns
+    add_index :<%= push_notification_configs_table_name %>, :authentication, using: :gin
+    add_index :<%= push_notification_configs_table_name %>, :metadata, using: :gin
+    <% end %>
+    <% end %>
+
+    # Foreign key constraint to tasks table
+    add_foreign_key :<%= push_notification_configs_table_name %>, :<%= tasks_table_name %>, 
+                    column: :task_id, primary_key: :id, on_delete: :cascade
+  end
+end

data/lib/a2a/rails/generators/templates/create_a2a_tasks.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+class Create<%= table_prefix.classify %>Tasks < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= tasks_table_name %>, id: false do |t|
+      # Primary key - use UUID if PostgreSQL, string otherwise
+      <% if postgresql? %>
+      t.uuid :id, primary_key: true, default: "gen_random_uuid()"
+      t.uuid :context_id, null: false
+      <% else %>
+      t.string :id, primary_key: true, limit: 36, null: false
+      t.string :context_id, limit: 36, null: false
+      <% end %>
+      
+      # Task metadata
+      t.string :kind, null: false, default: "task"
+      t.string :type, null: true # For task type classification
+      
+      # Task status information
+      t.string :status_state, null: false, default: "submitted"
+      t.text :status_message, null: true
+      t.decimal :status_progress, precision: 5, scale: 2, null: true
+      t.<%= json_column_type %> :status_result, null: true
+      t.<%= json_column_type %> :status_error, null: true
+      t.datetime :status_updated_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      
+      # Task data
+      t.<%= json_column_type %> :artifacts, null: true, default: -> { 
+        <% if postgresql? %>
+        "'[]'::jsonb"
+        <% else %>
+        "'[]'"
+        <% end %>
+      }
+      t.<%= json_column_type %> :history, null: true, default: -> { 
+        <% if postgresql? %>
+        "'[]'::jsonb"
+        <% else %>
+        "'[]'"
+        <% end %>
+      }
+      t.<%= json_column_type %> :metadata, null: true, default: -> { 
+        <% if postgresql? %>
+        "'{}'::jsonb"
+        <% else %>
+        "'{}'"
+        <% end %>
+      }
+      
+      # Task parameters and configuration
+      t.<%= json_column_type %> :params, null: true, default: -> { 
+        <% if postgresql? %>
+        "'{}'::jsonb"
+        <% else %>
+        "'{}'"
+        <% end %>
+      }
+      
+      # Timestamps
+      t.timestamps null: false
+      
+      # Soft delete support
+      t.datetime :deleted_at, null: true
+    end
+
+    <% if with_indexes? %>
+    # Add indexes for performance
+    add_index :<%= tasks_table_name %>, :id, unique: true
+    add_index :<%= tasks_table_name %>, :context_id
+    add_index :<%= tasks_table_name %>, :status_state
+    add_index :<%= tasks_table_name %>, :type
+    add_index :<%= tasks_table_name %>, :created_at
+    add_index :<%= tasks_table_name %>, :status_updated_at
+    add_index :<%= tasks_table_name %>, :deleted_at
+    
+    <% if postgresql? %>
+    # PostgreSQL-specific indexes for JSON columns
+    add_index :<%= tasks_table_name %>, :metadata, using: :gin
+    add_index :<%= tasks_table_name %>, :params, using: :gin
+    <% end %>
+    <% end %>
+  end
+end

data/lib/a2a/rails/generators/templates/example_agent_controller.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+##
+# Example A2A Agent Controller
+#
+# This controller demonstrates how to create an A2A agent using the Rails integration.
+# It includes examples of skills, capabilities, and method definitions.
+#
+# To test this agent:
+# 1. Start your Rails server
+# 2. Visit <%= mount_path %>/agent-card to see the agent card
+# 3. Send JSON-RPC requests to <%= mount_path %>/rpc
+#
+class ExampleAgentController < ApplicationController
+  include A2A::Rails::ControllerHelpers
+
+  # Configure this agent
+  a2a_agent name: "Example Agent",
+            description: "A demonstration A2A agent for Rails integration",
+            version: "1.0.0",
+            tags: ["example", "demo", "rails"]
+
+  <% if with_authentication? %>
+  # Configure authentication (uncomment and customize as needed)
+  # a2a_authenticate :<%= authentication_strategy %>, methods: ["secure_greeting"]
+  <% end %>
+
+  # Define agent skills
+  a2a_skill "greeting" do |skill|
+    skill.description = "Greet users with personalized messages"
+    skill.tags = ["greeting", "conversation", "social"]
+    skill.examples = [
+      {
+        input: { name: "Alice" },
+        output: { message: "Hello, Alice! Welcome to our A2A agent." }
+      }
+    ]
+  end
+
+  a2a_skill "echo" do |skill|
+    skill.description = "Echo back any message sent to the agent"
+    skill.tags = ["utility", "testing", "echo"]
+    skill.examples = [
+      {
+        input: { message: "Hello, world!" },
+        output: { echo: "Hello, world!" }
+      }
+    ]
+  end
+
+  a2a_skill "time" do |skill|
+    skill.description = "Get current server time in various formats"
+    skill.tags = ["utility", "time", "datetime"]
+    skill.examples = [
+      {
+        input: { format: "iso8601" },
+        output: { time: "2024-01-01T12:00:00Z", format: "iso8601" }
+      }
+    ]
+  end
+
+  # A2A method implementations
+
+  ##
+  # Greet a user with a personalized message
+  #
+  # @param params [Hash] Request parameters
+  # @option params [String] :name The name to greet
+  # @option params [String] :style Greeting style (formal, casual, friendly)
+  # @return [Hash] Greeting response
+  #
+  a2a_method "greeting" do |params|
+    name = params[:name] || "there"
+    style = params[:style] || "friendly"
+    
+    message = case style
+              when "formal"
+                "Good day, #{name}. It is a pleasure to make your acquaintance."
+              when "casual"
+                "Hey #{name}! What's up?"
+              else
+                "Hello, #{name}! Welcome to our A2A agent."
+              end
+    
+    {
+      message: message,
+      name: name,
+      style: style,
+      timestamp: Time.now.iso8601
+    }
+  end
+
+  ##
+  # Echo back the provided message
+  #
+  # @param params [Hash] Request parameters
+  # @option params [String] :message The message to echo
+  # @return [Hash] Echo response
+  #
+  a2a_method "echo" do |params|
+    message = params[:message] || ""
+    
+    {
+      echo: message,
+      length: message.length,
+      timestamp: Time.now.iso8601,
+      agent: "ExampleAgent"
+    }
+  end
+
+  ##
+  # Get current server time
+  #
+  # @param params [Hash] Request parameters
+  # @option params [String] :format Time format (iso8601, unix, human)
+  # @option params [String] :timezone Timezone (default: UTC)
+  # @return [Hash] Time response
+  #
+  a2a_method "get_time" do |params|
+    format = params[:format] || "iso8601"
+    timezone = params[:timezone] || "UTC"
+    
+    begin
+      time = Time.now.in_time_zone(timezone)
+      
+      formatted_time = case format
+                      when "unix"
+                        time.to_i
+                      when "human"
+                        time.strftime("%B %d, %Y at %I:%M %p %Z")
+                      else
+                        time.iso8601
+                      end
+      
+      {
+        time: formatted_time,
+        format: format,
+        timezone: timezone,
+        server_timezone: Time.zone.name
+      }
+    rescue ArgumentError => e
+      raise A2A::Errors::InvalidParams, "Invalid timezone: #{timezone}"
+    end
+  end
+
+  <% if with_authentication? %>
+  ##
+  # Secure greeting method (requires authentication)
+  #
+  # @param params [Hash] Request parameters
+  # @option params [String] :message Personal message
+  # @return [Hash] Authenticated greeting response
+  #
+  a2a_method "secure_greeting" do |params|
+    message = params[:message] || "Hello from the secure zone!"
+    
+    {
+      message: message,
+      user: current_user_info,
+      permissions: current_user_permissions,
+      authenticated_at: Time.now.iso8601,
+      security_level: "authenticated"
+    }
+  end
+  <% end %>
+
+  ##
+  # Get agent status and health information
+  #
+  # @param params [Hash] Request parameters (unused)
+  # @return [Hash] Status response
+  #
+  a2a_method "status" do |params|
+    {
+      status: "healthy",
+      version: "1.0.0",
+      uptime: Time.now - Rails.application.config.booted_at,
+      rails_version: Rails.version,
+      a2a_version: A2A::VERSION,
+      capabilities: self.class._a2a_capabilities&.map(&:name) || [],
+      methods: self.class._a2a_methods&.keys || [],
+      timestamp: Time.now.iso8601
+    }
+  end
+
+  # Standard Rails actions for agent card and RPC handling
+
+  ##
+  # Serve the agent card
+  #
+  def agent_card
+    render_agent_card
+  end
+
+  ##
+  # Handle JSON-RPC requests
+  #
+  def rpc
+    handle_a2a_rpc
+  end
+
+  private
+
+  # Override authentication methods if needed
+  <% if with_authentication? %>
+  
+  def current_user_info
+    if respond_to?(:current_user) && current_user.present?
+      {
+        id: current_user.id,
+        email: current_user.email,
+        name: current_user.name || current_user.email
+      }
+    else
+      { id: "anonymous", name: "Anonymous User" }
+    end
+  end
+
+  def current_user_permissions
+    # Customize based on your authorization system
+    if respond_to?(:current_user) && current_user.present?
+      ["read", "write"] # Example permissions
+    else
+      ["read"] # Anonymous permissions
+    end
+  end
+  <% end %>
+end

data/lib/a2a/rails/generators/templates/initializer.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# A2A Ruby SDK Configuration
+# 
+# This file configures the A2A (Agent2Agent) Protocol integration for your Rails application.
+# For more information, visit: https://a2a-protocol.org/sdk/ruby/
+
+A2A.configure do |config|
+  # Enable Rails integration
+  config.rails_integration = true
+  
+  # Mount path for A2A endpoints (default: "/a2a")
+  config.mount_path = "<%= mount_path %>"
+  
+  # Protocol configuration
+  config.protocol_version = "0.3.0"
+  config.default_transport = "JSONRPC"
+  
+  # Feature flags
+  config.streaming_enabled = true
+  config.push_notifications_enabled = true
+  
+  # Default MIME types for input/output
+  config.default_input_modes = ["text/plain", "application/json"]
+  config.default_output_modes = ["text/plain", "application/json"]
+  
+  # Middleware configuration
+  config.middleware_enabled = true
+  config.cors_enabled = true
+  config.rate_limiting_enabled = false
+  config.logging_enabled = Rails.env.development?
+  
+  # Authentication configuration
+  config.authentication_required = <%= with_authentication? %>
+  config.webhook_authentication_required = false
+  
+  # Storage configuration
+  <% case storage_backend %>
+  <% when "database" %>
+  # Database storage (requires running migrations)
+  config.task_storage = :database
+  <% when "redis" %>
+  # Redis storage configuration
+  config.task_storage = :redis
+  config.redis_config = {
+    url: ENV.fetch("REDIS_URL", "redis://localhost:6379/0"),
+    pool_size: 5,
+    pool_timeout: 5
+  }
+  <% else %>
+  # In-memory storage (default - not recommended for production)
+  config.task_storage = :memory
+  <% end %>
+  
+  # Timeout configuration
+  config.default_timeout = 30
+  
+  # Logging configuration
+  config.log_level = Rails.env.production? ? :info : :debug
+  
+  # User agent for HTTP requests
+  config.user_agent = "#{Rails.application.class.module_parent_name}/#{Rails.application.config.version rescue '1.0.0'} A2A-Ruby/<%= a2a_version %>"
+end
+
+# Rails-specific configuration
+Rails.application.configure do
+  # A2A engine configuration
+  config.a2a.enabled = true
+  config.a2a.mount_path = "<%= mount_path %>"
+  config.a2a.auto_mount = true
+  
+  # Middleware configuration
+  config.a2a.middleware_enabled = true
+  config.a2a.cors_enabled = true
+  config.a2a.rate_limiting_enabled = false
+  config.a2a.logging_enabled = Rails.env.development?
+  
+  # Authentication configuration
+  config.a2a.authentication_required = <%= with_authentication? %>
+end
+
+# Environment-specific configuration
+case Rails.env
+when "development"
+  A2A.configure do |config|
+    config.log_level = :debug
+    config.logging_enabled = true
+  end
+  
+when "test"
+  A2A.configure do |config|
+    config.task_storage = :memory
+    config.log_level = :warn
+    config.logging_enabled = false
+  end
+  
+when "production"
+  A2A.configure do |config|
+    config.log_level = :info
+    config.authentication_required = true
+    config.webhook_authentication_required = true
+    
+    # Use Redis in production if available
+    if ENV["REDIS_URL"].present?
+      config.task_storage = :redis
+    end
+  end
+end