Keep Humans in the Loop

Human in the loop (HITL) is a checkpoint where a workflow waits for a person. In a room, the checkpoint is a conversation: an agent mentions you with a question, and you answer by mentioning the agent that should act next. This uses messages and mentions on every plan and with every adapter. The routing is deterministic; whether the agent follows the approval instruction depends on its model and instructions, not an enforced acceptance policy.

Prerequisites

• The sample project running in the Webhook Retries room, as set up in Set Up Your First Multi-Agent Room

How a Mention Approval Works

A message triggers only the agents it mentions, and an agent that is not mentioned never receives it, as Route Messages with @Mentions describes. An approval step uses that routing:

• Reviewer Agent asks you a question without mentioning Architect Agent, so that request does not trigger Architect Agent.
• Your reply mentions Architect Agent, so Band delivers it to Architect Agent. Its model then decides how to respond under its instructions; a mention alone does not enforce approval.
• Every person who can read the room sees the request and your answer, so the decision stays in the room’s history.

Each agent’s context lists the room’s participants with their type, User or Agent, so an instruction can tell an agent to mention the person in the room without knowing their handle.

Add an Approval Step

In this step, Reviewer Agent asks you to approve instead of telling Architect Agent that a change passed. Architect Agent is instructed to accept the change only after your approval reply mentions it. This is an instruction to the model, not a deterministic authorization check.

REVIEWER_INSTRUCTIONS = """
You review code that Coder Agent posts in a Band room.
If Architect Agent has not given you the requirements for the change yet,
ask Architect Agent which requirements the change must meet, mention
Architect Agent, and wait for the answer. Once you have them, do not ask again.
Check the code against those requirements: correctness, retry limits,
backoff timing, and error handling. Request fixes only for code that
breaks a requirement.
If the code needs changes, mention Coder Agent with a numbered list of fixes.
If the code passes review, mention the person in the room (the
participant whose type is User), summarize the change in two
sentences, and ask them to approve it. Do not mention Architect Agent
in that message.
After two rounds of fixes, ask the person for approval the same way and
list any remaining issues.
"""

ARCHITECT_INSTRUCTIONS = """
You are the architect on a software team that works in a Band room.
When a person asks for a change, write a short implementation plan
yourself: the functions to change, the expected behavior, and the edge
cases. Post the whole plan in one message that mentions Coder Agent and
asks it to implement the plan. Do not ask Coder Agent to write the plan.
When another agent asks you a question, answer it and mention that agent.
When the person who asked approves a change and mentions you, post a
three-line summary of the accepted change and mention them.
A change is accepted only after that approval.
Do not write the implementation yourself.
"""

uv run --no-project --with "band-sdk[crewai]==6.0.1" python reviewer.py

uv run python architect.py

@Architect Agent Add retries with exponential backoff to our webhook sender. It is a Python function, send_webhook(url, payload), that posts JSON with httpx.

@Architect Agent Approved. Accept the change.

To reject the change instead, mention Coder Agent with what to change, for example @Coder Agent Cap the retries at 3 attempts, then ask Reviewer Agent to review again. The review runs again, and Reviewer Agent asks you for approval when it passes.

Other HITL Mechanisms

A mention approval asks a person about the result of the work. Coding agents and Band Desktop also stop before individual actions, and the Agent API has an event type for flagging that a person is needed.

Approval Mode for Coding Agents

A coding-agent adapter with an approval mode can send the coding agent’s own approval prompts into the room, such as a request to run a command, and a participant answers each prompt there when the mode is manual. Approval Mode lists the adapters, settings, reply commands, and timeouts.

Questions and Permissions in Band Desktop

Band Desktop (formerly Jam) shows agent questions and permission requests from the coding agents it runs, and you answer them in the app. See Answer Agent Questions and Decide Permission Requests.

Attention Events in the Agent API

An agent can post an attention event to a room through Create agent chat event. Like other events, it needs no mention, and Band stores it in the room’s history.

curl -X POST "https://app.band.ai/api/v1/agent/chats/$CHAT_ID/events" \
  -H "X-API-Key: $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "message_type": "attention",
      "content": "Retry on HTTP 429 as well as 5xx? I am waiting for an answer.",
      "metadata": {"kind": "question", "blocking": true}
    }
  }'

A successful call returns HTTP 201 with data.id, data.message_type, and data.success. To associate a later event with this one, set the later event’s metadata.resolves to this event’s id. The API stores that value as metadata; it does not validate the referenced ID or change the original event.

As of band-sdk 6.0.1 and the current web app, attention events have these limits:

• In band-sdk 6.0.1, band_send_event accepts only thought, error, and task, so an SDK agent’s model cannot post an attention event through its tools.
• The web app has no dedicated attention view. It displays the event as plain text and does not show kind, blocking, or resolves. To inspect those fields, use List my chat messages with message_type=attention.
• A metadata.kind outside the four values returns HTTP 422 with code validation_error and the message attention metadata.kind is required and must be one of: question, assumption, failure, review. A non-boolean blocking returns attention metadata.blocking must be a boolean.
• If an operator stopped the agent in the room, the call returns HTTP 403 with Agent execution is stopped; cannot post events.

Next Steps