a2a-ruby 1.0.0

data/lib/a2a/server/agent_execution/agent_executor.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require_relative "request_context"
+require_relative "../events/event_queue"
+
+module A2A
+  module Server
+    module AgentExecution
+      ##
+      # Abstract base class for agent executors
+      #
+      # Agent executors contain the core logic of the agent, executing tasks based on
+      # requests and publishing updates to an event queue. This mirrors the Python
+      # AgentExecutor interface.
+      #
+      class AgentExecutor
+        ##
+        # Execute the agent's logic for a given request context
+        #
+        # The agent should read necessary information from the context and
+        # publish Task or Message events, or TaskStatusUpdateEvent/TaskArtifactUpdateEvent
+        # to the event_queue. This method should return once the agent's execution
+        # for this request is complete or yields control (e.g., enters an input-required state).
+        #
+        # @param context [RequestContext] The request context containing the message, task ID, etc.
+        # @param event_queue [A2A::Server::Events::EventQueue] The queue to publish events to
+        # @abstract Subclasses must implement this method
+        def execute(context, event_queue)
+          raise NotImplementedError, "Subclasses must implement execute"
+        end
+
+        ##
+        # Request the agent to cancel an ongoing task
+        #
+        # The agent should attempt to stop the task identified by the task_id
+        # in the context and publish a TaskStatusUpdateEvent with state 'canceled'
+        # to the event_queue.
+        #
+        # @param context [RequestContext] The request context containing the task ID to cancel
+        # @param event_queue [A2A::Server::Events::EventQueue] The queue to publish the cancellation status update to
+        # @abstract Subclasses must implement this method
+        def cancel(context, event_queue)
+          raise NotImplementedError, "Subclasses must implement cancel"
+        end
+
+        protected
+
+        ##
+        # Helper method to publish a task status update event
+        #
+        # @param event_queue [A2A::Server::Events::EventQueue] The event queue
+        # @param task_id [String] The task ID
+        # @param context_id [String] The context ID
+        # @param status [A2A::Types::TaskStatus] The new task status
+        # @param metadata [Hash, nil] Optional metadata
+        def publish_task_status_update(event_queue, task_id, context_id, status, metadata = nil)
+          event_data = A2A::Types::TaskStatusUpdateEvent.new(
+            task_id: task_id,
+            context_id: context_id,
+            status: status,
+            metadata: metadata
+          )
+
+          event = A2A::Server::Events::Event.new(
+            type: "task_status_update",
+            data: event_data
+          )
+
+          event_queue.publish(event)
+        end
+
+        ##
+        # Helper method to publish a task artifact update event
+        #
+        # @param event_queue [A2A::Server::Events::EventQueue] The event queue
+        # @param task_id [String] The task ID
+        # @param context_id [String] The context ID
+        # @param artifact [A2A::Types::Artifact] The artifact
+        # @param append [Boolean] Whether this is an append operation
+        # @param metadata [Hash, nil] Optional metadata
+        def publish_task_artifact_update(event_queue, task_id, context_id, artifact, append = false, metadata = nil)
+          event_data = A2A::Types::TaskArtifactUpdateEvent.new(
+            task_id: task_id,
+            context_id: context_id,
+            artifact: artifact,
+            append: append,
+            metadata: metadata
+          )
+
+          event = A2A::Server::Events::Event.new(
+            type: "task_artifact_update",
+            data: event_data
+          )
+
+          event_queue.publish(event)
+        end
+
+        ##
+        # Helper method to publish a task object
+        #
+        # @param event_queue [A2A::Server::Events::EventQueue] The event queue
+        # @param task [A2A::Types::Task] The task object
+        def publish_task(event_queue, task)
+          event = A2A::Server::Events::Event.new(
+            type: "task",
+            data: task
+          )
+
+          event_queue.publish(event)
+        end
+
+        ##
+        # Helper method to publish a message object
+        #
+        # @param event_queue [A2A::Server::Events::EventQueue] The event queue
+        # @param message [A2A::Types::Message] The message object
+        def publish_message(event_queue, message)
+          event = A2A::Server::Events::Event.new(
+            type: "message",
+            data: message
+          )
+
+          event_queue.publish(event)
+        end
+      end
+
+      ##
+      # Simple agent executor implementation
+      #
+      # A basic implementation that can be used as a starting point for custom agents.
+      # Provides default behavior for task creation and status management.
+      #
+      class SimpleAgentExecutor < AgentExecutor
+        def initialize(agent_card: nil, task_manager: nil)
+          @agent_card = agent_card
+          @task_manager = task_manager
+        end
+
+        ##
+        # Execute a request by creating a task and processing the message
+        #
+        # @param context [RequestContext] The request context
+        # @param event_queue [A2A::Server::Events::EventQueue] The event queue
+        def execute(context, event_queue)
+          # Create or get the task
+          task = ensure_task(context)
+          publish_task(event_queue, task)
+
+          # Update task to working state
+          working_status = A2A::Types::TaskStatus.new(
+            state: A2A::Types::TASK_STATE_WORKING,
+            message: "Processing request",
+            updated_at: Time.now.utc.iso8601
+          )
+
+          publish_task_status_update(
+            event_queue,
+            task.id,
+            task.context_id,
+            working_status
+          )
+
+          # Process the message (delegate to subclass)
+          result = process_message(context.message, task, context)
+
+          # Update task with result
+          completed_status = A2A::Types::TaskStatus.new(
+            state: A2A::Types::TASK_STATE_COMPLETED,
+            result: result,
+            updated_at: Time.now.utc.iso8601
+          )
+
+          publish_task_status_update(
+            event_queue,
+            task.id,
+            task.context_id,
+            completed_status
+          )
+        rescue StandardError => e
+          # Handle errors by updating task status
+          if task
+            error_status = A2A::Types::TaskStatus.new(
+              state: A2A::Types::TASK_STATE_FAILED,
+              error: { message: e.message, type: e.class.name },
+              updated_at: Time.now.utc.iso8601
+            )
+
+            publish_task_status_update(
+              event_queue,
+              task.id,
+              task.context_id,
+              error_status
+            )
+          end
+
+          raise
+        end
+
+        ##
+        # Cancel a task by updating its status
+        #
+        # @param context [RequestContext] The request context
+        # @param event_queue [A2A::Server::Events::EventQueue] The event queue
+        def cancel(context, event_queue)
+          task_id = context.task_id
+          return unless task_id
+
+          canceled_status = A2A::Types::TaskStatus.new(
+            state: A2A::Types::TASK_STATE_CANCELED,
+            message: "Task canceled by request",
+            updated_at: Time.now.utc.iso8601
+          )
+
+          publish_task_status_update(
+            event_queue,
+            task_id,
+            context.context_id,
+            canceled_status
+          )
+        end
+
+        protected
+
+        ##
+        # Process a message (to be implemented by subclasses)
+        #
+        # @param message [A2A::Types::Message] The message to process
+        # @param task [A2A::Types::Task] The associated task
+        # @param context [RequestContext] The request context
+        # @return [Object] Processing result
+        def process_message(message, _task, _context)
+          # Default implementation just echoes the message
+          {
+            echo: message.to_h,
+            processed_at: Time.now.utc.iso8601
+          }
+        end
+
+        private
+
+        ##
+        # Ensure a task exists for the request context
+        #
+        # @param context [RequestContext] The request context
+        # @return [A2A::Types::Task] The task object
+        def ensure_task(context)
+          if context.task_id && @task_manager
+            # Try to get existing task
+            existing_task = begin
+              @task_manager.get_task(context.task_id)
+            rescue StandardError
+              nil
+            end
+            return existing_task if existing_task
+          end
+
+          # Create new task
+          task_id = context.task_id || SecureRandom.uuid
+          context_id = context.context_id || SecureRandom.uuid
+
+          A2A::Types::Task.new(
+            id: task_id,
+            context_id: context_id,
+            status: A2A::Types::TaskStatus.new(
+              state: A2A::Types::TASK_STATE_SUBMITTED,
+              message: "Task created",
+              updated_at: Time.now.utc.iso8601
+            ),
+            history: context.message ? [context.message] : [],
+            metadata: {
+              created_at: Time.now.utc.iso8601,
+              executor: self.class.name
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/a2a/server/agent_execution/request_context.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module A2A
+  module Server
+    module AgentExecution
+      ##
+      # Request context for agent execution
+      #
+      # Contains all the information needed for an agent to process a request,
+      # including the message, task ID, context ID, and server call context.
+      #
+      class RequestContext
+        attr_reader :message, :task_id, :context_id, :server_context, :metadata
+
+        ##
+        # Initialize a new request context
+        #
+        # @param message [A2A::Types::Message, nil] The message that initiated the request
+        # @param task_id [String, nil] The task ID if continuing an existing task
+        # @param context_id [String, nil] The context ID for the conversation
+        # @param server_context [A2A::Server::Context, nil] The server call context
+        # @param metadata [Hash] Additional metadata for the request
+        def initialize(message: nil, task_id: nil, context_id: nil, server_context: nil, metadata: {})
+          @message = message
+          @task_id = task_id
+          @context_id = context_id || message&.context_id
+          @server_context = server_context
+          @metadata = metadata.dup
+        end
+
+        ##
+        # Check if this is a new task (no task_id provided)
+        #
+        # @return [Boolean] True if this is a new task
+        def new_task?
+          @task_id.nil?
+        end
+
+        ##
+        # Check if this is continuing an existing task
+        #
+        # @return [Boolean] True if continuing an existing task
+        def continuing_task?
+          !@task_id.nil?
+        end
+
+        ##
+        # Check if this request has a message
+        #
+        # @return [Boolean] True if a message is present
+        def has_message?
+          !@message.nil?
+        end
+
+        ##
+        # Get the user from the server context if available
+        #
+        # @return [Object, nil] The user object or nil
+        def user
+          @server_context&.user
+        end
+
+        ##
+        # Check if the request is authenticated
+        #
+        # @return [Boolean] True if authenticated
+        def authenticated?
+          @server_context&.authenticated? || false
+        end
+
+        ##
+        # Get authentication data for a specific scheme
+        #
+        # @param scheme [String] The authentication scheme
+        # @return [Object, nil] Authentication data or nil
+        def authentication(scheme)
+          @server_context&.get_authentication(scheme)
+        end
+
+        ##
+        # Get metadata value
+        #
+        # @param key [String, Symbol] The metadata key
+        # @return [Object, nil] The metadata value or nil
+        def get_metadata(key)
+          @metadata[key] || @server_context&.get_metadata(key)
+        end
+
+        ##
+        # Set metadata value
+        #
+        # @param key [String, Symbol] The metadata key
+        # @param value [Object] The metadata value
+        def set_metadata(key, value)
+          @metadata[key] = value
+        end
+
+        ##
+        # Convert to hash representation
+        #
+        # @return [Hash] Hash representation of the context
+        def to_h
+          {
+            message: @message&.to_h,
+            task_id: @task_id,
+            context_id: @context_id,
+            metadata: @metadata,
+            authenticated: authenticated?,
+            user: user&.to_s
+          }
+        end
+
+        ##
+        # Create a copy of this context with modifications
+        #
+        # @param **changes [Hash] Changes to apply
+        # @return [RequestContext] New context with changes applied
+        def with(**changes)
+          RequestContext.new(
+            message: changes[:message] || @message,
+            task_id: changes[:task_id] || @task_id,
+            context_id: changes[:context_id] || @context_id,
+            server_context: changes[:server_context] || @server_context,
+            metadata: @metadata.merge(changes[:metadata] || {})
+          )
+        end
+      end
+
+      ##
+      # Builder for creating request contexts from various inputs
+      #
+      # Provides a convenient way to build RequestContext objects from
+      # different types of input (JSON-RPC requests, HTTP requests, etc.)
+      #
+      class RequestContextBuilder
+        ##
+        # Build a request context from a message send request
+        #
+        # @param params [Hash] The message send parameters
+        # @param server_context [A2A::Server::Context, nil] The server context
+        # @return [RequestContext] The built request context
+        def self.from_message_send(params, server_context = nil)
+          message_data = params["message"] || params[:message]
+          task_id = params["taskId"] || params[:task_id]
+          context_id = params["contextId"] || params[:context_id]
+
+          message = if message_data.is_a?(A2A::Types::Message)
+                      message_data
+                    elsif message_data.is_a?(Hash)
+                      A2A::Types::Message.from_h(message_data)
+                    else
+                      nil
+                    end
+
+          # Extract context_id from message if not provided in params
+          context_id ||= message&.context_id
+
+          RequestContext.new(
+            message: message,
+            task_id: task_id,
+            context_id: context_id,
+            server_context: server_context,
+            metadata: {
+              request_type: "message_send",
+              params: params
+            }
+          )
+        end
+
+        ##
+        # Build a request context from a task operation request
+        #
+        # @param params [Hash] The task operation parameters
+        # @param server_context [A2A::Server::Context, nil] The server context
+        # @param operation [String] The operation type (e.g., 'get', 'cancel')
+        # @return [RequestContext] The built request context
+        def self.from_task_operation(params, server_context = nil, operation: "get")
+          task_id = params["id"] || params[:id] || params["taskId"] || params[:task_id]
+          context_id = params["contextId"] || params[:context_id]
+
+          RequestContext.new(
+            task_id: task_id,
+            context_id: context_id,
+            server_context: server_context,
+            metadata: {
+              request_type: "task_#{operation}",
+              params: params
+            }
+          )
+        end
+
+        ##
+        # Build a request context from a streaming message request
+        #
+        # @param params [Hash] The streaming message parameters
+        # @param server_context [A2A::Server::Context, nil] The server context
+        # @return [RequestContext] The built request context
+        def self.from_streaming_message(params, server_context = nil)
+          context = from_message_send(params, server_context)
+          context.set_metadata(:streaming, true)
+          context.set_metadata(:request_type, "message_stream")
+          context
+        end
+
+        ##
+        # Build a request context from a task resubscription request
+        #
+        # @param params [Hash] The resubscription parameters
+        # @param server_context [A2A::Server::Context, nil] The server context
+        # @return [RequestContext] The built request context
+        def self.from_task_resubscription(params, server_context = nil)
+          context = from_task_operation(params, server_context, operation: "resubscribe")
+          context.set_metadata(:streaming, true)
+          context
+        end
+      end
+    end
+  end
+end