Class: Agentic::Task

Inherits:
Object
  • Object
show all
Includes:
Observable
Defined in:
lib/agentic/task.rb

Overview

Represents an individual task to be executed by an agent

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Observable

#add_observer, #count_observers, #delete_observer, #delete_observers, #notify_observers

Constructor Details

#initialize(description:, agent_spec:, input: {}, output_schema_name: nil) ⇒ Task

Initializes a new task

Parameters:

  • description (String) —

    Human-readable description of the task

  • agent_spec (Hash, AgentSpecification) —

    Requirements for the agent that will execute this task

  • input (Hash) (defaults to: {}) —

    Input data for the task

  • output_schema_name (Symbol, nil) (defaults to: nil) —

    Name of the output schema to use for structured output



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/agentic/task.rb', line 33

def initialize(description:, agent_spec:, input: {}, output_schema_name: nil)
  @id = SecureRandom.uuid
  @description = description

  # Convert agent_spec to AgentSpecification if it's a hash
  @agent_spec = if agent_spec.is_a?(Hash)
    AgentSpecification.new(
      name: agent_spec["name"],
      description: agent_spec["description"] || "",
      instructions: agent_spec["instructions"]
    )
  else
    agent_spec
  end

  @input = input
  @output = nil
  @failure = nil
  @status = :pending
  @ready_to_execute = nil
  @output_schema_name = output_schema_name
end

Instance Attribute Details

#agent_spec ⇒ Hash (readonly)

Requirements for the agent that will execute this task

Returns:

  • (Hash) —

    the current value of agent_spec



21
22
23
 
# File 'lib/agentic/task.rb', line 21

def agent_spec
  @agent_spec
end

#description ⇒ String (readonly)

Human-readable description of the task

Returns:

  • (String) —

    the current value of description



21
22
23
 
# File 'lib/agentic/task.rb', line 21

def description
  @description
end

#failure ⇒ TaskFailure? (readonly)

Failure information if the task failed, nil otherwise

Returns:



21
22
23
 
# File 'lib/agentic/task.rb', line 21

def failure
  @failure
end

#id ⇒ String (readonly)

Unique identifier for the task

Returns:

  • (String) —

    the current value of id



21
22
23
 
# File 'lib/agentic/task.rb', line 21

def id
  @id
end

#input ⇒ Hash (readonly)

Input data for the task

Returns:

  • (Hash) —

    the current value of input



21
22
23
 
# File 'lib/agentic/task.rb', line 21

def input
  @input
end

#output ⇒ Hash? (readonly)

Output produced by the task, nil if not yet executed

Returns:

  • (Hash, nil) —

    the current value of output



21
22
23
 
# File 'lib/agentic/task.rb', line 21

def output
  @output
end

#output_schema_name ⇒ Object

Returns the value of attribute output_schema_name.



25
26
27
 
# File 'lib/agentic/task.rb', line 25

def output_schema_name
  @output_schema_name
end

#ready_to_execute ⇒ Boolean? (readonly)

Flag indicating if the task is ready to be executed

Returns:

  • (Boolean, nil) —

    the current value of ready_to_execute



21
22
23
 
# File 'lib/agentic/task.rb', line 21

def ready_to_execute
  @ready_to_execute
end

#retry_count ⇒ Object

Returns the value of attribute retry_count.



25
26
27
 
# File 'lib/agentic/task.rb', line 25

def retry_count
  @retry_count
end

#status ⇒ Symbol (readonly)

Current status of the task (:pending, :in_progress, :completed, :failed)

Returns:

  • (Symbol) —

    the current value of status



21
22
23
 
# File 'lib/agentic/task.rb', line 21

def status
  @status
end

Class Method Details

.from_definition(definition, input = {}) ⇒ Task

Creates a task from a TaskDefinition

Parameters:

  • definition (TaskDefinition) —

    The task definition

  • input (Hash) (defaults to: {}) —

    Input data for the task

Returns:

  • (Task) —

    A new task instance



60
61
62
63
64
65
66
 
# File 'lib/agentic/task.rb', line 60

def self.from_definition(definition, input = {})
  new(
    description: definition.description,
    agent_spec: definition.agent,
    input: input
  )
end

Instance Method Details

#has_output_schema? ⇒ Boolean

Checks if this task has a structured output schema

Returns:

  • (Boolean) —

    True if task has an output schema



157
158
159
 
# File 'lib/agentic/task.rb', line 157

def has_output_schema?
  !@output_schema_name.nil? && TaskOutputSchemas.exists?(@output_schema_name)
end

#output_schema ⇒ Agentic::StructuredOutputs::Schema?

Returns the output schema for this task

Returns:



150
151
152
153
 
# File 'lib/agentic/task.rb', line 150

def output_schema
  return nil unless @output_schema_name
  TaskOutputSchemas.get(@output_schema_name)
end

#perform(agent) ⇒ TaskResult

Executes the task using the given agent

Parameters:

  • agent (Agent) —

    The agent that will execute this task

Returns:

  • (TaskResult) —

    The result of the task execution



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/agentic/task.rb', line 71

def perform(agent)
  old_status = @status
  @status = :in_progress

  notify_observers(:status_change, old_status, @status)

  begin
    @output = if has_output_schema?
      agent.execute_with_schema(build_prompt, output_schema)
    else
      agent.execute(build_prompt)
    end
    old_status = @status
    @status = :completed

    notify_observers(:status_change, old_status, @status)

    TaskResult.new(
      task_id: @id,
      success: true,
      output: @output
    )
  rescue => e
    @failure = TaskFailure.new(
      message: e.message,
      type: e.class.name,
      context: {
        backtrace: e.backtrace&.first(10),
        agent_id: agent.respond_to?(:id) ? agent.id : nil
      }
    )

    old_status = @status
    @status = :failed

    notify_observers(:status_change, old_status, @status)
    notify_observers(:failure_occurred, @failure)

    Agentic.logger.error("Task execution failed: #{e.message}")

    TaskResult.new(
      task_id: @id,
      success: false,
      failure: @failure
    )
  end
end

#retry(agent) ⇒ TaskResult

Retries a failed task

Parameters:

  • agent (Agent) —

    The agent that will execute this task

Returns:

  • (TaskResult) —

    The result of the task execution

Raises:

  • (StandardError) —

    If the task is not in a failed state



123
124
125
126
127
128
129
130
131
132
 
# File 'lib/agentic/task.rb', line 123

def retry(agent)
  raise "Cannot retry a task that is not in a failed state" unless @status == :failed

  old_status = @status
  @status = :retrying

  notify_observers(:status_change, old_status, @status)

  perform(agent)
end

#set_output_schema(schema_name) ⇒ Object

Sets the output schema for this task

Parameters:

  • schema_name (Symbol) —

    The name of the schema to use



163
164
165
 
# File 'lib/agentic/task.rb', line 163

def set_output_schema(schema_name)
  @output_schema_name = schema_name
end

#to_h ⇒ Hash

Returns a serializable representation of the task

Returns:

  • (Hash) —

    The task as a hash



136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/agentic/task.rb', line 136

def to_h
  {
    id: @id,
    description: @description,
    agent_spec: @agent_spec.is_a?(AgentSpecification) ? @agent_spec.to_h : @agent_spec,
    input: @input,
    output: @output,
    status: @status,
    failure: @failure&.to_h
  }
end