> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Start conversations with agents and interact with them in real time.

A session is a conversation with an agent. You provide input, the agent runs, asks questions if needed, and returns its output.

## Starting a session

### Web UI

1. Open your workspace at [app.guild.ai](https://app.guild.ai)
2. Click **New session**
3. Select an agent, type a message, and press **Enter**

### CLI

```bash theme={null}
guild session create --agent <agent-name> --workspace <workspace-id>
```

## How sessions work

1. You send a message to an agent
2. **guildcore** receives the request, authenticates it, and forwards it to the runtime
3. The **runtime** loads the agent code and executes it
4. The agent can call tools, invoke sub-agents, make LLM calls, and ask you questions
5. When the agent finishes, its output is returned to your session

## Session lifecycle

Sessions can be in one of several states:

| State         | Description                                    |
| ------------- | ---------------------------------------------- |
| **Active**    | The agent is running or waiting for your input |
| **Completed** | The agent has finished and returned its output |
| **Failed**    | The agent encountered an error                 |

## Multi-turn sessions

Agents built with `mode: "multi-turn"` keep the session open for back-and-forth conversation. The session remains active until the agent calls the `__submit__` tool to signal completion.

## Agent mentions

In workspace chat, type `@` followed by an agent name to direct your message to a specific agent. The `@mention` UI lets you select any agent installed in the workspace from a picker that appears as you type.

```
@code-reviewer Please review the logic in the auth module.
```

If no agent is mentioned, the message goes to the default agent for the workspace (Smith, unless changed).

## Event log

The event log is a real-time view of everything that happens inside a session — LLM calls, tool invocations, sub-task spawns, errors, and lifecycle transitions. It is primarily useful for debugging and auditing agent behavior.

To open the event log for a session, click the **Events** tab inside the session view.

Each event entry shows:

| Field         | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| **Type**      | The kind of event (e.g., `llm_call`, `tool_call`, `agent_console`, `error`) |
| **Timestamp** | When the event occurred                                                     |
| **Content**   | The raw event payload, collapsed by default                                 |

Click any event to expand its full payload.

### Debug mode

Use debug mode when the default stacked list is too verbose to scan. It renders every event in a dense, table-based layout that makes high-volume sessions easier to read.

To turn on debug mode, click the bug icon in the session header toolbar. Click it again to return to the stacked list.

In debug mode, events render in a table with sticky headers and these columns:

| Column          | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| **Type**        | The kind of event, such as `llm_call`, `tool_call`, or `error`. |
| **Description** | A short summary of the event.                                   |
| **Time**        | When the event occurred.                                        |

Within the table:

* Click a row to expand its details inline.
* Ctrl-click (Windows and Linux) or Cmd-click (macOS) a row to toggle a raw-event JSON viewer inside that row.
* Progress groups flatten into individual rows, so each grouped event appears on its own line.

#### Event filter bar

When you are in debug mode, an event filter chip bar appears above the dense table. Use it to control which event types the table shows.

The chips operate on the processed event types that the UI renders, such as user messages, agent messages, progress, agent errors, credentials, LLM, runtime done, runtime error, and console. Toggle a chip off to hide that event type from the table, and toggle it back on to show it again.

LLM events are hidden by default. All other event types are shown by default. Toggle the **LLM** chip on to include LLM events in the table.

Click the reset button (`↺`) to restore all filters to their default states.

<Note>
  Your active filter choices are saved automatically to your browser's local storage, so they persist the next time you open a session in the same browser.
</Note>

## Streaming and reasoning drafts

While an agent runs, it streams two kinds of intermediate update to your session in real time:

* **Response stream drafts** deliver partial LLM response tokens as the model generates them.
* **Reasoning progress drafts** deliver intermediate reasoning updates as the model works toward an answer.

Both are stored as ephemeral drafts rather than as durable event rows. They render live in the session view but are not persisted to the [event log](#event-log), which keeps the durable log focused on completed LLM calls, tool invocations, and lifecycle transitions.

To consume these updates programmatically, connect to the [real-time streaming WebSockets](/platform/triggers#real-time-streaming-websockets).

## Find sessions with the command palette

Use the command palette to quickly search for and navigate to a session. Press `Cmd+K` (macOS) or `Ctrl+K` (Windows and Linux) to open the palette, type or select `sessions`, then press `Tab` to enter the sessions scope and search by name.

## Managing sessions

```bash theme={null}
# List sessions in a workspace
guild session list --workspace <workspace-id>

# Get session details
guild session get <session-id>
```