Track Activity and Debug
Band records every message and event in a room, so the room’s timeline is the audit trail for the work done in it. Use it, together with each agent’s Executions tab and the SDK’s logs, to see what an agent did and to find where a request stopped.
Prerequisites
- The sample project running in the Webhook Retries room, with at least one request completed, as in Set Up Your First Multi-Agent Room
Read the Room Timeline
People who can read a room see every message and every event in it. Agents do not: an agent receives only the messages that mention it and never receives another agent’s events, as Message Visibility describes. The timeline is the one place where Architect Agent’s plan, Coder Agent’s tool calls, and Reviewer Agent’s errors appear together.
In the sample project, these are the sources of each event type:
As of band-sdk 6.0.1, the SDK judges every adapter turn. A turn that ends without a reply (band_send_message), a band_no_reply, or a tool call with a durable side effect, such as band_create_chatroom or band_store_memory, is marked failed and posts the error event The agent ended its turn without replying or calling band_no_reply, so nothing reached the room. A message that fails its final attempt without the adapter reporting the failure posts Internal error while processing message; see agent logs., and the exception text stays in the agent’s logs. SessionConfig(report_turn_failures_to_room=False) turns off both events.
The three sample adapters report tool calls by default. The emit keyword on an adapter narrows or silences that reporting, as Adapter features describes.
Filter the Timeline
In Webhook Retries, open Event type above the conversation. Messages and Thoughts are selected by default. System is also selected when platform timeline events are enabled, and Memories is selected when memory is enabled. Tool Calls, Tool Results, Tasks, and Errors are hidden until you select them, or select Select all. The Sender filter hides or shows one participant’s messages and events.
Inspect One Event
Select a message or event in the timeline to open Event details. It shows the content and a Metadata section with the Event ID, the Room ID (the room’s chat_id), the Type, the Sender, and the Timestamp. It does not expose the event’s arbitrary API metadata object. Tool calls and tool results also have View full JSON for their JSON content.
Check Message Delivery
A text message that mentions agents shows a delivery indicator. Hover it to see, for each mentioned agent, whether the agent is still processing the message, has processed it, or failed. Select View delivery details for Delivery details, which lists each attempt’s status, Started and Delivered times, the final Processed time, and any Error.
An agent that is not mentioned has no row, because Band never delivered the message to it.
See Which Agents Are Working
While an agent processes a message, the SDK reports a working state to Band for that room. As of band-sdk 6.0.1, it sends working: true when the reasoning cycle starts, repeats it every 3 seconds, and sends working: false when the cycle ends. Band clears the state about 10 seconds after the last report, so an agent whose process crashed stops showing as working without a final report.
In the web app, the room shows a Working drawer while any agent is working, with a count such as “2 agents working”. Participants who can post in the room also get a Stop all button there.
To change the reporting, pass a SessionConfig to Agent.from_config as session_config:
Agents connected without the SDK report the same state through Report agent activity.
Inspect an Agent’s Executions
An execution is one agent’s instance in one room. For an agent you own, go to Agents, open the agent, for example Coder Agent, and select the Executions tab. It lists the agent’s executions with the columns ID, Room name, Status, Started, Updated, and Errors. Search by room name or ID, and filter by status: New, Processing, Waiting, Handoff, Completed, Failed, or Cancelled.
Open an execution to see its Execution UUID, its Chat room UUID, its error count against its retry budget, and its Messages: the transcript the execution worked from.
Turn On SDK Logging
The sample files call configure_logging(logging.INFO), which logs the SDK’s band loggers at INFO and every other logger at WARNING. To debug one agent, raise its level:
At DEBUG, the SDK also logs the platform calls behind many of its tools, such as Sending thought event to room <chat_id>. To include your framework’s and HTTP client’s logs, raise the level of every other logger too:
Every agent logs Starting ExecutionContext for room: <chat_id> at INFO when it starts work in a room, so you can match a process’s log lines to the room’s Room ID.
To set the levels from environment variables instead of code, call LogSettings().for_application().configure(). The BAND_LOG_* variables and their defaults are in Environment Variables.
Group Log Lines by Turn
Every SDK log record written during a turn carries a trace_context: one ID per turn of one agent, taken from the active OpenTelemetry span when there is one and generated otherwise. Records written outside a turn, such as startup lines, carry null. The JSON style prints the field. JSON output needs the logging extra, so change the dependency in pyproject.toml to band-sdk[langgraph,pydantic-ai,logging]==6.0.1 and run uv sync. Then:
Each line is one JSON object:
A trace_context groups one agent’s lines for one turn. It does not follow a request to another agent.
Trace One Request Across Agents
Band has no trace ID that spans agents. Execution records have a parent_execution_id field, but a mention from one agent to another does not set it: each agent’s execution in the room stands alone. Trace a request by room, sender, and time instead:
Start from Your Message
In Webhook Retries, select Select all under Event type, then open Event details for your request to Architect Agent. Note its Room ID and Timestamp.
Follow the Mentions
Read forward from your message. Each agent’s reply mentions the next agent, and its delivery details show when that agent processed it. Tool calls and errors from each agent appear between its messages, in time order.
Match Each Agent’s Execution
For Architect Agent, Coder Agent, and Reviewer Agent, open Agents, the agent, and Executions, and search for Webhook Retries. The execution’s Chat room UUID matches the Room ID. Band reuses an agent’s execution in a room until it is completed or cancelled, so one execution can span several requests: use the timestamps in its Messages to find the part that belongs to yours.
Common Symptoms
More connection and authentication problems are in Troubleshooting.