> ## Documentation Index
> Fetch the complete documentation index at: https://pigeonholeapp.co.uk/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Agents

> Describe a report in plain English, preview it, and have it emailed to you on a schedule.

Agents let you build your own reports without waiting for one to be added to Pigeonhole. You describe the data you want in plain English, Pigeonhole works out the query and shows you the results, and you save it so you can run it again or have it emailed to you on a schedule.

<Note>
  Agents are a preview feature. The page is headed **Agents (Preview)** in the app while we finish it off. Please send any feedback to [Pigeonhole Support](mailto:support@pigeonholeapp.co.uk).
</Note>

<Info>
  Open in app: [Settings → Agents](/docs/app/admin/settings/agents)
</Info>

## Creating an agent

1. Click **Create Agent**.
2. In the **Describe your report** box, write what you want in plain English — for example *"Get me all children with funded sessions that don't have an approved funding form"*. Click **Generate**.
3. Pigeonhole shows a **Preview** with the number of rows found and the first of them. Read it carefully — this is the point to catch a misunderstanding. If it isn't what you meant, reword your description and click **Regenerate**.
4. Give the agent a **Title** — one is suggested for you, and you can change it.
5. Click **Save Agent**.

<Tip>
  Be specific about the time period you mean. Descriptions like "last week" or "this term" are stored as a rolling period, so the report stays current every time it runs rather than being frozen to the dates you built it on.
</Tip>

## Scheduling delivery

A schedule is optional. Without one the agent is a saved report you run whenever you need it.

1. In the **Schedule** box, describe when it should run in plain English — for example *"every Monday at 8am"*.
2. Click **Set Schedule**. Pigeonhole works out the schedule and shows you the **Next run** date so you can check it landed where you expected.
3. Add one or more addresses in **Delivery Email**, separated by commas or semicolons. Each run is emailed to them as a CSV.
4. Click **Save Agent**.

<Note>
  A delivery email needs a schedule. If you add an address without setting a schedule, Pigeonhole will ask you for one before it saves.
</Note>

Changing the wording in the **Schedule** box clears the schedule, so click **Set Schedule** again to confirm the new one before saving.

## Running an agent and viewing history

On the agents list, each row shows its **Schedule** (or **Manual** if it doesn't have one) and when it **Last Run**.

Click the clock icon against an agent to open **Execution History**. From here you can:

* See every run with its date, status, row count, and the address it was emailed to.
* Download the results of any run as a CSV using the download icon.
* Run the agent immediately with the green play button, without waiting for its schedule.

Use the **...** menu on the list to edit or delete an agent. Deleting one also deletes its execution history and files.

## Frequently Asked Questions

### What data can an agent see?

Only your own nursery's data, and only the kinds of information you can already see in Pigeonhole. Agents cannot reach another setting's data.

### Can an agent change anything?

No. Agents only read data and produce reports. Any change to a child, invoice or record still goes through the normal screens.

### My agent returned no rows — what went wrong?

Usually the description was read differently to how you meant it. Reword it to be more specific — name the exact status, room or period you mean — and click **Regenerate** to preview again before saving.

### Can I get the results as a spreadsheet?

Yes. Scheduled runs are emailed as a CSV, and you can download the CSV from any past run in **Execution History**.