conductor_ruby 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eaac8568f7cf211e8337d9c41ccf454d9362d8c1b5f4d8adefb2a6f2faff64e
-  data.tar.gz: 5c34b569b0080d6ea6ea2b20411614076ba1fbefd5de6901ea581a917f3ac30c
+  metadata.gz: 58e85067049af7ceef18c133c58b3f562b53d62421cdafb61bf8bdc5eec4ebe8
+  data.tar.gz: 9d9d0cc7ec214d7734b09d0d179269119d516f716069ed8fa7c15e477cd97c66
 SHA512:
-  metadata.gz: 364e5f398619c081bc979e0158d15daf6cbe2df9f2b548e90d81d8811da900c828f88a34e619a992e0847ce210ae24f0fe3a4a6b29fff6c2e3ce743bdbbe81eb
-  data.tar.gz: 66b81f3609e971ce064ab042287fea9e96e9ce197765d1ba5cf46b5265583f37f73311cec754f6ef97ec03b28391e310809cbb7504e4ce147dd8519f7086e12c
+  metadata.gz: 1ba8b9dccdbdd29fdbc1afbc48e42c492c4cc8be47cb34ca763abf0bba558093480b0d016461a1a1215d9e1fe4278586de536d762cb0f8f05fa0f4c4d63a8dfd
+  data.tar.gz: ce5edabd959da8b8c68184146bbbed0489b620c4ffad7f9e6e335c0b23348fa96cd11c8d0c79188b0dab74f693b9d14e1225e6a23d2afbe9b955e97fd8e63838

data/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.1]
+
+### Added
+
+- **Conductor Agents** (`require 'conductor/agents'`): define agents in Ruby and run them on a Conductor server (#29)
+  - `Agent` with instructions, model, tools, guardrails, handoffs, memory, termination conditions and prompt templates
+  - `tool def` DSL that turns a method into a worker tool with a schema derived from keyword defaults, plus factories for HTTP, OpenAPI, MCP, human, agent, media, PDF and RAG tools
+  - Regex, LLM and custom guardrails with `raise`, `retry`, `fix` and `human` failure modes
+  - Sequential, parallel, hierarchical and swarm multi-agent patterns, handoffs and human-in-the-loop approval
+  - `AgentRuntime` with streaming, status polling, secrets resolution and automatic worker registration
+  - Examples under `examples/agents/` and documentation under `docs/agents/`
+- Agent playback integration tests driven by the shared Conductor HTTP and MCP playback services (#29)
+- Integration (e2e) test suite now runs against a Conductor OSS stack on every PR and gates the Orkes cloud run (#26)
+
 ## [0.1.0]
 
 ### Added
@@ -139,4 +153,5 @@ end
 - Supports both OSS Conductor and Orkes Cloud
 - Ruby 2.6+ compatible (Ruby 3+ recommended for Ractor support)
 
+[0.1.1]: https://github.com/conductor-oss/ruby-sdk/releases/tag/v0.1.1
 [0.1.0]: https://github.com/conductor-oss/ruby-sdk/releases/tag/v0.1.0

data/examples/agents/01_basic_agent.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/01_basic_agent.py.
+# Run: bundle exec ruby -Ilib examples/agents/01_basic_agent.rb
+require 'conductor/agents'
+
+module Example01BasicAgent
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    agent = Agent.new(
+      name: "greeter",
+      model: model,
+      instructions: "You are a friendly assistant. Keep responses brief."
+    )
+    agent
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    agent = build
+    executions = []
+    execution = runtime.call_async(agent, "Say hello and tell me a fun fact about Python.")
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example01BasicAgent.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/02a_simple_tools.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/02a_simple_tools.py.
+# Run: bundle exec ruby -Ilib examples/agents/02a_simple_tools.rb
+require 'conductor/agents'
+
+module Example02aSimpleTools
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def get_weather(city: String)
+    { city: city, temp_f: 72, condition: "Sunny" }
+  end
+  tool :get_weather, description: "Get the current weather for a city."
+
+  def get_stock_price(symbol: String)
+    { symbol: symbol, price: 182.50, change: "+1.2%" }
+  end
+  tool :get_stock_price, description: "Get the current stock price for a ticker symbol."
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    agent = Agent.new(
+      name: "weather_stock_agent",
+      model: model,
+      tools: [self[:get_weather], self[:get_stock_price]],
+      instructions: "You are a helpful assistant. Use tools to answer questions."
+    )
+    agent
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    agent = build
+    executions = []
+    execution = runtime.call_async(agent, "What's the weather like in San Francisco?")
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example02aSimpleTools.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/02c_tool_retry_config.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/02c_tool_retry_config.py.
+# Run: bundle exec ruby -Ilib examples/agents/02c_tool_retry_config.rb
+require 'conductor/agents'
+
+module Example02cToolRetryConfig
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def call_external_api(query: String)
+    { result: "Data for: #{query}", source: "external_api" }
+  end
+  tool :call_external_api, description: "Call an unreliable external API that may need aggressive retries.", retry_policy: "exponential_backoff", retry_count: 5, retry_delay_seconds: 1
+
+  def query_database(sql: String)
+    { rows: [{ id: 1, value: sql }], count: 1 }
+  end
+  tool :query_database, description: "Run a database query with fixed-interval retries for transient connection issues." , retry_policy: "fixed", retry_count: 3, retry_delay_seconds: 5
+
+  def process_data(data: String)
+    { processed: data, status: "ok" }
+  end
+  tool :process_data, description: "Process data locally — light retries with linear backoff." , retry_policy: "linear_backoff", retry_count: 2, retry_delay_seconds: 2
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    agent = Agent.new(
+      name: "retry_config_demo",
+      model: model,
+      tools: [self[:call_external_api], self[:query_database], self[:process_data]],
+      instructions: "You help users fetch and process data. Use the appropriate tool for each request."
+    )
+    agent
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    agent = build
+    executions = []
+    execution = runtime.call_async(agent, "Look up the latest Python release info from the API.")
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example02cToolRetryConfig.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/04_http_and_mcp_tools.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/04_http_and_mcp_tools.py.
+# Run: bundle exec ruby -Ilib examples/agents/04_http_and_mcp_tools.rb
+require 'conductor/agents'
+
+module Example04HttpAndMcpTools
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def format_report(title: String, body: String)
+    { report: "=== #{title} ===\n#{body}\n#{'=' * (title.length + 8)}" }
+  end
+  tool :format_report, description: "Format a title and body into a structured report."
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    reverse_api = Tool.http(
+      "reverse_string",
+      "http://localhost:3001/api/string/reverse",
+      description: "Reverse a string using the HTTP API",
+      method: "POST",
+      headers: { "Authorization" => "Bearer ${HTTP_TEST_API_KEY}" },
+      credentials: ["HTTP_TEST_API_KEY"],
+      input_schema: { "type" => "object", "properties" => { "text" => { "type" => "string", "description" => "Text to reverse" } }, "required" => ["text"] }
+    )
+    mcp_test_tools = Tool.mcp(
+      "http://localhost:3001/mcp",
+      name: "mcp_test_tools",
+      description: "Deterministic test tools via MCP — math, string, collection, encoding, hash, datetime, validation, and conversion operations.",
+      headers: { "Authorization" => "Bearer ${MCP_TEST_API_KEY}" },
+      credentials: ["MCP_TEST_API_KEY"]
+    )
+    agent = Agent.new(
+      name: "http_tools_demo",
+      model: model,
+      tools: [self[:format_report], reverse_api, mcp_test_tools],
+      instructions: "You can reverse strings and format reports. When asked to reverse a string, use reverse_string first, then format_report with the result."
+    )
+    agent
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    agent = build
+    executions = []
+    execution = runtime.call_async(agent, "Reverse the string 'hello world' and add 33 and 21 append the result to that string, then write a report with the result.")
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example04HttpAndMcpTools.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/05_handoffs.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/05_handoffs.py.
+# Run: bundle exec ruby -Ilib examples/agents/05_handoffs.rb
+require 'conductor/agents'
+
+module Example05Handoffs
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def check_balance(account_id: String)
+    { account_id: account_id, balance: 5432.10, currency: "USD" }
+  end
+  tool :check_balance, description: "Check the balance of a bank account."
+
+  def lookup_order(order_id: String)
+    { order_id: order_id, status: "shipped", eta: "2 days" }
+  end
+  tool :lookup_order, description: "Look up the status of an order."
+
+  def get_pricing(product: String)
+    { product: product, price: 99.99, discount: "10% off" }
+  end
+  tool :get_pricing, description: "Get pricing information for a product."
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    billing_agent = Agent.new(
+      name: "billing",
+      model: model,
+      instructions: "You handle billing questions: balances, payments, invoices.",
+      tools: [self[:check_balance]]
+    )
+    technical_agent = Agent.new(
+      name: "technical",
+      model: model,
+      instructions: "You handle technical questions: order status, shipping, returns.",
+      tools: [self[:lookup_order]]
+    )
+    sales_agent = Agent.new(
+      name: "sales",
+      model: model,
+      instructions: "You handle sales questions: pricing, products, promotions.",
+      tools: [self[:get_pricing]]
+    )
+    support = Agent.new(
+      name: "support",
+      model: model,
+      instructions: "Route customer requests to the right specialist: billing, technical, or sales.",
+      agents: [billing_agent, technical_agent, sales_agent],
+      strategy: :handoff
+    )
+    support
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    support = build
+    executions = []
+    execution = runtime.call_async(support, "What's the balance on account ACC-123?")
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example05Handoffs.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/06_sequential_pipeline.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/06_sequential_pipeline.py.
+# Run: bundle exec ruby -Ilib examples/agents/06_sequential_pipeline.rb
+require 'conductor/agents'
+
+module Example06SequentialPipeline
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    researcher = Agent.new(
+      name: "researcher",
+      model: model,
+      instructions: "You are a researcher. Given a topic, provide key facts and data points. Be thorough but concise. Output raw research findings."
+    )
+    writer = Agent.new(
+      name: "writer",
+      model: model,
+      instructions: "You are a writer. Take research findings and write a clear, engaging article. Use headers and bullet points where appropriate."
+    )
+    editor = Agent.new(
+      name: "editor",
+      model: model,
+      instructions: "You are an editor. Review the article for clarity, grammar, and tone. Make improvements and output the final polished version."
+    )
+    pipeline = researcher >> writer >> editor
+    pipeline
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    pipeline = build
+    executions = []
+    execution = runtime.call_async(pipeline, "The impact of AI agents on software development in 2025")
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example06SequentialPipeline.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/07_parallel_agents.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/07_parallel_agents.py.
+# Run: bundle exec ruby -Ilib examples/agents/07_parallel_agents.rb
+require 'conductor/agents'
+
+module Example07ParallelAgents
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    market_analyst = Agent.new(
+      name: "market_analyst",
+      model: model,
+      instructions: "You are a market analyst. Analyze the given topic from a market perspective: market size, growth trends, key players, and opportunities."
+    )
+    risk_analyst = Agent.new(
+      name: "risk_analyst",
+      model: model,
+      instructions: "You are a risk analyst. Analyze the given topic for risks: regulatory risks, technical risks, competitive threats, and mitigation strategies."
+    )
+    compliance_checker = Agent.new(
+      name: "compliance",
+      model: model,
+      instructions: "You are a compliance specialist. Check the given topic for compliance considerations: data privacy, regulatory requirements, and industry standards."
+    )
+    analysis = Agent.new(
+      name: "analysis",
+      model: model,
+      agents: [market_analyst, risk_analyst, compliance_checker],
+      strategy: :parallel
+    )
+    analysis
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    analysis = build
+    executions = []
+    execution = runtime.call_async(analysis, "Launching an AI-powered healthcare diagnostic tool in the US market")
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example07ParallelAgents.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/09_human_in_the_loop.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/09_human_in_the_loop.py.
+# Run: bundle exec ruby -Ilib examples/agents/09_human_in_the_loop.rb
+require 'conductor/agents'
+
+module Example09HumanInTheLoop
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def check_balance(account_id: String)
+    { account_id: account_id, balance: 15000.00 }
+  end
+  tool :check_balance, description: "Check the balance of an account."
+
+  def transfer_funds(from_acct: String, to_acct: String, amount: Float)
+    { status: "completed", from: from_acct, to: to_acct, amount: amount }
+  end
+  tool :transfer_funds, description: "Request a funds transfer; runtime pauses for human approval before execution." , approval_required: true
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    agent = Agent.new(
+      name: "banker",
+      model: model,
+      tools: [self[:check_balance], self[:transfer_funds]],
+      instructions: "You are a banking assistant. Use check_balance for balance inquiries. When asked to transfer money, first check the balance, then call transfer_funds to request the transfer. The runtime will pause for human approval before the transfer executes."
+    )
+    agent
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    agent = build
+    agent.on_approval do |request|
+      output.puts "Approval requested: #{request.tool_calls}"
+      response = {}
+      request.response_schema.fetch('properties').each do |field, schema|
+        output.print "#{schema['description'] || schema['title'] || field}: "
+        answer = input.gets
+        raise EOFError, "No response supplied for #{field}" unless answer
+
+        response[field] = schema['type'] == 'boolean' ? %w[y yes].include?(answer.strip.downcase) : answer.strip
+      end
+      request.respond(response)
+    end
+    executions = []
+    execution = runtime.call_async(agent, "Transfer $500 from ACC-789 to ACC-456. Check the balance first.")
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example09HumanInTheLoop.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/09c_hitl_streaming.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/09c_hitl_streaming.py.
+# Run: bundle exec ruby -Ilib examples/agents/09c_hitl_streaming.rb
+require 'conductor/agents'
+
+module Example09cHitlStreaming
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def check_service(service_name: String)
+    { service: service_name, status: "unhealthy", uptime: "0m" }
+  end
+  tool :check_service, description: "Check the health of a service."
+
+  def restart_service(service_name: String)
+    { service: service_name, status: "restarted", new_uptime: "0m" }
+  end
+  tool :restart_service, description: "Restart a service. Safe operation, no approval needed."
+
+  def delete_service_data(service_name: String, data_type: String)
+    { service: service_name, data_type: data_type, status: "deleted" }
+  end
+  tool :delete_service_data, description: "Delete service data. Destructive — requires human approval." , approval_required: true
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    agent = Agent.new(
+      name: "ops_agent",
+      model: model,
+      tools: [self[:check_service], self[:restart_service], self[:delete_service_data]],
+      instructions: "You are an operations assistant. Work through the request one tool call at a time, in this order:\n1. Check the service with check_service.\n2. If it is unhealthy, restart it with restart_service.\n3. Last, if the user asked you to clear or delete data, call delete_service_data.\nA human approves the deletion, not you — delete_service_data pauses for that approval by itself, so never ask for approval in your own reply."
+    )
+    agent
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    agent = build
+    agent.on_approval do |request|
+      output.puts "Approval requested: #{request.tool_calls}"
+      response = {}
+      request.response_schema.fetch('properties').each do |field, schema|
+        output.print "#{schema['description'] || schema['title'] || field}: "
+        answer = input.gets
+        raise EOFError, "No response supplied for #{field}" unless answer
+
+        response[field] = schema['type'] == 'boolean' ? %w[y yes].include?(answer.strip.downcase) : answer.strip
+      end
+      request.respond(response)
+    end
+    executions = []
+    on_event = ->(event) { output.puts "[#{event['event']}] #{event['data']}" }
+    execution = runtime.call_async(agent, "The payments service is down. Check it, restart it, and clear its stale cache data.", on_event: on_event)
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example09cHitlStreaming.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/103_plan_and_compile.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/103_plan_and_compile.py.
+# Run: bundle exec ruby -Ilib examples/agents/103_plan_and_compile.rb
+require 'conductor/agents'
+
+module Example103PlanAndCompile
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def factorial(n: Integer)
+    return "ERROR: n must be in [0, 20], got #{n}" unless (0..20).cover?(n)
+
+    (1..n).reduce(1, :*).to_s
+  end
+  tool :factorial, output_schema: { 'type' => 'string' }, description: "Compute n! and return it as a string.\n\nArgs:\n    n: Non-negative integer. Capped at 20 to keep things sane."
+
+  def write_summary(text: String)
+    text
+  end
+  tool :write_summary, output_schema: { 'type' => 'string' }, description: "Persist a short summary string. Returns it back for the validator."
+
+  def check_summary(text: String, min_chars: Integer)
+    JSON.generate(passed: text.length >= min_chars, length: text.length, min_chars: min_chars)
+  end
+  tool :check_summary, output_schema: { 'type' => 'string' }, description: "Return JSON ``{passed, length, min_chars}`` for the validator.\n\nArgs:\n    text: The summary to check.\n    min_chars: Minimum acceptable length in characters."
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    planner_instructions = "You are a math-explainer planner. Plan a workflow that:\n\n1. Computes factorials of 1, 2, 3, 4, 5 in PARALLEL using ``factorial`` (static args).\n2. Writes a short prose summary about factorial growth using ``write_summary``\n   (use a ``generate`` block — the LLM produces the ``text`` arg at run time).\n3. Validates the summary is at least 30 characters via ``check_summary``,\n   with ``success_condition: \"$.passed === true\"``.\n"
+    harness = Conductor::Agents.plan_execute(
+      name: "plan_and_compile_demo",
+      tools: [self[:factorial], self[:write_summary], self[:check_summary]],
+      planner_instructions: planner_instructions,
+      fallback_instructions: "The plan failed. Use the available tools to recover.",
+      fallback_max_turns: 4,
+      model: model
+    )
+    harness
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout, topic: 'factorials')
+    harness = build
+    executions = []
+    execution = runtime.call_async(harness, "Topic: #{topic}")
+    output.puts execution.result(timeout: 180)
+    compiled = find_plan_and_compile_output(runtime, execution.execution_id)
+    raise 'No PLAN_AND_COMPILE task found in the workflow tree' unless compiled
+    raise "Plan compilation failed: #{compiled['error']}" if compiled['error']
+
+    output.puts "Compiled workflow: #{compiled['workflowName']}"
+    output.puts "Stats: #{compiled['stats']}"
+    Array(compiled.dig('workflowDef', 'tasks')).each do |task|
+      output.puts "#{task['type']}: #{task['taskReferenceName']}"
+    end
+    executions << execution
+    executions
+  end
+
+  def self.find_plan_and_compile_output(runtime, execution_id)
+    client = Conductor::Client::WorkflowClient.new(runtime.configuration)
+    pending = [execution_id]
+    visited = []
+    until pending.empty?
+      id = pending.pop
+      next if visited.include?(id)
+
+      visited << id
+      workflow = client.get_workflow(id)
+      workflow.tasks.each do |task|
+        return task.output_data if task.task_type == 'PLAN_AND_COMPILE'
+
+        pending << task.sub_workflow_id if task.sub_workflow_id
+      end
+    end
+    nil
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example103PlanAndCompile.run(topic: ARGV.empty? ? 'factorials' : ARGV.join(' '))
+  ensure
+    Conductor::Agents.shutdown
+  end
+end

data/examples/agents/10_guardrails.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Port of python-sdk/examples/agents/10_guardrails.py.
+# Run: bundle exec ruby -Ilib examples/agents/10_guardrails.rb
+require 'conductor/agents'
+
+module Example10Guardrails
+  include Conductor::Agents
+  extend Conductor::Agents::Tools
+
+  def get_order_status(order_id: String)
+    { order_id: order_id, status: "shipped", tracking: "1Z999AA10123456784", estimated_delivery: "2026-02-22" }
+  end
+  tool :get_order_status, description: "Look up the current status of an order."
+
+  def get_customer_info(customer_id: String)
+    { customer_id: customer_id, name: "Alice Johnson", email: "alice@example.com",
+      card_on_file: "4532-0150-1234-5678", membership: "gold" }
+  end
+  tool :get_customer_info, description: "Retrieve customer details including payment info on file."
+
+  def self.pii_guardrail
+    Guardrail.new(name: "no_pii", position: :output, on_fail: :retry) do |content|
+      pii = /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b|\b\d{3}-\d{2}-\d{4}\b/
+      if pii.match?(content)
+        GuardrailResult.new(passed: false, message: "Your response contains PII (credit card or SSN). Redact all card numbers and SSNs before responding.")
+      else
+        GuardrailResult.new(passed: true)
+      end
+    end
+  end
+
+  def self.build(model: ENV.fetch('CONDUCTOR_AGENT_LLM_MODEL', 'openai/gpt-4o-mini'))
+    no_pii = pii_guardrail
+    agent = Agent.new(
+      name: "support_agent",
+      model: model,
+      tools: [self[:get_order_status], self[:get_customer_info]],
+      instructions: "You are a customer support assistant. Use the available tools to answer questions about orders and customers. Always include all details from the tool results in your response.",
+      guardrails: [no_pii]
+    )
+    agent
+  end
+
+  def self.run(runtime: Conductor::Agents.runtime, input: $stdin, output: $stdout)
+    agent = build
+    executions = []
+    execution = runtime.call_async(agent, "I need a full summary: What's the status of order ORD-42, and what's the profile for customer CUST-7?")
+    output.puts execution.result(timeout: 180)
+    executions << execution
+    executions
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    Example10Guardrails.run
+  ensure
+    Conductor::Agents.shutdown
+  end
+end