# Sessions On this page you can learn what a session is, how to start one, and where to find and follow your sessions. ## What a session is A session is where the [Ask agent](https://askpilot.com/docs/ask-agent.html) executes the workflow and where you can follow each action it took. Every time a [workflow](https://askpilot.com/docs/workflows.html) starts, manually, on a trigger or through the API, Askpilot opens a session for it, for the Askpilot user who has access to that workflow. ## How to start a session *Picture: the Run workflow screen. The message box has a workflow selected on its Run line, a Context line with the details for this run, the Sources and Auto-run dropdowns, and the send button.* A session is started by running a workflow. A workflow can be started in three ways. - **Manually.** Click **Run workflow** in the left sidebar to start it. Learn more at [Manually](https://askpilot.com/docs/workflows.html#run-manually). - **On a trigger.** Set up a trigger that starts the workflow. Learn more at [On a trigger](https://askpilot.com/docs/workflows.html#run-trigger). - **Through the API.** Trigger a workflow from your own system via the API. Learn more at [Through the API](https://askpilot.com/docs/workflows.html#run-api), or at [Start workflows through the API](https://askpilot.com/docs/developers/workflows.html) in the Developers section. ## What a run is A run is one turn of the Ask agent in a session. A session is made of runs. The first run starts when the session opens, and every later run starts when something continues the session: a message you send, an event the session was waiting for, auto-run on its schedule, or a request through the API. At the start of every run the Ask agent re-reads the whole PROCESS.md and continues from where the session was, without repeating finished work, so a change you save to the workflow applies from its next run. A run ends when the Ask agent has finished every task it can do at that moment, or when it needs an input from you. The session then waits for the next run. Every run appears in the feed of the [session view](#session-view). ## Open and Done *Picture: the left sidebar, with Run workflow, Workflows, Sources and Settings, the Open and Done lists and the sessions in the Open list, one of them tagged Awaiting input.* Your sessions are listed in the left sidebar, under **Open** and **Done**. - **Open** lists the sessions that are still in progress: the Ask agent is working, or it is waiting for an input from you. A session that is waiting is marked **Awaiting input**. - **Done** lists the sessions that are finished. In both lists, sessions are ordered by the time of their last run, the most recent first. ### How a session moves to Done or Open A session moves to **Done** in two ways. - **The Ask agent moves it there itself**, with its [Mark session as done](https://askpilot.com/docs/ask-agent.html#mark-session-as-done) tool, once every todo of the workflow is done. - **You mark it done yourself**, with the tick in the top right corner of the session. A session in **Done** is closed: **it no longer listens for the [events](https://askpilot.com/docs/continuing-a-session.html#events) it was waiting for**, so an event that arrives for it does not resume it. To pick a session up again, open it and either click the button in the top right corner to move it back to **Open**, or send it a message, which moves it back to **Open** automatically. Either one continues the session. ## The session view *Picture: a session, with the title bar and its auto-run control, the feed showing the event that started the session and the Ask agent’s actions, the message box with the Sources button, and the workflow checklist on the right.* Open a session to follow it. - **The title bar** names the session and carries two controls: the [auto-run](https://askpilot.com/docs/continuing-a-session.html#auto-run) control, so you can set an auto-run frequency or turn it off for this session, and the tick that marks the session as done. - **The feed** shows the message or event that started the session and everything that happened since, in order: a log of every action the Ask agent executed, the details of every event that arrived, every time auto-run re-ran the session, and every message you sent manually. - **The checklist on the right** tracks the workflow’s todos as they are worked through. For a session without a workflow it stays empty. - **The message box at the bottom** lets you send a message to the Ask agent once a run is completed. The **Sources** button under it lets you select the sources the Ask agent will use to execute the run. The selection applies when you send the message manually. ## When the Ask agent needs an input *Picture: the same session stopped on an Input needed card, with the Ask agent’s question, an answer typed in, and the Submit and Skip buttons.* When the Ask agent needs something from you, the session stops and shows you what it needs, a question to answer or an action to approve. Type your answer or choose an option and click **Submit**, or click **Skip** to let the Ask agent carry on without it. Several questions asked at once arrive as one panel with one **Submit** button. Skipping one of them skips only that item: the Ask agent does not ask about it again and does not work around it. While it waits, the session sits in **Open** and carries the **Awaiting input** tag in the sessions list. Until you answer, the session does not continue in any way: not through the API, not on an event, and not on its [auto-run](https://askpilot.com/docs/continuing-a-session.html#auto-run) schedule. The Input needed card is one of the interactive blocks the Ask agent replies with. Learn more at [Interactive blocks](https://askpilot.com/docs/ask-agent.html#blocks). ## How to stop a run *Picture: the same session while the Ask agent is working, with the stop icon in the message box in place of the send button.* While the Ask agent is working, the message box shows a stop icon in place of the send button. Click it to stop the run. The session stays in **Open**, with everything the Ask agent did so far in the feed. You can also write to it in the message box. “Pause” makes it stop before its next action and hold the session, with its todos and its event subscriptions, until you tell it to resume. “Stop” ends the workflow: the Ask agent tells you what was done, what was in progress and what was left undone. ## Continuing a session automatically Besides a message you send, an open session continues on its own in three ways. - **On an event.** An event the session is waiting for arrives and resumes it. - **On auto-run.** Auto-run re-runs the session on its schedule. - **Through the API.** Your own systems start another workflow in the session. Learn more at [Continuing a session automatically](https://askpilot.com/docs/continuing-a-session.html). --- This is the Markdown version of https://askpilot.com/docs/sessions.html. The whole documentation as one file: https://askpilot.com/docs/llms-full.txt