a2a-ruby 1.0.0

data/lib/a2a/server/example_agent.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require_relative "agent"
+require_relative "a2a_methods"
+require_relative "../types"
+
+##
+# Example agent implementation demonstrating A2A protocol methods
+#
+# This class shows how to create an A2A agent that includes the standard
+# protocol methods and implements custom message processing logic.
+#
+module A2A
+  module Server
+    class ExampleAgent
+      include A2A::Server::Agent
+      include A2A::Server::A2AMethods
+
+      # Configure the agent
+      a2a_config name: "Example A2A Agent",
+                 description: "A demonstration agent for the A2A protocol",
+                 version: "1.0.0",
+                 default_input_modes: ["text"],
+                 default_output_modes: ["text"]
+
+      # Define a simple capability
+      a2a_capability "echo" do
+        method :echo
+        description "Echo back the input message"
+        input_schema type: "object",
+                     properties: { message: { type: "string" } },
+                     required: ["message"]
+        output_schema type: "object",
+                      properties: { echo: { type: "string" } }
+        tags %w[utility test]
+      end
+
+      # Define a custom method
+      a2a_method "echo" do |params, _context|
+        message = params["message"]
+        { echo: "You said: #{message}" }
+      end
+
+      protected
+
+      ##
+      # Process message synchronously
+      #
+      # @param message [A2A::Types::Message] The message to process
+      # @param task [A2A::Types::Task] The associated task
+      # @param context [A2A::Server::Context] Request context
+      # @return [Object] Processing result
+      def process_message_sync(message, task, _context)
+        # Extract text from message parts
+        text_parts = message.parts.select { |part| part.is_a?(A2A::Types::TextPart) }
+        text_content = text_parts.map(&:text).join(" ")
+
+        # Simple echo response
+        response_message = A2A::Types::Message.new(
+          message_id: SecureRandom.uuid,
+          role: A2A::Types::ROLE_AGENT,
+          parts: [
+            A2A::Types::TextPart.new(text: "Echo: #{text_content}")
+          ],
+          context_id: message.context_id,
+          task_id: task.id
+        )
+
+        # Add message to task history
+        task_manager.add_message(task.id, message)
+        task_manager.add_message(task.id, response_message)
+
+        {
+          message: response_message.to_h,
+          processed_at: Time.now.utc.iso8601
+        }
+      end
+
+      ##
+      # Process message asynchronously
+      #
+      # @param message [A2A::Types::Message] The message to process
+      # @param task [A2A::Types::Task] The associated task
+      # @param context [A2A::Server::Context] Request context
+      # @return [void]
+      def process_message_async(message, task, context)
+        # Start background processing
+        Thread.new do
+          # Simulate some processing time
+          sleep 1
+
+          # Process the message
+          result = process_message_sync(message, task, context)
+
+          # Update task with result
+          task_manager.update_task_status(
+            task.id,
+            A2A::Types::TaskStatus.new(
+              state: A2A::Types::TASK_STATE_COMPLETED,
+              result: result,
+              updated_at: Time.now.utc.iso8601
+            )
+          )
+        rescue StandardError => e
+          # Handle errors
+          task_manager.update_task_status(
+            task.id,
+            A2A::Types::TaskStatus.new(
+              state: A2A::Types::TASK_STATE_FAILED,
+              error: { message: e.message, type: e.class.name },
+              updated_at: Time.now.utc.iso8601
+            )
+          )
+        end
+      end
+
+      ##
+      # Process message stream
+      #
+      # @param message [A2A::Types::Message] The message to process
+      # @param task [A2A::Types::Task] The associated task
+      # @param context [A2A::Server::Context] Request context
+      # @yield [response] Yields each response in the stream
+      # @return [void]
+      def process_message_stream(message, task, _context)
+        # Extract text from message parts
+        text_parts = message.parts.select { |part| part.is_a?(A2A::Types::TextPart) }
+        text_content = text_parts.map(&:text).join(" ")
+
+        # Stream back the message word by word
+        words = text_content.split(/\s+/)
+
+        words.each_with_index do |word, index|
+          response_message = A2A::Types::Message.new(
+            message_id: SecureRandom.uuid,
+            role: A2A::Types::ROLE_AGENT,
+            parts: [
+              A2A::Types::TextPart.new(text: "Word #{index + 1}: #{word}")
+            ],
+            context_id: message.context_id,
+            task_id: task.id
+          )
+
+          yield response_message.to_h
+
+          # Small delay between words
+          sleep 0.5
+        end
+
+        # Final message
+        final_message = A2A::Types::Message.new(
+          message_id: SecureRandom.uuid,
+          role: A2A::Types::ROLE_AGENT,
+          parts: [
+            A2A::Types::TextPart.new(text: "Streaming complete. Processed #{words.length} words.")
+          ],
+          context_id: message.context_id,
+          task_id: task.id
+        )
+
+        yield final_message.to_h
+      end
+
+      ##
+      # Generate agent card
+      #
+      # @param context [A2A::Server::Context] Request context
+      # @return [A2A::Types::AgentCard] The agent card
+      def generate_agent_card(_context)
+        A2A::Types::AgentCard.new(
+          name: self.class._a2a_config[:name] || "Example Agent",
+          description: self.class._a2a_config[:description] || "An example A2A agent",
+          version: self.class._a2a_config[:version] || "1.0.0",
+          url: "https://example.com/agent",
+          preferred_transport: A2A::Types::TRANSPORT_JSONRPC,
+          skills: generate_skills_from_capabilities,
+          capabilities: generate_capabilities_info,
+          default_input_modes: self.class._a2a_config[:default_input_modes] || ["text"],
+          default_output_modes: self.class._a2a_config[:default_output_modes] || ["text"],
+          additional_interfaces: [
+            A2A::Types::AgentInterface.new(
+              transport: A2A::Types::TRANSPORT_JSONRPC,
+              url: "https://example.com/agent/rpc"
+            )
+          ],
+          supports_authenticated_extended_card: true,
+          protocol_version: "1.0"
+        )
+      end
+
+      ##
+      # Generate extended agent card with authentication context
+      #
+      # @param context [A2A::Server::Context] Request context
+      # @return [A2A::Types::AgentCard] The extended agent card
+      def generate_extended_agent_card(context)
+        # Get base card
+        card = generate_agent_card(context)
+
+        # Add authenticated user information if available
+        if context.user
+          # Modify card based on user context
+          # This is where you could add user-specific capabilities or information
+          card.instance_variable_set(:@metadata, {
+                                       authenticated_user: context.user.to_s,
+                                       authentication_time: Time.now.utc.iso8601,
+                                       extended_features: %w[user_context personalized_responses]
+                                     })
+        end
+
+        card
+      end
+
+      private
+
+      ##
+      # Generate skills from registered capabilities
+      #
+      # @return [Array<A2A::Types::AgentSkill>] List of skills
+      def generate_skills_from_capabilities
+        self.class.a2a_capability_registry.all.map do |capability|
+          A2A::Types::AgentSkill.new(
+            id: capability.name,
+            name: capability.name.humanize,
+            description: capability.description || "No description available",
+            tags: capability.tags || [],
+            examples: capability.examples || [],
+            input_modes: ["text"],
+            output_modes: ["text"]
+          )
+        end
+      end
+
+      ##
+      # Generate capabilities information
+      #
+      # @return [A2A::Types::AgentCapabilities] Capabilities info
+      def generate_capabilities_info
+        A2A::Types::AgentCapabilities.new(
+          streaming: true,
+          push_notifications: true,
+          state_transition_history: true,
+          extensions: []
+        )
+      end
+    end
+  end
+end

data/lib/a2a/server/handler.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require_relative "../protocol/json_rpc"
+require_relative "../errors"
+require_relative "agent"
+require_relative "middleware"
+
+##
+# Request handler for processing A2A JSON-RPC requests
+#
+# This class handles the processing of JSON-RPC requests, including
+# method routing, parameter validation, response generation, and
+# batch request processing.
+#
+# @example Basic usage
+#   handler = A2A::Server::Handler.new(agent_instance)
+#   response = handler.handle_request(json_request_string)
+#
+module A2A
+  module Server
+    class Handler
+      attr_reader :agent, :middleware_stack
+
+      ##
+      # Initialize a new request handler
+      #
+      # @param agent [Object] The agent instance that includes A2A::Server::Agent
+      # @param middleware [Array] Array of middleware to apply
+      def initialize(agent, middleware: [])
+        @agent = agent
+        @middleware_stack = middleware.dup
+
+        validate_agent!
+      end
+
+      ##
+      # Handle a JSON-RPC request string
+      #
+      # @param request_body [String] The JSON-RPC request as a string
+      # @param context [A2A::Server::Context, nil] Optional request context
+      # @return [String] The JSON-RPC response as a string
+      def handle_request(request_body, context: nil)
+        A2A::Monitoring::Instrumentation.instrument_request({ method: "parse_request" }) do
+          # Parse the JSON-RPC request
+          parsed_request = A2A::Protocol::JsonRpc.parse_request(request_body)
+
+          # Handle single or batch requests
+          if parsed_request.is_a?(Array)
+            handle_batch_request(parsed_request, context: context)
+          else
+            handle_single_request(parsed_request, context: context)
+          end
+        rescue A2A::Errors::A2AError => e
+          # Return error response for A2A errors
+          error_response = A2A::Protocol::JsonRpc.build_error_response(
+            code: e.code,
+            message: e.message,
+            data: e.data,
+            id: nil # Unknown ID for parse errors
+          )
+          error_response.to_json
+        rescue StandardError => e
+          # Return internal error for unexpected errors
+          error_response = A2A::Protocol::JsonRpc.build_error_response(
+            code: A2A::Protocol::JsonRpc::INTERNAL_ERROR,
+            message: "Internal server error: #{e.message}",
+            id: nil
+          )
+          error_response.to_json
+        end
+      end
+
+      ##
+      # Handle a single JSON-RPC request
+      #
+      # @param request [A2A::Protocol::Request] The parsed request
+      # @param context [A2A::Server::Context, nil] Optional request context
+      # @return [String] The JSON-RPC response as a string
+      def handle_single_request(request, context: nil)
+        # Apply middleware stack
+        response = apply_middleware_stack(request, context) do
+          # Route the request to the agent
+          route_request(request, context: context)
+        end
+
+        # Convert response to JSON
+        if response
+          response.to_json
+        else
+          # No response for notifications
+          nil
+        end
+      end
+
+      ##
+      # Handle a batch JSON-RPC request
+      #
+      # @param requests [Array<A2A::Protocol::Request>] Array of parsed requests
+      # @param context [A2A::Server::Context, nil] Optional request context
+      # @return [String] The JSON-RPC batch response as a string
+      def handle_batch_request(requests, context: nil)
+        # Process each request in the batch
+        responses = requests.map do |request|
+          # Apply middleware stack for each request
+          apply_middleware_stack(request, context) do
+            route_request(request, context: context)
+          end
+        rescue StandardError => e
+          # Convert errors to error responses
+          A2A::Errors::ErrorUtils.exception_to_json_rpc_error(e, request_id: request.id)
+        end
+
+        # Filter out nil responses (from notifications)
+        batch_response = A2A::Protocol::JsonRpc.build_batch_response(responses.compact)
+
+        # Return empty array if no responses (all notifications)
+        batch_response.to_json
+      end
+
+      ##
+      # Route a request to the appropriate agent method
+      #
+      # @param request [A2A::Protocol::Request] The JSON-RPC request
+      # @param context [A2A::Server::Context, nil] Optional request context
+      # @return [Hash, nil] The JSON-RPC response hash or nil for notifications
+      def route_request(request, context: nil)
+        # Validate the request
+        validate_request(request)
+
+        # Create or enhance context
+        request_context = context || A2A::Server::Context.new(request: request)
+        request_context.instance_variable_set(:@request, request) if context
+
+        # Check if the method exists
+        unless @agent.class.a2a_method_registered?(request.method)
+          raise A2A::Errors::MethodNotFound, "Method '#{request.method}' not found"
+        end
+
+        # Get method definition for validation
+        @agent.class.a2a_method_definition(request.method)
+
+        # Validate parameters against capability schema if available
+        validate_method_parameters(request.method, request.params)
+
+        # Delegate to the agent
+        @agent.handle_a2a_request(request, context: request_context)
+      end
+
+      ##
+      # Add middleware to the handler
+      #
+      # @param middleware [Object] Middleware instance that responds to #call
+      def add_middleware(middleware)
+        @middleware_stack << middleware
+      end
+
+      ##
+      # Remove middleware from the handler
+      #
+      # @param middleware [Object] Middleware instance to remove
+      def remove_middleware(middleware)
+        @middleware_stack.delete(middleware)
+      end
+
+      ##
+      # Get all registered methods from the agent
+      #
+      # @return [Array<String>] Array of method names
+      def registered_methods
+        @agent.class.a2a_method_registry.keys
+      end
+
+      ##
+      # Check if a method is registered
+      #
+      # @param method_name [String] The method name to check
+      # @return [Boolean] True if the method is registered
+      def method_registered?(method_name)
+        @agent.class.a2a_method_registered?(method_name)
+      end
+
+      ##
+      # Get method definition
+      #
+      # @param method_name [String] The method name
+      # @return [Hash, nil] The method definition or nil if not found
+      def method_definition(method_name)
+        @agent.class.a2a_method_definition(method_name)
+      end
+
+      ##
+      # Get all capabilities from the agent
+      #
+      # @return [Array<A2A::Protocol::Capability>] Array of capabilities
+      def capabilities
+        @agent.class.a2a_capability_registry.all
+      end
+
+      ##
+      # Find capability by method name
+      #
+      # @param method_name [String] The method name
+      # @return [A2A::Protocol::Capability, nil] The capability or nil if not found
+      def find_capability_by_method(method_name)
+        @agent.class.a2a_capability_registry.find_by_method(method_name).first
+      end
+
+      private
+
+      ##
+      # Validate that the agent includes the Agent module
+      def validate_agent!
+        return if @agent.class.included_modules.include?(A2A::Server::Agent)
+
+        raise ArgumentError, "Agent must include A2A::Server::Agent module"
+      end
+
+      ##
+      # Validate a JSON-RPC request
+      #
+      # @param request [A2A::Protocol::Request] The request to validate
+      # @raise [A2A::Errors::InvalidRequest] If the request is invalid
+      def validate_request(request)
+        raise A2A::Errors::InvalidRequest, "Invalid request object" unless request.is_a?(A2A::Protocol::Request)
+
+        if request.method.nil? || (respond_to?(:empty?) && empty?) || (is_a?(String) && strip.empty?)
+          raise A2A::Errors::InvalidRequest,
+                "Method name is required"
+        end
+
+        return if request.params.is_a?(Hash) || request.params.is_a?(Array)
+
+        raise A2A::Errors::InvalidParams, "Parameters must be an object or array"
+      end
+
+      ##
+      # Validate method parameters against capability schema
+      #
+      # @param method_name [String] The method name
+      # @param params [Hash, Array] The method parameters
+      # @raise [A2A::Errors::InvalidParams] If parameters are invalid
+      def validate_method_parameters(method_name, params)
+        capability = find_capability_by_method(method_name)
+        return unless capability # Skip validation if no capability defined
+
+        begin
+          capability.validate_input(params)
+        rescue ArgumentError => e
+          raise A2A::Errors::InvalidParams, "Parameter validation failed: #{e.message}"
+        end
+      end
+
+      ##
+      # Apply the middleware stack to a request
+      #
+      # @param request [A2A::Protocol::Request] The request
+      # @param context [A2A::Server::Context, nil] The request context
+      # @yield Block to execute after middleware
+      # @return [Object] The result from the block
+      def apply_middleware_stack(request, context, &block)
+        # Build the middleware chain from the outside in
+        chain = block
+
+        @middleware_stack.reverse_each do |middleware|
+          current_chain = chain
+          chain = lambda do
+            if middleware.respond_to?(:call)
+              middleware.call(request, context) { current_chain.call }
+            else
+              # Fallback for middleware that don't implement call
+              current_chain.call
+            end
+          end
+        end
+
+        # Execute the chain
+        chain.call
+      end
+    end
+  end
+end