List agents

title: Agents description: Create AI agents and run them against conversations.

List agents

result = client.agents.list()

for agent in result:  # ListResponse is iterable
    print(agent.name)

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"

With structured fields

Define payload_schema to enforce specific fields in the AI output payload:

agent = client.agents.create(
    name="Hotel Concierge",
    system_prompt="Extract structured tasks from hotel guest messages.",
    payload_schema=[
        {"name": "room_number", "field_type": "text", "required": True},
        {"name": "description", "field_type": "text", "required": True},
        {"name": "due_at", "field_type": "datetime", "required": False},
        {"name": "priority", "field_type": "text", "required": False},
    ],
)

Available field types: text, number, boolean, date, time, datetime. Max 10 fields.

With allowed action types

By default, the AI can return any action type (free-form). Set allowed_actions to constrain it to a specific list — the AI can only return values from this list.

agent = client.agents.create(
    name="Support Agent",
    system_prompt="Handle customer support requests.",
    allowed_actions=[
        "support.refund.process",
        "support.ticket.create",
        "support.escalation.request",
    ],
)

Format: domain.resource.action (snake_case, 3 segments). Max 10 action types.

When a run completes, every action's type is guaranteed to be in this list:

run = agent.run(input={"last_message": "I want a refund for order #1234"})

for action in run.actions:
    match action["type"]:
        case "support.refund.process":
            process_refund(action["payload"])
        case "support.ticket.create":
            create_ticket(action["payload"])
        case "support.escalation.request":
            notify_escalation(action["payload"])

Retrieve an agent

agent = client.agents.retrieve("agt_01hx...")
agent.is_active    # True
agent.is_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

Creates a run and polls until complete (blocks). The run is processed asynchronously on the server.

# String input (auto-wrapped as last_message)
run = agent.run(input="Clean room 204 tomorrow at 8")

# Dict input (full control)
run = agent.run(input={
    "last_message": "Clean room 204 tomorrow at 8",
    "recent_messages": ["Hi, I have a request"],
})

run.status           # "completed"
run.intent           # "task_extraction"
run.confidence       # 0.95
run.actions          # [{"type": "hospitality.room_service.request", "payload": {...}}]
run.suggested_reply  # "I'll arrange cleaning for room 204 tomorrow at 8am."
run.context_summary  # "Guest requested room 204 cleaning for tomorrow 8am."

Async (non-blocking)

run = agent.run_async(input="Clean room 204 tomorrow at 8")
run.status  # "pending"

# ... do other things ...

run.wait(timeout=30)  # blocks until completed

List runs

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

# From the client
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 handlers:

from whatsrb_cloud import ActionRegistry

registry = ActionRegistry()

registry.register("create_task", lambda payload: create_task(
    description=payload["description"],
    room_number=payload["room_number"],
    priority=payload["priority"],
))

registry.register("create_ticket", lambda payload: create_ticket(
    message=payload["message"],
))

# 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.

Action confirmation

When an agent has confirmation_mode="confirm", actions require human validation before dispatch.

# Enable confirmation mode
agent = client.agents.update("agt_xxx",
    confirmation_mode="confirm",
    confirmation_timeout_minutes=30
)

# Run the agent
run = agent.run(input="I want a refund for order #1234")

# Review action_statuses
run.action_statuses  # [{"status": "pending", ...}, ...]

# Confirm specific actions (by index)
run.confirm_actions([0, 2])

# Reject specific actions (by index)
run.reject_actions([1])

# Dispatch only executes confirmed actions
run.dispatch(registry)

See Action Confirmation for the full guide.

Agent attributes

AgentRun attributes