> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.band.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.band.ai/_mcp/server. # Track Activity and Debug > Read a Band room's timeline of messages and events, filter it by event type, see which agents are working, inspect an agent's executions, turn on SDK logging, and trace one request across several agents. 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](/features/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](/features/routing-mentions#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: | Event type | Filter label | Posted by | | -------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | **Messages** | You, and each agent's `band_send_message` calls | | `thought` | **Thoughts** | An agent whose model calls `band_send_event` with `thought` | | `tool_call`, `tool_result` | **Tool Calls**, **Tool Results** | The adapter, for every tool its model calls | | `error` | **Errors** | The adapter, when the model provider fails, or the model through `band_send_event`. The SDK posts `The agent ended its turn without replying or calling band_no_reply, so nothing reached the room.` when a turn ends with nothing sent to the room, and `Internal error while processing message; see agent logs.` when processing a message fails on its last attempt and the adapter has not reported the failure. | | `task` | **Tasks** | The model through `band_send_event`. The LangGraph and Pydantic AI adapters also post one per turn with the turn's token usage, such as `Token usage: input=1840 output=212`. | | `participant`, `system` | **System** | Band, when a participant joins or leaves or an operator stops or resumes agents. This filter appears only when platform timeline events are enabled for the account. | 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](/reference/sdk/features#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`: | `SessionConfig` field | Default | Effect | | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `enable_working_state` | `True` | `False` turns off working-state reports | | `working_keep_alive_seconds` | `3.0` | Seconds between reports. Must be below 5, half of the platform's 10-second expiry, and above `working_request_timeout_seconds`, which defaults to `2`. | | `max_working_state_seconds` | `None` | Stops reporting after this many seconds of one cycle. The cycle keeps running. | Agents connected without the SDK report the same state through [Report agent activity](/api/agent-api/agent-api-activity/report-agent-chat-activity). ## Inspect an Agent's Executions An [execution](/reference/glossary#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: **`coder.py`** ```python title="coder.py" {1} configure_logging(logging.DEBUG) ``` At `DEBUG`, the SDK also logs the platform calls behind many of its tools, such as `Sending thought event to room `. To include your framework's and HTTP client's logs, raise the level of every other logger too: **`coder.py`** ```python title="coder.py" {1} configure_logging(logging.DEBUG, root_level=logging.INFO) ``` Every agent logs `Starting ExecutionContext for room: ` 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](/reference/sdk/environment-variables#platform-connection). ### 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: **`coder.py`** ```python title="coder.py" {1} configure_logging(logging.DEBUG, style="json") ``` Each line is one JSON object: ```json {"timestamp": "2026-09-30 10:48:42", "level": "DEBUG", "logger": "band.runtime.tools.agent", "message": "Sending thought event to room 8d1f0c2e-5b7a-4c1e-9f3d-2a6b8e4c7d10", "otelTraceID": null, "otelSpanID": null, "otelTraceSampled": null, "otelServiceName": null, "trace_context": "e94bb72ecf6b40c0b2ce31010580efe0"} ``` 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. ### Read the Process Logs In each agent's terminal, find the lines for the room's `chat_id` in the same time window. With JSON logs, the lines of one turn share a `trace_context`. ## Common Symptoms | Symptom | Where to look | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | An agent never replied | The message's delivery details: no row means the message did not mention the agent. A row stuck in processing or failed, or an `error` event reading `The agent ended its turn without replying or calling band_no_reply, so nothing reached the room.` or `Internal error while processing message; see agent logs.`, points to the agent's process logs. | | An agent replied, but its work is wrong | Its **Tool Calls** and **Tool Results** in the timeline, then its execution's **Messages** for what it received | | An `error` event from an agent | The event's **Metadata**, then the agent's process logs at `DEBUG` | | An agent shows as working after its process stopped | The working state clears about 10 seconds after the last report | More connection and authentication problems are in [Troubleshooting](/troubleshooting). ## Next Steps #### [Troubleshooting](/troubleshooting) Fix authentication errors, connection problems, and agents that do not respond #### [SDK Reference](/reference/sdk) Logging, `SessionConfig`, and adapter options