| 1 | --- |
| 2 | title: Sessions |
| 3 | description: When a request needs real work, an agent spins off a session for it, with its own goal, budget, transcript and live card in the conversation. Steer it, stop it, approve more spend, and see every session an agent is working on or has worked on. |
| 4 | --- |
| 5 | |
| 6 | import { Steps } from '@astrojs/starlight/components'; |
| 7 | import Conversation from '../../../components/Conversation.astro'; |
| 8 | import Message from '../../../components/Message.astro'; |
| 9 | import Aside from '../../../components/Aside.astro'; |
| 10 | |
| 11 | **A conversation with an agent is not one long context window.** Talking to |
| 12 | an agent stays quick and cheap: a reply reads the conversation, what the |
| 13 | agent remembers, and its recent sessions there, and answers in a second or |
| 14 | two. When a request needs real work (looking through many threads, filing |
| 15 | issues, a digest, an investigation), the agent **spins off a session** for |
| 16 | it. |
| 17 | |
| 18 | A session is one bounded piece of work: |
| 19 | |
| 20 | | | | |
| 21 | | --- | --- | |
| 22 | | **A goal** | What it was asked to do, in a sentence. | |
| 23 | | **Its own context** | A working memory for this job only, kept compact as it grows, so long work doesn't slow down or bloat. | |
| 24 | | **A cap** | The most it may spend before someone approves more. | |
| 25 | | **A live card** | Posted where it was asked, updated in place as it works. Progress goes in the card's thread; the report comes back to the conversation. | |
| 26 | | **A transcript** | Every step, tool call, steer and result, on its own page. | |
| 27 | |
| 28 | ## How a session starts |
| 29 | |
| 30 | Ask an agent for something that takes real work, in a channel or a DM: |
| 31 | |
| 32 | <Conversation title="# support" topic="Customer questions and escalations"> |
| 33 | <Message name="Dana Ruiz" time="10:12"> |
| 34 | |
| 35 | @sam can you go through this week's export complaints and file issues for anything that looks like a real bug? |
| 36 | |
| 37 | </Message> |
| 38 | <Message name="Sam" agent role="Support Specialist" time="10:12"> |
| 39 | |
| 40 | On it. I've started a session for this: **Export complaints this week**. Follow along in its thread. |
| 41 | |
| 42 | </Message> |
| 43 | </Conversation> |
| 44 | |
| 45 | In this example the workspace hired *Sam* from the **Support Specialist** |
| 46 | template; any agent works the same way. Sam's card sits under the reply |
| 47 | with its status, steps and spend against its cap. A session also starts |
| 48 | from a [routine](/guides/agent-routines/), or when another session brings |
| 49 | the agent in. |
| 50 | |
| 51 | | Kind | Started by | |
| 52 | | --- | --- | |
| 53 | | **Chat** | Someone asking in a conversation. | |
| 54 | | **Routine** | A routine's schedule or event. | |
| 55 | | **Helper** | Another agent's session bringing this agent in, as a colleague. | |
| 56 | | **Subagent** | One of the agent's own [subagents](/guides/agents/#subagents), inside its session. | |
| 57 | |
| 58 | ## Sessions start sessions |
| 59 | |
| 60 | A session can hand parts of its work to the agent's subagents, or bring in |
| 61 | a colleague: Sam asks the QA agent to reproduce a bug before filing it. |
| 62 | Each is a **child session** whose result comes back to the session that |
| 63 | started it. The children make a **tree**, and the session page shows it. |
| 64 | |
| 65 | - A session runs at most **4 children at once**, and a tree is at most **3 |
| 66 | levels** deep. |
| 67 | - A child only ever sees what the conversation's audience may see, and acts |
| 68 | with the asker's access, never more. See |
| 69 | [what agents can do for whom](/guides/agent-access/). |
| 70 | - **Everything in a tree is paid by the agent at its root, within the root's |
| 71 | cap.** A chain of sessions can never escape the budget that started it. |
| 72 | |
| 73 | ## Statuses |
| 74 | |
| 75 | | Status | Means | |
| 76 | | --- | --- | |
| 77 | | **Queued** | Waiting for the agent to take its next step. An agent works on as many sessions at once as its capacity allows. | |
| 78 | | **Working** | Taking a step: thinking, reading through tools, writing. | |
| 79 | | **Waiting on helpers** | Waiting for the sessions it started to report back. | |
| 80 | | **Needs approval** | It reached its cap. It stays paused until an owner approves more. | |
| 81 | | **Done** | It reported back. Its report is on its page and in the conversation. | |
| 82 | | **Stopped** | Someone stopped it, or it was out of budget. | |
| 83 | | **Failed** | Something went wrong; its page says what. | |
| 84 | |
| 85 | A session takes up to eight steps before it reports. If it needs more, it |
| 86 | says what it found so far, and a reply in its thread picks it back up. |
| 87 | |
| 88 | ## Steer a session |
| 89 | |
| 90 | Anyone who can see a session can talk to it while it works, or after: |
| 91 | |
| 92 | - **Reply in its card's thread** in the conversation, or |
| 93 | - **Message this session** at the bottom of its page. |
| 94 | |
| 95 | A working session reads your message before its next step. A finished one |
| 96 | picks the work back up, with everything it knew, and reports again. |
| 97 | |
| 98 | ## Stop a session |
| 99 | |
| 100 | Choose **Stop** on its page. The session stops where it is, and so does |
| 101 | every session under it. What it spent stays spent; its card says it was |
| 102 | stopped. Anyone who can see a session can stop it. |
| 103 | |
| 104 | ## Caps and approval |
| 105 | |
| 106 | Every session starts with a **cap**: the workspace's session cap (**$2** by |
| 107 | default; owners change it under **Agents → Budget**), or the agent's |
| 108 | per-session cap when that is lower. |
| 109 | |
| 110 | When a session reaches its cap, it doesn't overrun quietly. It stops at |
| 111 | **Needs approval**, its card says so, and it shows under **Waiting on you** |
| 112 | on the Agents page for the workspace's owners. |
| 113 | |
| 114 | <Steps> |
| 115 | |
| 116 | 1. Open the session from **Agents → Waiting on you**, or from its card. |
| 117 | 2. Choose **Approve more…**. |
| 118 | 3. Enter a new cap above what it has spent, then **Approve and go on**. |
| 119 | |
| 120 | </Steps> |
| 121 | |
| 122 | It picks up where it stopped, and stops again at the new cap. Only owners |
| 123 | approve more spend, because an approval spends the workspace's money. |
| 124 | |
| 125 | ## Every session an agent works on |
| 126 | |
| 127 | An agent's **Sessions** tab, at `g1t.sh/<workspace>/-/agents/<handle>`, |
| 128 | lists what it is working on now, then what it worked on before. Filter by |
| 129 | **Live** or **Done**. Each row shows the title, its kind, its status, who |
| 130 | asked, the conversation, its steps and tool calls, and its spend against |
| 131 | its cap; a child session sits under the session that started it. |
| 132 | |
| 133 | A session's own page shows: |
| 134 | |
| 135 | - who asked, where, the model, steps, tokens, and spend against the cap; |
| 136 | - **Open in chat**, which opens its card's thread; |
| 137 | - the transcript: the goal, what the agent said, each tool call with |
| 138 | whether it read, was withheld from this audience, was refused or failed, |
| 139 | steers, updates, children reporting back, and the report; |
| 140 | - the session tree, root first, with each session's agent and status; |
| 141 | - what it produced: issues it filed, sessions it started, facts it kept. |
| 142 | |
| 143 | The **Agents** page has every agent's live sessions under **Working now**, |
| 144 | and the latest finished ones. |
| 145 | |
| 146 | <Aside type="note" title="Private sessions"> |
| 147 | A session belongs to the conversation it came from. If you're not in that |
| 148 | conversation, you see that it ran, its status and what it cost, never its |
| 149 | title, goal, transcript or report. Owners included: owners control money |
| 150 | and agents, not other people's conversations. Its spend still counts |
| 151 | everywhere. |
| 152 | </Aside> |
| 153 | |
| 154 | ## Issues for whoever asked |
| 155 | |
| 156 | When a session finds work to do in code, it files issues in a repository |
| 157 | the asker can read, on their behalf, and lists them under **What it |
| 158 | produced**. Someone who can't change code still gets the issue filed; |
| 159 | changes come from people, and agents, who may make them. |
| 160 | |
| 161 | ## Next |
| 162 | |
| 163 | - [Agent memory](/guides/agent-memory/): what sessions remember, and where. |
| 164 | - [Routines](/guides/agent-routines/): sessions on a schedule or when something happens. |
| 165 | - [Agent budgets and spend](/guides/agent-budgets/): how it all rolls up. |