Session

• A session in Guild is the full log of an agent's execution run: every event, every tool call, every state change from start to finish.
• Sessions can be resumed with --resume <session-id>. Resuming pins the session's agent version and workspace, so the resumed run behaves exactly like the original.
• Guild sessions are not the same as login sessions. A poll timeout during a session does not discard the session; the session stays intact and can be resumed later.
• Sessions have types (chat, webhook, time, agent_test) that reflect how they were started, and can be inspected across the whole workspace with guild session list.

A session in Guild is the durable record of one full execution of an agent. It captures the user input, every tool call the agent made, every response from an LLM, every state change, and the final output. If an agent runs, a session was created.

Sessions matter because agents are not single request/response operations. A single session can involve dozens of steps, multiple tool calls, human approvals, retries, and pauses. The session is the object that holds all of that together and makes it inspectable after the fact.

The word "session" is doing a specific job here. It is not the same as a login session (the thing that tracks whether a user is signed in). A login session ends when you log out or your cookie expires. A Guild session ends when the agent completes, errors, or is explicitly stopped — and even then, the record persists.

Sessions have types based on how they started

Guild sessions carry a type that reflects the trigger source: chat (started from a person typing in the app or CLI), webhook (started by a webhook trigger firing on an external event), time (started by a time trigger on a schedule), and agent_test (started from guild agent test during agent development).

You can filter session lists by type using guild session list --type chat (or webhook, time, agent_test) to see exactly what a class of automation is doing across the workspace.

Resume is a first-class operation

Every session has an ID, and every session can be resumed with --resume <session-id>. Resuming works in interactive mode, in --mode json, and in --mode jsonl. When you resume, the CLI skips version resolution and ephemeral builds because the resumed session already pins the exact agent version and workspace it started with. --workspace and --agent-version flags are ignored on resume for that reason.

In --mode json and --mode jsonl, resuming appends your input to the specified session as a new user message instead of starting a new session. The CLI reports the resumed session's ID and only polls for events created after your message. That's how you build long-running interactions without losing state on transient failures.

A poll timeout does not end the session

If a response poll times out during a session, the session is not discarded. Guild is deliberate about this: transient network or infrastructure issues should not destroy the state of a long-running agent. The CLI reports the session ID and a resume hint (guild agent test --resume <session-id> or the equivalent for chat), so you can pick up where the timeout left you.

Sessions belong to a workspace

Every session runs in the context of a workspace, inherits its workspace context, and uses the workspace's connected credentials. That's why guild session list scopes to the default workspace unless you specify otherwise.

Auditability is not optional for production agents

An agent doing real work — closing tickets, opening pull requests, sending messages — needs an audit trail. Sessions are that audit trail. Every action an agent took, every input it saw, every decision it made is captured in the session record. When a stakeholder asks "what did the agent actually do," the answer is in the session.

Resume is the difference between resilient and fragile

Agents run against the real internet: LLM providers rate-limit, networks blip, infrastructure restarts. If a transient failure destroyed the session, you would either lose the work or waste tokens re-doing it. Because Guild sessions survive poll timeouts and are explicitly resumable, agents can be genuinely long-running without you having to build recovery logic yourself.

Session types map onto operational questions

Filtering sessions by type is how you answer the questions leaders actually ask. How much activity came from webhook automations this week? How much did our scheduled agents cost last month? Which agent has the most chat sessions? Types make those questions one command away.

List and filter sessions

guild session list                       # Sessions in the default workspaceguild session list --type chat           # Only chat-started sessionsguild session list --type webhook        # Only webhook-triggered sessionsguild session list --type time           # Only time-triggered sessionsguild session list --type agent_test     # Only sessions from guild agent test

Resume a session

guild agent test --resume <session-id>   # Resume a test sessionguild agent chat --resume <session-id>   # Resume a chat session

Works in interactive, --mode json, and --mode jsonl. Version resolution is skipped because the resumed session pins its agent version and workspace.

Recovering from a poll timeout

If a response poll times out, Guild's CLI prints the session ID and the exact resume command. Copy the hint from the error output and re-run to pick up where the timeout left you. No state is lost.

Inspect sessions spawned by a specific trigger

guild trigger sessions <trigger-id>

Shows every session that a specific trigger produced. Useful for reviewing what a webhook or time trigger has actually done since it was activated.

Session IDs are how you reference a run

Everywhere Guild talks about a specific execution — logs, error output, resume commands, trigger inspection — it refers to the session ID. Copy the ID from the CLI output when you want to come back to a specific run.

Resuming ignores workspace and version flags

--workspace and --agent-version flags on a resume are ignored, because the resumed session already knows its workspace and pins its agent version. If you need to run against a different workspace or version, start a new session; do not try to "redirect" an existing one.

Type filters are your friend for triage

A workspace with active agents can rack up hundreds of sessions in a week. --type filters (chat, webhook, time, agent_test) are the fast way to slice that down to what you actually want to look at.

Poll timeouts vs. real failures

A poll timeout is a transient issue with waiting for events, not a failure of the agent. Retry the resume command; the session is fine. A real agent failure is a different signal and shows up in the session's event log.

Guild is a control plane for AI agents, a place to build, deploy, and govern the agents your teams run in production. Sessions are the durable, inspectable record of everything those agents actually do.

• The CLI commands reference documents every session command in full.
• Sessions live inside a workspace and can be spawned by triggers or by a chat with an agent.
• Explore the Guild CLI and the rest of the platform at guild.ai.