Skip to main content
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
  2. Click New session
  3. Select an agent, type a message, and press Enter

​
CLI

​
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:

​
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.
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: 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: 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.
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.

​
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, 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.

​
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