conductor_ruby 0.1.0 → 0.1.1

data/lib/conductor/agents/agent.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'tool'
+require_relative 'tools'
+require_relative 'guardrail'
+require_relative 'termination'
+require_relative 'handoff'
+require_relative 'callback_handler'
+require_relative 'memory'
+require_relative 'prompt_template'
+
+module Conductor
+  module Agents
+    # Multi-agent orchestration strategies (wire values are lowercase snake_case)
+    module Strategy
+      HANDOFF = 'handoff'
+      SEQUENTIAL = 'sequential'
+      PARALLEL = 'parallel'
+      ROUTER = 'router'
+      ROUND_ROBIN = 'round_robin'
+      RANDOM = 'random'
+      SWARM = 'swarm'
+      MANUAL = 'manual'
+      PLAN_EXECUTE = 'plan_execute'
+      ALL = [HANDOFF, SEQUENTIAL, PARALLEL, ROUTER, ROUND_ROBIN, RANDOM, SWARM, MANUAL, PLAN_EXECUTE].freeze
+
+      def self.normalize(value)
+        s = value.to_s.downcase
+        raise ConfigurationError, "invalid strategy #{value.inspect}; use one of #{ALL.join(', ')}" unless ALL.include?(s)
+
+        s
+      end
+    end
+
+    # An agent definition. Nothing here talks to the server: ConfigSerializer turns the
+    # tree into agentConfig and AgentRuntime runs it (call_sync / call_async delegate to
+    # Conductor::Agents.runtime).
+    #
+    #   agent = Agent.new(name: 'weather', model: 'openai/gpt-4o', instructions: 'Answer weather questions.')
+    #   agent.add_tool :get_weather
+    #   puts agent.call_sync('Weather in Lisbon?')
+    class Agent
+      NAME_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_-]*\z/
+
+      attr_reader :name, :tools, :agents, :guardrails, :handoffs, :callbacks, :credentials, :callback_procs
+      attr_accessor :model, :instructions, :router, :output_type, :memory, :termination,
+                    :max_turns, :max_tokens, :timeout_seconds, :temperature, :stateful,
+                    :metadata, :description, :external, :base_url, :prefill_tools, :approval_handler,
+                    :planner, :fallback, :fallback_max_turns, :planner_context
+
+      # @param name [String] ^[a-zA-Z_][a-zA-Z0-9_-]*$
+      # @param model [String, nil] "provider/model"; the left side is the server integration name
+      # @param instructions [String, PromptTemplate, Proc]
+      # @param strategy [Symbol, String] how sub-agents are orchestrated (default :handoff)
+      def initialize(name:, model: nil, instructions: '', tools: [], agents: [], strategy: nil, router: nil,
+                     output_type: nil, guardrails: [], memory: nil, termination: nil, handoffs: [], callbacks: [],
+                     credentials: [], max_turns: 25, max_tokens: nil, timeout_seconds: 0, temperature: nil,
+                     stateful: false, metadata: nil, description: nil, external: false, base_url: nil,
+                     prefill_tools: [], planner: nil, fallback: nil, fallback_max_turns: nil, planner_context: [])
+        @name = name.to_s
+        raise ConfigurationError, "invalid agent name #{name.inspect}: must match #{NAME_PATTERN.source}" unless NAME_PATTERN.match?(@name)
+        raise ConfigurationError, 'max_turns must be >= 1' unless max_turns.is_a?(Integer) && max_turns >= 1
+
+        @model = model
+        @instructions = instructions
+        @tools = []
+        @agents = []
+        @strategy = strategy.nil? ? nil : Strategy.normalize(strategy)
+        @router = router
+        @output_type = output_type
+        @guardrails = Array(guardrails)
+        @memory = memory
+        @termination = termination
+        @handoffs = Array(handoffs)
+        @callbacks = Array(callbacks)
+        @callback_procs = Hash.new { |h, k| h[k] = [] }
+        @credentials = Array(credentials).map(&:to_s).uniq
+        @max_turns = max_turns
+        @max_tokens = max_tokens
+        @timeout_seconds = timeout_seconds
+        @temperature = temperature
+        @stateful = stateful ? true : false
+        @metadata = metadata
+        @description = description
+        @external = external ? true : false
+        @base_url = base_url
+        @prefill_tools = Array(prefill_tools)
+        @approval_handler = nil
+        @planner = planner
+        @fallback = fallback
+        @fallback_max_turns = fallback_max_turns
+        @planner_context = Array(planner_context)
+        [planner, fallback].compact.each do |child|
+          raise ConfigurationError, 'planner and fallback must be Agents' unless child.is_a?(Agent)
+        end
+        raise ConfigurationError, 'strategy: :plan_execute requires planner:' if @strategy == Strategy::PLAN_EXECUTE && planner.nil?
+        raise ConfigurationError, 'planner and fallback require strategy: :plan_execute' if (planner || fallback) && @strategy != Strategy::PLAN_EXECUTE
+        raise ConfigurationError, 'strategy: :plan_execute requires tools:' if @strategy == Strategy::PLAN_EXECUTE && Array(tools).empty?
+
+        Array(tools).each { |t| add_tool(t) }
+        Array(agents).each { |a| add_agent(a) }
+        raise ConfigurationError, 'strategy: :router requires router:' if @strategy == Strategy::ROUTER && @router.nil?
+      end
+
+      # ── Strategy ──────────────────────────────────────────────────────
+
+      # @return [String] effective strategy (default handoff)
+      def strategy
+        @strategy || Strategy::HANDOFF
+      end
+
+      def strategy=(value)
+        @strategy = value.nil? ? nil : Strategy.normalize(value)
+      end
+
+      # True when the user set a strategy explicitly
+      def strategy_set?
+        !@strategy.nil?
+      end
+
+      # ── Tools ─────────────────────────────────────────────────────────
+
+      # Give the agent a tool.
+      # @param tool [Symbol, String, Tool, Module, Class, Agent] a tool name defined with
+      #   `tool def`, a Tool, a module that `extend Conductor::Agents::Tools`, or another
+      #   Agent (wrapped as an agent tool)
+      # @param credentials [Array<String>, nil] secret names when the scanner cannot see them
+      # @return [self]
+      def add_tool(tool, credentials: nil)
+        resolve_tool_defs(tool).each do |tool_def|
+          td = credentials ? tool_def.dup.tap { |d| d.credentials = tool_def.credentials.dup } : tool_def
+          td.add_credentials(*credentials) if credentials
+          raise ConfigurationError, "duplicate tool name #{td.name.inspect} on agent #{@name}" if @tools.any? { |t| t.name == td.name }
+
+          @tools << td
+        end
+        self
+      end
+
+      def add_tools(*tools)
+        tools.flatten.each { |t| add_tool(t) }
+        self
+      end
+
+      # @return [Tool, nil]
+      def tool(name)
+        @tools.find { |t| t.name == name.to_s }
+      end
+
+      # ── Team ──────────────────────────────────────────────────────────
+
+      # Add a member agent (same as agents: in the constructor)
+      def add_agent(agent)
+        raise ConfigurationError, "add_agent expects an Agent, got #{agent.class}" unless agent.is_a?(Agent)
+        raise ConfigurationError, "duplicate sub-agent name #{agent.name.inspect} under #{@name}" if @agents.any? { |a| a.name == agent.name }
+
+        @agents << agent
+        self
+      end
+
+      def add_agents(*agents)
+        agents.flatten.each { |a| add_agent(a) }
+        self
+      end
+
+      # Hand off to +agent+ when this agent's output mentions +on+ (String), or when the
+      # block/proc given as +on+ returns true.
+      def hands_off_to(agent, on:)
+        handoff = if on.respond_to?(:call)
+                    Handoff::OnCondition.new(target: agent, condition: on)
+                  else
+                    Handoff::OnTextMention.new(target: agent, text: on)
+                  end
+        @handoffs << handoff
+        self
+      end
+
+      def add_handoff(handoff)
+        @handoffs << handoff
+        self
+      end
+
+      # Sequential pipeline: a >> b >> c
+      def >>(other)
+        raise ConfigurationError, ">> expects an Agent, got #{other.class}" unless other.is_a?(Agent)
+
+        left = sequential_pipeline? ? @agents : [self]
+        right = other.sequential_pipeline? ? other.agents : [other]
+        members = left + right
+        Agent.new(name: members.map(&:name).join('_'), model: @model || other.model,
+                  agents: members, strategy: Strategy::SEQUENTIAL)
+      end
+
+      def sequential_pipeline?
+        @strategy == Strategy::SEQUENTIAL && !@agents.empty?
+      end
+
+      # ── Guardrails / termination sugar ────────────────────────────────
+
+      # Scrub these words from the output before anyone sees it
+      def redact(words, name: "#{@name}_redact")
+        patterns = Array(words).map { |w| w.is_a?(Regexp) ? w : Regexp.escape(w.to_s) }
+        @guardrails << RegexGuardrail.new(patterns, mode: :block, position: :output, on_fail: :fix, name: name)
+        self
+      end
+
+      def add_guardrail(guardrail)
+        @guardrails << guardrail
+        self
+      end
+
+      # Stop when the output contains +text+
+      def stop_when(text, case_sensitive: false)
+        add_termination(Termination::TextMention.new(text, case_sensitive: case_sensitive))
+      end
+
+      # Stop after +messages+ messages
+      def stop_after(messages:)
+        add_termination(Termination::MaxMessage.new(messages))
+      end
+
+      def add_termination(condition)
+        @termination = @termination ? (@termination | condition) : condition
+        self
+      end
+
+      # ── Callbacks ─────────────────────────────────────────────────────
+
+      def add_callback(handler)
+        @callbacks << handler
+        self
+      end
+
+      # Register a block for a callback position (before_model, after_model, ...)
+      def callback(position, &block)
+        pos = position.to_s
+        raise ConfigurationError, "unknown callback position #{position.inspect}" unless CallbackHandler::POSITIONS.include?(pos)
+
+        @callback_procs[pos] << block
+        self
+      end
+
+      # Callables for +position+, or nil when nothing is registered
+      def callback_chain(position, logger: nil)
+        CallbackHandler.chain(position, @callbacks, @callback_procs[position.to_s], logger: logger)
+      end
+
+      # Positions with at least one handler or proc
+      def callback_positions
+        CallbackHandler::POSITIONS.reject { |p| callback_chain(p).nil? }
+      end
+
+      # ── Approval ──────────────────────────────────────────────────────
+
+      # Decide approval-required tool calls: the block receives an ApprovalRequest
+      def on_approval(&block)
+        @approval_handler = block
+        self
+      end
+
+      # ── Credentials ───────────────────────────────────────────────────
+
+      def add_credentials(*names)
+        @credentials = (@credentials + names.flatten.map(&:to_s)).uniq
+        self
+      end
+
+      # ── Execution (delegates to the default runtime) ──────────────────
+
+      # Run and block until the answer is ready
+      # @return [String]
+      def call_sync(prompt, session_id: nil, **options)
+        Conductor::Agents.runtime.call_sync(self, prompt, session_id: session_id, **options)
+      end
+
+      # Run in the background; returns an Execution. The block (if given) receives the answer.
+      def call_async(prompt, session_id: nil, **options, &on_done)
+        Conductor::Agents.runtime.call_async(self, prompt, session_id: session_id, **options, &on_done)
+      end
+
+      # ── Introspection ─────────────────────────────────────────────────
+
+      # Every agent in the tree (self first), including router, planner-style children and agent tools
+      def all_agents
+        list = [self]
+        @agents.each { |a| list.concat(a.all_agents) }
+        [@router, @planner, @fallback].each { |a| list.concat(a.all_agents) if a.is_a?(Agent) }
+        @tools.each do |t|
+          child = t.config['agent'] if t.tool_type == ToolType::AGENT_TOOL
+          list.concat(child.all_agents) if child.is_a?(Agent)
+        end
+        list.uniq
+      end
+
+      # True when this agent or anything under it is stateful
+      def stateful_tree?
+        all_agents.any? { |a| a.stateful || a.tools.any?(&:stateful) }
+      end
+
+      def to_s
+        "#<Conductor::Agents::Agent #{@name} model=#{@model.inspect} tools=#{@tools.size} agents=#{@agents.size}>"
+      end
+      alias inspect to_s
+
+      private
+
+      def resolve_tool_defs(tool)
+        case tool
+        when Tool then [tool]
+        when Symbol, String
+          [Tools.lookup(tool) || raise(ConfigurationError, "no tool named #{tool.inspect}; define it with `tool def #{tool}(...)` first")]
+        when Agent then [Tool.agent(tool)]
+        when Module
+          raise ConfigurationError, "#{tool} has no tools; use `extend Conductor::Agents::Tools` and `tool def ...`" unless tool.respond_to?(:tool_defs)
+
+          tool.tool_defs
+        else
+          raise ConfigurationError, "cannot use #{tool.inspect} as a tool"
+        end
+      end
+    end
+  end
+end

data/lib/conductor/agents/callback_handler.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Conductor
+  module Agents
+    # Lifecycle hooks. Subclass and override any method; each runs as a worker task
+    # named <agent>_<position> that the server schedules at that point.
+    #
+    #   class Timing < Conductor::Agents::CallbackHandler
+    #     def on_model_start(messages: nil, **) = (@t0 = Time.now; nil)
+    #     def on_model_end(llm_result: nil, **) = (puts Time.now - @t0; nil)
+    #   end
+    #
+    # Return nil to continue to the next handler, or a non-empty Hash to short-circuit and
+    # hand that Hash to the server as an override.
+    class CallbackHandler
+      POSITION_TO_METHOD = {
+        'before_agent' => :on_agent_start,
+        'after_agent' => :on_agent_end,
+        'before_model' => :on_model_start,
+        'after_model' => :on_model_end,
+        'before_tool' => :on_tool_start,
+        'after_tool' => :on_tool_end
+      }.freeze
+
+      POSITIONS = POSITION_TO_METHOD.keys.freeze
+
+      def on_agent_start(**_kwargs); end
+      def on_agent_end(**_kwargs); end
+      def on_model_start(**_kwargs); end
+      def on_model_end(**_kwargs); end
+      def on_tool_start(**_kwargs); end
+      def on_tool_end(**_kwargs); end
+
+      # True when this handler overrides the hook for +position+
+      def handles?(position)
+        method_name = POSITION_TO_METHOD.fetch(position.to_s)
+        self.class.instance_method(method_name).owner != CallbackHandler
+      end
+
+      class << self
+        # Build one callable for +position+ from a list of handlers (and optional procs),
+        # or nil when nothing is registered. First non-empty Hash wins; errors are logged.
+        # @return [Proc, nil]
+        def chain(position, handlers, procs = [], logger: nil)
+          position = position.to_s
+          method_name = POSITION_TO_METHOD.fetch(position)
+          active = Array(handlers).select { |h| h.handles?(position) }
+          callables = Array(procs) + active.map { |h| h.method(method_name) }
+          return nil if callables.empty?
+
+          lambda do |**kwargs|
+            callables.each do |callable|
+              result = callable.call(**kwargs)
+              return result if result.is_a?(Hash) && !result.empty?
+            rescue StandardError => e
+              logger&.error("callback #{position} failed: #{e.class}: #{e.message}")
+            end
+            {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/conductor/agents/config_serializer.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative 'agent'
+
+module Conductor
+  module Agents
+    # Serializes an Agent tree into the agentConfig JSON the server compiles. Same shape
+    # as the Python SDK's AgentConfigSerializer: camelCase keys, nils dropped, strategy only
+    # on agents with sub-agents, agent credentials at the top level and tool credentials
+    # under config.credentials.
+    #
+    # Two Ruby-specific rules:
+    # - a team parent with no model inherits the first member's model (the server requires
+    #   a model on every agent config);
+    # - members that declared hands_off_to make a team with no explicit strategy a swarm,
+    #   and their handoffs are hoisted to the team, which is where the server reads them.
+    class ConfigSerializer
+      def self.serialize(agent)
+        new.serialize(agent)
+      end
+
+      # @param agent [Agent]
+      # @return [Hash] agentConfig
+      def serialize(agent)
+        serialize_agent(agent)
+      end
+
+      private
+
+      def serialize_agent(agent)
+        has_sub_agents = !agent.agents.empty?
+        strategy, handoffs = effective_strategy_and_handoffs(agent)
+
+        config = {
+          'name' => agent.name,
+          'model' => effective_model(agent),
+          'baseUrl' => agent.base_url,
+          'strategy' => has_sub_agents || agent.planner || agent.fallback ? strategy : nil,
+          'maxTurns' => agent.max_turns,
+          'timeoutSeconds' => agent.timeout_seconds,
+          'external' => agent.external,
+          'description' => agent.description,
+          'instructions' => serialize_instructions(agent.instructions)
+        }
+        config['tools'] = agent.tools.map { |t| serialize_tool(t, agent_stateful: agent.stateful) } unless agent.tools.empty?
+        config['agents'] = agent.agents.map { |a| serialize_agent(a) } if has_sub_agents
+        config.merge!(serialize_plan(agent))
+        config['router'] = serialize_router(agent) unless agent.router.nil?
+        config['outputType'] = serialize_output_type(agent.output_type) unless agent.output_type.nil?
+        config['guardrails'] = agent.guardrails.map { |g| serialize_guardrail(g) } unless agent.guardrails.empty?
+        config['memory'] = serialize_memory(agent.memory) if agent.memory && !agent.memory.empty?
+        config.merge!(serialize_scalars(agent))
+        config['termination'] = serialize_termination(agent.termination) unless agent.termination.nil?
+        config['handoffs'] = handoffs.map { |h| serialize_handoff(h, agent.name) } unless handoffs.empty?
+        config.merge!(serialize_extras(agent))
+        config.compact
+      end
+
+      def serialize_scalars(agent)
+        {
+          'maxTokens' => agent.max_tokens,
+          'temperature' => agent.temperature
+        }
+      end
+
+      def serialize_plan(agent)
+        config = {}
+        config['planner'] = serialize_agent(agent.planner) if agent.planner
+        config['fallback'] = serialize_agent(agent.fallback) if agent.fallback
+        config['fallbackMaxTurns'] = agent.fallback_max_turns unless agent.fallback_max_turns.nil?
+        config['plannerContext'] = agent.planner_context unless agent.planner_context.empty?
+        config
+      end
+
+      def serialize_extras(agent)
+        extras = {}
+        extras['metadata'] = agent.metadata if agent.metadata && !agent.metadata.empty?
+        callbacks = agent.callback_positions.map { |p| { 'position' => p, 'taskName' => "#{agent.name}_#{p}" } }
+        extras['callbacks'] = callbacks unless callbacks.empty?
+        extras['prefillTools'] = agent.prefill_tools.map(&:to_h) unless agent.prefill_tools.empty?
+        extras['credentials'] = agent.credentials unless agent.credentials.empty?
+        extras
+      end
+
+      def effective_model(agent)
+        return agent.model if agent.model && !agent.model.to_s.empty?
+        return nil if agent.external
+
+        inherited = (agent.agents + [agent.planner, agent.fallback].compact).map { |a| effective_model(a) }.compact.first
+        return inherited if inherited
+
+        raise ConfigurationError,
+              "agent #{agent.name.inspect} has no model: pass model: 'provider/model' (the server requires one)"
+      end
+
+      # Swarm hoisting: members with hands_off_to make the parent a swarm unless the user chose a strategy
+      def effective_strategy_and_handoffs(agent)
+        member_handoffs = agent.agents.flat_map(&:handoffs)
+        return [agent.strategy, agent.handoffs] if member_handoffs.empty?
+
+        strategy = agent.strategy_set? ? agent.strategy : Strategy::SWARM
+        return [strategy, agent.handoffs] unless strategy == Strategy::SWARM
+
+        hoisted = (agent.handoffs + member_handoffs).uniq { |h| [h.class, h.target, h.respond_to?(:text) ? h.text : nil] }
+        [strategy, hoisted]
+      end
+
+      def serialize_instructions(instructions)
+        case instructions
+        when PromptTemplate then instructions.to_h
+        when Proc, Method then instructions.call
+        when nil then nil
+        else
+          s = instructions.to_s
+          s.empty? ? nil : s
+        end
+      end
+
+      def serialize_tool(tool_def, agent_stateful: false)
+        result = {
+          'name' => tool_def.name,
+          'description' => tool_def.description,
+          'inputSchema' => tool_def.input_schema,
+          'toolType' => tool_def.tool_type
+        }
+        result['outputSchema'] = tool_def.output_schema unless tool_def.output_schema.nil? || tool_def.output_schema.empty?
+        result['approvalRequired'] = true if tool_def.approval_required
+        result['stateful'] = true if agent_stateful || tool_def.stateful
+        result['timeoutSeconds'] = tool_def.timeout_seconds unless tool_def.timeout_seconds.nil?
+        result['maxCalls'] = tool_def.max_calls unless tool_def.max_calls.nil?
+
+        unless tool_def.config.empty?
+          config = tool_def.config.transform_keys(&:to_s)
+          config['agentConfig'] = serialize_agent(config.delete('agent')) if tool_def.tool_type == ToolType::AGENT_TOOL && config.key?('agent')
+          result['config'] = config
+        end
+
+        result['guardrails'] = tool_def.guardrails.map { |g| serialize_guardrail(g) } unless tool_def.guardrails.empty?
+
+        unless tool_def.credentials.empty?
+          result['config'] ||= {}
+          result['config']['credentials'] = tool_def.credentials
+        end
+
+        result
+      end
+
+      def serialize_guardrail(guardrail)
+        result = {
+          'name' => guardrail.name,
+          'position' => guardrail.position,
+          'onFail' => guardrail.on_fail,
+          'maxRetries' => guardrail.max_retries,
+          'guardrailType' => guardrail.guardrail_type
+        }
+        case guardrail
+        when RegexGuardrail
+          result['patterns'] = guardrail.pattern_strings
+          result['mode'] = guardrail.mode
+          result['message'] = guardrail.message if guardrail.message
+        when LlmGuardrail
+          result['model'] = guardrail.model
+          result['policy'] = guardrail.policy
+          result['maxTokens'] = guardrail.max_tokens if guardrail.max_tokens
+        else
+          result['taskName'] = guardrail.name
+        end
+        result
+      end
+
+      def serialize_termination(condition)
+        case condition
+        when Termination::TextMention
+          { 'type' => 'text_mention', 'text' => condition.text, 'caseSensitive' => condition.case_sensitive }
+        when Termination::StopMessage
+          { 'type' => 'stop_message', 'stopMessage' => condition.stop_message }
+        when Termination::MaxMessage
+          { 'type' => 'max_message', 'maxMessages' => condition.max_messages }
+        when Termination::TokenUsage
+          h = { 'type' => 'token_usage' }
+          h['maxTotalTokens'] = condition.max_total_tokens unless condition.max_total_tokens.nil?
+          h['maxPromptTokens'] = condition.max_prompt_tokens unless condition.max_prompt_tokens.nil?
+          h['maxCompletionTokens'] = condition.max_completion_tokens unless condition.max_completion_tokens.nil?
+          h
+        when Termination::And
+          { 'type' => 'and', 'conditions' => condition.conditions.map { |c| serialize_termination(c) } }
+        when Termination::Or
+          { 'type' => 'or', 'conditions' => condition.conditions.map { |c| serialize_termination(c) } }
+        else
+          { 'type' => 'unknown' }
+        end
+      end
+
+      def serialize_handoff(handoff, agent_name)
+        result = { 'target' => handoff.target }
+        case handoff
+        when Handoff::OnToolResult
+          result['type'] = 'on_tool_result'
+          result['toolName'] = handoff.tool_name
+          result['resultContains'] = handoff.result_contains if handoff.result_contains
+        when Handoff::OnTextMention
+          result['type'] = 'on_text_mention'
+          result['text'] = handoff.text
+        when Handoff::OnCondition
+          result['type'] = 'on_condition'
+          result['taskName'] = "#{agent_name}_handoff_#{handoff.target}"
+        else
+          result['type'] = 'unknown'
+        end
+        result
+      end
+
+      def serialize_router(agent)
+        router = agent.router
+        return serialize_agent(router) if router.is_a?(Agent)
+        return { 'taskName' => "#{agent.name}_router_fn" } if router.respond_to?(:call)
+
+        nil
+      end
+
+      # output_type: a JSON schema Hash, optionally wrapped as { schema:, class_name: }
+      def serialize_output_type(output_type)
+        schema = output_type.respond_to?(:to_json_schema) ? output_type.to_json_schema : output_type
+        schema = schema.transform_keys(&:to_s) if schema.is_a?(Hash)
+        if schema.is_a?(Hash) && (schema.key?('schema') || schema.key?('className') || schema.key?('class_name'))
+          result = {}
+          result['schema'] = schema['schema'] if schema['schema']
+          class_name = schema['className'] || schema['class_name']
+          result['className'] = class_name if class_name
+          return result
+        end
+
+        result = { 'schema' => schema }
+        result['className'] = schema['title'] if schema.is_a?(Hash) && schema['title']
+        result
+      end
+
+      def serialize_memory(memory)
+        result = {}
+        result['messages'] = memory.messages unless memory.messages.empty?
+        result['maxMessages'] = memory.max_messages if memory.max_messages
+        result
+      end
+    end
+  end
+end

data/lib/conductor/agents/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../exceptions'
+
+module Conductor
+  module Agents
+    # Base class for agent definition and runtime errors
+    class Error < ConductorError; end
+
+    # Invalid agent/tool definition (bad name, missing model, positional tool args, ...)
+    class ConfigurationError < Error; end
+
+    # secret('X') was called but X is neither on the task's runtimeMetadata nor in ENV
+    class CredentialNotFoundError < Error; end
+
+    # A tool returned something that cannot be serialized to JSON
+    class ToolSerializationError < Error; end
+
+    # The SSE stream could not be opened (non-200, connection failure, heartbeat-only)
+    class SseUnavailableError < Error; end
+
+    # Server-side agent API errors are the transport-level classes
+    AgentApiError = Conductor::AgentApiError
+    AgentNotFoundError = Conductor::AgentNotFoundError
+  end
+end