# Ask agent

On this page you can learn what the Ask agent is, how it runs a workflow, and how it gets work done.

## What the Ask agent is

*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.*

The Ask agent is the agent that runs workflows in Askpilot. It is built for one purpose, to execute a [workflow](https://askpilot.com/docs/workflows.html) end to end. A workflow is a business process written as a [PROCESS.md](https://askpilot.com/docs/process-md.html) file. Whenever a workflow starts, manually, on a trigger or through the API, Askpilot opens a [session](https://askpilot.com/docs/sessions.html) and the Ask agent takes it from there. It reads the PROCESS.md file and its related asset files, if any, and works through its tasks, handing each task to the right [source](https://askpilot.com/docs/sources.html), a subagent specialised in a certain kind of work, in order to execute the workflow successfully.

In the Askpilot app it appears as **Ask**. Every step it takes is a line in the session’s feed, so you can always see what it did and why.

## One Ask agent per Askpilot user

Every Askpilot user in an organization gets an Ask agent of their own by default, which they supervise and manage. A user can be one person, e.g. mark@company.com, a team, e.g. marketing@company.com, or the whole company, e.g. admin@company.com. That user’s Ask agent runs the workflows and uses the sources they have access to, in sessions that belong to them, keeps their files and memory, and turns to them when it needs input. None of that is shared with other users in the same Askpilot organization, unless a workflow or a source has been shared with them.

## Internal information

*Picture: a session in which the Ask agent turns “tomorrow morning” into a date and time using the Askpilot user’s timezone, and emails a colleague by name using the member list of the organization.*

Beyond the workflow and its sources, the Ask agent starts every session with some internal information about the organization it works in, so the PROCESS.md does not have to state it.

- **The current date and time**, in the timezone set in your [account settings](https://askpilot.com/docs/account.html#account). When a workflow or a message says “tomorrow”, “in two days” or “9am”, it works out the exact date and time from your timezone. For example, a calendar event it creates lands at the right time, and a follow-up due in two days is sent on the right day.
- **Your organization info**, the company name and website set under [Organization info](https://askpilot.com/docs/organization.html#info), so it knows which company it works for.
- **The members of your organization**, their names and email addresses, as listed under [Members](https://askpilot.com/docs/organization-members.html#members). This allows it, for example, to hand work over or escalate to a colleague based on their name and email.

## Interactive blocks

Instead of text-only replies, the Ask agent can use interactive blocks to reply in a session, for example an email draft you edit and send, a form you fill in, or a question with options to pick from.

### Text

*Picture: a Text block, a card with a title, the text and a copy button.*

Text the Ask agent wrote for you to reuse, for example a draft, a summary or a document, shown as a card with a title and a copy button.

The block is called `text` and has these fields.

| Field | Required | Purpose |
| --- | --- | --- |
| `title` | No | A short title shown above the text. |
| `content` | Yes | The text itself, as many lines as needed. |

To ask for it in a PROCESS.md, write for example: **“Give me the call summary as a text block titled Call summary.”**

### Email

*Picture: an Email block, a card with the title, the To, Subject and body fields, Cc and Bcc, a copy button for the body, and the Edit and Send buttons.*

An email draft with the **To**, **Subject** and body fields. Click **Edit** to change it and **Send** to send it through your email source. When no email source is enabled, the button changes into **Open in email** and opens the draft in your own mail app.

The block is called `email` and has these fields.

| Field | Required | Purpose |
| --- | --- | --- |
| `title` | Yes | A short title saying what the email is for, shown above it. |
| `to` | Yes | The recipients, comma-separated for more than one. |
| `cc` | No | Copied recipients. |
| `bcc` | No | Blind-copied recipients. |
| `subject` | Yes | The subject line. |
| `body` | Yes | The email text. |

To ask for it in a PROCESS.md, write for example: **“Draft the reply to the landlord as an email block for me to send.”**

### Tags

*Picture: a Tags block, a row of four tags, two blue for the property and the tenant and two red for the problem and its urgency.*

Colourful tags that reflect a status: blue for neutral context, red for a risk or something urgent, green for a good outcome. They can be used, for example, when a call comes in and you want to see at a glance who called, which property it is about and how urgent it is.

The block is called `tags`. Each tag has these fields.

| Field | Required | Purpose |
| --- | --- | --- |
| `label` | Yes | The text of the tag, one to five words. |
| `status` | Yes | `default` is blue, for neutral context; `danger` is red, for a risk or something urgent; `success` is green, for a good outcome. |

To ask for it in a PROCESS.md, write for example: **“Add tags for the property, the tenant and the urgency of the issue.”**

### Input needed

*Picture: an Input needed block under the heading Actions needing your approval, with the question, a line of context, two numbered options, a field for your own answer, the Submit button, the Skip this step button and the 1 of 2 counter.*

A question that pauses the session until you answer, with options to pick from or a field for your own answer. Click **Submit** to answer, or **Skip this step** to let the Ask agent carry on without it. Learn more at [When the Ask agent needs an input](https://askpilot.com/docs/sessions.html#when-it-needs-you).

The block is called `input_needed`, always wrapped in `reply_required`, and has these fields. When you use `Approval: required` in a PROCESS.md, on a todo or in an Instruction or a Rule for actions in general, the approval is presented with this block as well. Learn more at [Approvals](https://askpilot.com/docs/process-md.html#approvals).

| Field | Required | Purpose |
| --- | --- | --- |
| `question` | Yes | The question or the action to approve. |
| `context` | No | Why the Ask agent asks. |
| `options` | No | Choices to pick from. You can still type an answer of your own. |

To ask for it in a PROCESS.md, write for example: **“Before suggesting available slots to the client, ask me which slot to offer, with the available slots as options.”**

### Form

*Picture: a Form block under the same heading, with a title, a line of context, the Name prefilled, an optional Email field, a date picker, a city dropdown, a message field and the Submit button.*

A form to fill in the details the Ask agent needs before it can continue, for example the name, email and preferred date of a new applicant. Details it already knows are prefilled for you to check. Fill in the rest and click **Submit**.

The block is called `form`, always wrapped in `reply_required`, and has these fields.

| Field | Required | Purpose |
| --- | --- | --- |
| `title` | Yes | What the form is for. |
| `description` | No | A line of context. |
| `fields` | Yes | One entry per field, each with the parts below. |
| `label` | Yes | The label you see. |
| `type` | Yes | `short_text`, `long_text`, `calendar_picker`, `email`, `single_select` or `multi_select`. |
| `required` | No | `true` when the session cannot continue without the field. |
| `value` | No | A value the Ask agent already knows, prefilled for you to check. |
| `options` | No | The choices of a `single_select` or `multi_select` field. |
| `submit_label` | No | The button label, **Submit** by default. |

To ask for it in a PROCESS.md, write for example: **“When you ask me for the applicant’s details, use a form: name, email, preferred viewing date, and the city as a dropdown.”**

### Work summary and Work done

*Picture: a Work summary under the heading Summary, with a Call summary card and its copy button, two tags, one of them green for a good outcome, the Work done card with two items, and the Session closed card below it.*

The final report the Ask agent sends once the workflow has finished. It sums up what happened. For example, after a viewing request it reports what the caller asked for, and the work done shows the confirmation email it sent and the contact it updated in the CRM.

The block is called `work_summary`. It shows other blocks rather than fields, and the Ask agent uses it by default when the PROCESS.md sets no other completion format.

| Field | Required | Purpose |
| --- | --- | --- |
| `text` | No | The summary. |
| `tags` | No | Tags for the people, records and outcomes. |
| `email` | No | A draft for you to send. |
| `work_done` | No | The list of outcomes, one `item` per outcome, each with a `title`, a short label such as Email sent, and a `description` with the specifics: recipient, record, time, subject. |

To ask for it in a PROCESS.md, write for example: **“Finish with a work summary that includes a call summary, tags for the property and the outcome, and the work done.”**

### Session closed

The notice that the Ask agent has [marked the session as done](#mark-session-as-done). The session is now in the **Done** list.

The block is called `session_closed` and has one field.

| Field | Required | Purpose |
| --- | --- | --- |
| `content` | Yes | The Ask agent sends exactly this text: *This session has been moved to Done.* |

## Available tools

The Ask agent uses these tools to get the work done.

- **Workflow todos planning.** Lets it turn the workflow into a todo list and keep it up to date as the work is done.
- **Work orchestration.** Lets it hand each task to the right [source](https://askpilot.com/docs/sources.html).
- **File management.** Lets it list, read, write, edit and search the files in its file system.
- **Document creation and editing.** Lets it read and analyse, create new or edit existing Word, Excel, PowerPoint, PDF and CSV files.
- **Image reading.** Lets it read and analyse images.
- **Data analysis.** Lets it query and analyse any spreadsheet or data file with SQL.
- **Knowledge search.** Lets it search the documents in a [Files, Web pages, Google Drive or SharePoint source](https://askpilot.com/docs/sources.html#source-types) for the information it needs.
- **Data search.** Lets it query the spreadsheets and structured data files in a [Files](https://askpilot.com/docs/sources.html#files-sources), [Google Drive or SharePoint](https://askpilot.com/docs/sources.html#drive-sources) source with SQL, to filter, count and combine records, or search them by keyword.
- **Event subscriptions.** Lets it list the webhook events of a source and subscribe the session to them, so the session resumes the moment one of them arrives.
- **Session naming.** Lets it update the name of the session.
- **Mark session as done.** Lets it mark the session as completed, which moves it to the **Done** list.

## File system

The Ask agent has a local file system that lets it keep, read and work on files. Files and folders can be isolated to a single session, or shared and accessible in every session.

- **Working folder.** Every session gets a private folder of its own, where the work is done and where the files it creates and the files you drop in live.
- **Workflows.** A folder storing the workflows, each PROCESS.md with its assets.
- **Knowledge base.** A folder holding the documents and pages your [Files, Web pages, Google Drive and SharePoint](https://askpilot.com/docs/sources.html#source-types) sources bring in, with vector search built in.
- **Recordings.** A folder storing transcripts of your call recordings, if you have a phone system connected as a source.
- **Memory.** A folder storing user-related memory files.

## Memory

The Ask agent keeps a memory that lasts from one session to the next. It reads it at the start of every session and updates it when something worth keeping comes up, a preference you state, an instruction that should apply every time, a correction, or a fact you will need again. At any time you can ask it to read its memory notes back to you, or tell it to update them.

## How it operates

When a workflow is started, the Ask agent follows the same flow every time.

1. **It reads the workflow.** The name, the description and the PROCESS.md file: its role, the instructions, the rules, the todos to complete and the paths it can run. It also reads any related [asset files](https://askpilot.com/docs/process-md.html#assets), the templates, price lists, tone guides and other files the PROCESS.md names, as extra context or as the files it works on. To execute the work it follows the PROCESS.md exactly.
2. **It works through the todos.** One task at a time, in order, deciding at each step what the task needs: a record from your CRM, a message to a customer, a document to fill in, a fact from the web, or whatever else the workflow says has to be done. The checklist on the right of the session shows the todos and ticks them off as they are done. How the file becomes that list, with or without todos, is explained at [How the Ask agent turns the PROCESS.md into tasks](https://askpilot.com/docs/process-md.html#tasks).
3. **It uses sources to get the work done.** The Ask agent delegates each task to a source, a subagent specialised in a certain kind of work, set by its type. For example, to send an email it hands the task to a source of the Microsoft Outlook type, which sends it through your Outlook account and reports back.
4. **It stops when the workflow says so.** If the workflow has rules that require human intervention, such as a step that needs your approval, a question only you can answer, or a situation it is told to escalate, the session stops and waits. In the sessions list it carries the **Awaiting input** tag, and in the session you see what input the Ask agent needs from you. Your answer lets it carry on.
5. **It resumes the work automatically.** A session that has stopped can be resumed without you, in three ways. Auto-run re-runs it on a schedule, hourly to monthly, until every task is done. An event the workflow subscribed to, a WhatsApp reply for example, resumes it the moment the event arrives. And your own systems can start another workflow in it through the API. Learn more at [Continuing a session automatically](https://askpilot.com/docs/continuing-a-session.html).
6. **It reports.** Each action and its result is written to the session as it happens, so you can follow the run while it is going or read it back afterwards. It never claims an action succeeded unless the source confirms it, and never presents partial work as complete.
7. **It carries the work through to the end.** It keeps going until every todo is done, across every tool the workflow needs to get the work done, then moves the session to **Done**. If the workflow requires human intervention, it stops to ask for your input and then carries on.

> **To change how the Ask agent works, update the workflow** The Ask agent reads and applies every line of the PROCESS.md, so a change to the process or its related asset files, if any, changes what it does on the next run. If a run did something you did not expect, the fix is almost always a clearer instruction or a rule in the file. The [PROCESS.md](https://askpilot.com/docs/process-md.html) pages show the lines that most often need it.

---
This is the Markdown version of https://askpilot.com/docs/ask-agent.html. The whole documentation as one file: https://askpilot.com/docs/llms-full.txt