Skip to main content

List agents

result = client.agents.list

result.each { |agent| puts agent.name }  # List is Enumerable
result.meta  # => { "total" => 3 }

Create an agent

agent = client.agents.create(
  name: "Hotel Concierge",
  system_prompt: "You are a hotel operations agent...",
  business_account_id: "acc_01hx..."
)

agent.id     # => "agt_01hx..."
agent.name   # => "Hotel Concierge"
agent.status # => "active"

Retrieve an agent

agent = client.agents.retrieve("agt_01hx...")
agent.active?   # => true
agent.auto_run? # => false

Update an agent

agent = client.agents.update("agt_01hx...", name: "Updated Concierge")

Delete an agent

client.agents.delete("agt_01hx...")  # => true

Run an agent (sync)

Creates a run and polls until completed. Blocks the current thread.
run = agent.run(input: { last_message: "Clean room 204 tomorrow at 8" })

run.status     # => "completed"
run.intent     # => "task_extraction"
run.confidence # => 0.95
run.actions    # => [{ "type" => "create_task", "room" => "204", ... }]
You can tune the polling behavior:
run = agent.run(
  input: { last_message: "..." },
  timeout: 60,   # seconds before raising (default: 30)
  interval: 2    # seconds between polls (default: 1)
)

Run an agent (async)

Creates a run and returns immediately without waiting.
run = agent.run_async(input: { last_message: "Clean room 204" })
run.status  # => "pending"

# Later: poll manually
run.reload
run.completed?  # => false

# Or block until done
run.wait(timeout: 30, interval: 1)
run.completed?  # => true

List runs

# From an agent object
runs = agent.runs.list

# From the client
runs = client.agents.runs("agt_01hx...").list
# or
runs = client.agent_runs("agt_01hx...").list

Retrieve a run

run = client.agent_runs("agt_01hx...").retrieve("run_01hx...")

Dispatch actions with a registry

Use an ActionRegistry to route agent actions to your service objects:
registry = WhatsrbCloud::ActionRegistry.new

registry.register("create_task") do |action|
  Task.create!(
    description: action["description"],
    room_number: action["room_number"],
    priority: action["priority"]
  )
end

registry.register("create_ticket") do |action|
  Ticket.create!(message: action["message"])
end

# Dispatch all actions from a completed run
run = agent.run(input: { last_message: "Fix the AC in room 107" })
run.dispatch(registry)
See Registries for the full guide.

Agent attributes

AttributeTypeDescription
idStringAgent ID
nameStringAgent name
system_promptStringSystem prompt for the agent
modelStringModel used
statusStringactive, inactive
business_account_idStringLinked business account
auto_runBooleanWhether auto-run is enabled
active?BooleanWhether agent is active
auto_run?BooleanWhether auto-run is enabled

AgentRun attributes

AttributeTypeDescription
idStringRun ID
agent_idStringParent agent ID
statusStringpending, running, completed, failed
inputHashInput data sent to the agent
outputHashAgent output (intent, confidence, actions)
errorStringError message if failed
intentStringShortcut for output["intent"]
confidenceFloatShortcut for output["confidence"]
actionsArrayShortcut for output["actions"]
pending?BooleanStatus is pending
running?BooleanStatus is running
completed?BooleanStatus is completed
failed?BooleanStatus is failed
finished?BooleanCompleted or failed