Chatwoot AI Agents Ruby SDK

The AI Agents library provides a framework for building multi-agent AI workflows using several interconnected abstractions:

• Agents: Immutable, thread-safe AI assistants defined by specific roles and capabilities.
• AgentRunner: A thread-safe execution manager responsible for managing multi-agent conversations.
• Context: A mechanism for serializable state management that persists across different agent interactions.
• Handoffs: A tool-based mechanism used to facilitate seamless transitions between different agents.
• Tools: Stateless extensions that allow agents to integrate with external systems.
• Callbacks: A system for receiving real-time notifications regarding agent reasoning (thinking), tool execution, and handoffs.
• AgentTool: A specialized mechanism for agent-to-agent collaboration that does not require a full conversation handoff.

The AI Agents SDK provides real-time callbacks to monitor agent execution stages. These are useful for building live UIs, streaming status updates, or collecting metrics. Callbacks are registered on an Agents::Runner instance using chainable methods.

runner = Agents::Runner.with_agents(triage, support)
  .on_run_start { |agent, input, ctx| puts "Starting: #{agent}" }
  .on_run_complete { |agent, result, ctx| puts "Completed: #{agent}" }
  .on_agent_complete { |agent, result, error, ctx| puts "Agent done: #{agent}" }
  .on_agent_thinking { |agent, input| puts "#{agent} thinking..." }
  .on_tool_start { |tool, args| puts "Using #{tool}" }
  .on_tool_complete { |tool, result| puts "#{tool} completed" }
  .on_agent_handoff { |from, to, reason| puts "#{from} → #{to}" }

The Agent-as-Tool pattern is used for multi-agent collaboration where specialized agents work behind the scenes to assist an orchestrator without the user being aware of the multiple agents involved.

Handoffs vs Agent-as-Tool

Use this pattern when you need specialized processing, behind-the-scenes coordination, complex multi-step workflows, or a modular architecture with a clean separation of concerns.

Handoffs allow agents to transfer control to other specialized agents based on the conversation context. This process is transparent to the user. You define these relationships using agent.register_handoffs(target_agent1, target_agent2, ...).

Common patterns include:

• Hub-and-Spoke: A central triage agent routes to specialists, and specialists route back to triage.
• Direct Routing: Agents route directly to one another.

# Hub-and-spoke pattern
triage = Agents::Agent.new(name: "Triage")
billing = Agents::Agent.new(name: "Billing")
support = Agents::Agent.new(name: "Support")

triage.register_handoffs(billing, support)
billing.register_handoffs(triage)
support.register_handoffs(triage)

runner = Agents::Runner.with_agents(triage, billing, support)

The Agents::Runner manages the lifecycle of a multi-agent conversation:

• Entry Points: The first agent passed to Agents::Runner.with_agents(...) is the default starting agent for all new conversations.
• Context Preservation: To continue a conversation after a handoff, you must pass the context from the previous result into the next .run call. The AgentRunner uses this context to automatically detect which agent is currently active.
• Thread Safety: The AgentRunner is thread-safe and can be reused across multiple concurrent conversations/threads.

# Start conversation
result1 = runner.run("My name is John and I have a billing question")

# Continue conversation by passing the context
result2 = runner.run("What payment methods do you accept?", context: result1.context)
# The runner automatically selects the correct agent based on result1.context

The ISP Customer Support system implements a hub-and-spoke pattern to manage customer requests.

Core Components

1. Triage Agent (The Hub): Acts as the entry point. It greets customers, analyzes their requests, and routes them to the appropriate specialist.
2. Specialist Agents (The Spokes):
   • Sales Agent: Handles new customer acquisition, plan upgrades, changes, and billing questions.
   • Support Agent: Handles technical troubleshooting, account information lookups, and escalations.

Routing Logic

Instead of agents bouncing requests back and forth, the system uses task-focused design. For example, the Support Agent is designed to handle both account lookups and technical troubleshooting to prevent unnecessary handoffs between agents.

The library separates long-lived configuration from short-lived execution using two distinct components:

1. AgentRunner (Long-lived): A thread-safe manager created once and reused across multiple conversations. It maintains an immutable agent registry, defines the entry point for conversations, and determines conversation continuity.
2. Runner (Per-request): A stateless execution engine created for every conversation turn. It handles LLM communication, tool execution, and manages the RunContext during that specific execution. It is designed to be garbage-collected immediately after use.

This separation ensures that the system is scalable and can handle concurrent conversations without state contamination.

The Agents::Runner returns a result object containing a context hash. This context is fully serializable and tracks the conversation_history and the current_agent (stored as a string name). To resume a conversation later, pass the serialized context back into the run method.

# Start conversation
result = runner.run("I need billing help")
context = result.context

# Serialize for storage
json_context = JSON.dump(context)

# Later: Restore and continue
restored_context = JSON.parse(json_context, symbolize_names: true)
result = runner.run("Actually, I need technical support too", context: restored_context)