Agent setup guide
Reader's Advisory Picks
A patron's “what should I read next?” becomes 5 personal picks your library owns, with call numbers, approved by a librarian and emailed.
What it does
A patron's “what should I read next?” becomes 5 personal picks your library owns, with call numbers, approved by a librarian and emailed.
- Starts from each “what should I read next?” request your form posts to its webhook.
- AI plans 1–3 searches of the free Open Library catalogue from the books the patron loved, their mood, format and age band.
- It shortlists up to 12 candidates and looks each one up in your catalogue export sheet.
- AI picks up to 5 titles you own, each with a “why you'll like it” line, the call number, format and branch.
- A librarian approves every list in Reviews before it's emailed, with replies to your readers' advisory inbox.
What it needs
- A paid plan (agents run live on paid plans).
- An AI provider key (Settings → AI Providers).
- Google Sheets, connected in Settings → Integrations, plus an HTTP / Custom API connection to https://openlibrary.org (free, no key).
- A catalogue export sheet of the titles you own (refresh it monthly), and a form that can post JSON to a webhook.
What it doesn't do
- It suggests only titles found in your catalogue export, matched by title, so it can miss editions with different titles.
- It doesn't place holds or check availability (ILS systems aren't connectors).
- For children and teens it uses the age band only: no names or other details.
- Nothing is sent before a librarian approves the list.
Availability and plans
Available
Its workflow is built and tested, and every app it needs is live. You can get it and set it up now.
Included free on the Enterprise plan; on other paid plans it's a one-time purchase per workspace (the price is on the Agents page). The Agents page in the app always shows its current status.
Before you start
- A paid plan: agents run live, and the Free plan only runs Dry Runs.
- An AI provider key (OpenAI, Anthropic, Google and more) in Settings → AI Providers. AI usage is billed by your provider.
- These apps, connected in Settings → Integrations: HTTP / Custom API and Google Sheets.
- A form, app or system that can send each new item to a webhook URL (the agent starts from a webhook).
- About 20 minutes.
Set it up step by step
Get the agent first (buy it, or it's already yours when your plan includes it), then in Agents → My agents press “Set up this agent”. That creates the agent's workflow in your workspace (it counts towards your plan's workflow limit) and opens the canvas with a setup checklist above it. Each item links to the exact place to go and ticks itself off when it's done.
1. Connect your AI provider
The AI steps run on your own key (OpenAI, Anthropic, Google and more). Add one in Settings → AI Providers.
2. Connect Open Library (HTTP / Custom API)
In Settings → Integrations, add an HTTP / Custom API connection named “Open Library” with base URL https://openlibrary.org and Authentication “None”. Open Library's search is free and needs no key; the agent makes at most 3 searches per request.
3. Connect Google Sheets
Connect the Google account that can open your catalogue export (Settings → Integrations → Google Sheets).
4. Pick the Open Library connection
Open “Search Open Library” and pick the connection.
| Setting | What to enter | In step |
|---|---|---|
| Open Library connection | The HTTP / Custom API connection with base URL https://openlibrary.org and Authentication “None”. Pick your connected HTTP / Custom API account. | “Search Open Library” |
5. Pick your catalogue export
Open “Find it in your catalogue” and pick your account, spreadsheet, tab and the title column.
| Setting | What to enter | In step |
|---|---|---|
| Google account (catalogue) | The Google account that can open your catalogue export. Pick your connected Google Sheets account. | “Find it in your catalogue” |
| Catalogue export spreadsheet | Paste the link of the spreadsheet with your catalogue export. | “Find it in your catalogue” |
| Catalogue export tab | The tab with one row per title you own (Title, Author, Call number, Format, Branch), e.g. “Catalogue”. | “Find it in your catalogue” |
| Title column name | The header of the column with the main title, exactly as written in the sheet, e.g. Title. | “Find it in your catalogue” |
6. Describe your library
Open “Pick 5 titles you own” and replace the placeholder with your holds instructions, formats and sign-off.
| Setting | What to enter | In step |
|---|---|---|
| Your library and holds | Replace the placeholder with your library's name, how patrons place a hold, the formats you lend, any collections to favour and your sign-off. It starts as “[PASTE YOUR LIBRARY'S NAME, HOW PATRONS PLACE A HOLD (CATALOGUE LINK, PHONE, DESK), WHICH FORMATS YOU LEND (PRINT, LARGE PRINT, AUDIOBOOK CD, E-BOOK…), ANY COLLECTIONS TO FAVOUR AND YOUR SIGN-OFF HERE]” until you replace it. | “Pick 5 titles you own” |
7. Add your readers' advisory inbox
Open “Email the patron” and enter the Reply-to address.
| Setting | What to enter | In step |
|---|---|---|
| Readers' advisory inbox (replies) | Patrons' replies come back to this address. | “Email the patron” |
8. Test it with Dry Run
Press Dry Run: the agent runs on sample data with no messages sent and nothing written to your apps.
9. Switch the trigger on
Open the trigger, switch the webhook on and copy its URL and secret into your readers' advisory form.
How it works
The agent is a normal workflow with 12 steps (3 AI steps, with a person approving in Reviews). You can open, edit and monitor it like any other workflow.
- “What should I read next?” form — Starts when your form or app sends data to the agent's webhook URL. Starts when your readers' advisory form posts a request: books they loved, mood, format, age band and anything to avoid.
- Plan the search — AI step (runs on your AI provider key). AI reads what the patron loved and wants, and picks 1–3 short Open Library searches (subjects, authors, themes).
- Each search — Repeats the steps below for each item (up to 3 per run). Runs each planned search on Open Library (at most 3).
- [For each item — “Each search”] Search Open Library — HTTP / Custom API: Send a request. Searches the free Open Library catalogue (no key) and returns up to 10 works per search: title, author, first published year and subjects.
- Shortlist the candidates — AI step (runs on your AI provider key). AI removes duplicates, books the patron already read and anything to avoid, and keeps up to 12 candidates to look up in your catalogue.
- Each candidate — Repeats the steps below for each item (up to 12 per run). Looks every candidate up in your catalogue export (up to 12).
- [For each item — “Each candidate”] Find it in your catalogue — Google Sheets: Find a row. Looks the title up in your catalogue export sheet (case-insensitive match on the title column) to get the call number, format and branch.
- Pick 5 titles you own — AI step (runs on your AI provider key). AI picks up to 5 titles found in your catalogue, writes a “why you'll like it” line for each with the call number, and drafts the email.
- Librarian approves the list — A person approves or rejects it in Reviews (the run waits). A librarian checks the picks (owned, right age, right format) and the email in Reviews, edits anything and approves; nothing is sent before that.
- Not sent — Kept in the run history. Branch: Rejected. Nothing was sent; the run history keeps the list.
- Email the patron — Sends an email from your workspace's sender. Branch: Approved. Sends the approved reading list to the patron, with replies going to your readers' advisory inbox.
- List sent — Kept in the run history. The run history keeps the picks and the email.
Test it with Dry Run
Press Dry Run in the canvas. The agent runs on the sample data stored on its trigger (the “Sample data for Dry Run” box), so you can check every step's output before anything is live. Edit the sample to match the fields your own form or app sends.
Sample data fields
patron_name, email, loved_books, mood, format, age_band, avoid, notes.
- Nothing is sent or written: app actions, emails and Slack posts are simulated, and AI steps don't call your AI provider.
- Approval steps use the Dry Run decision you pick in the step's settings (approved, rejected or timeout), so you can try each branch.
- For-each loops repeat only the first 3 items.
Go live
- Open the trigger, switch the webhook on and copy its URL and secret into your readers' advisory form.
- The webhook is protected by a secret: send it in the header shown in the Activation panel (requests without it are refused with 403). Each request starts one run.
- The setup checklist adds a “paid plan” item before activation: live runs need a paid plan (the Free plan only runs Dry Runs).
- When every checklist item is done and the trigger is on, the checklist says “Live — this agent is running”. Follow its runs in the workflow's History tab and in Analytics → Agents.
Questions
What should the form send?
A JSON POST with patron_name, email, loved_books, mood, format, age_band (e.g. Adult, Teen, Children), avoid and notes. Your form or site posts it with the webhook's signature header.
What catalogue export do I need?
A Google Sheet with one row per title you own: Title (the main title, without subtitle), Author, Call number, Format and Branch. Most ILS report tools can export this; refresh it monthly. Lookups match the title exactly (ignoring case), so titles with long subtitles may be missed.
Does it place holds?
No. ILS systems aren't connectors. The email tells the patron how to place a hold your usual way.
Troubleshooting
- “No AI provider connected” or a rejected key: connect or fix the key in Settings → AI Providers, then press Test there.
- A checklist item stays unticked: the setting is still empty or still contains its placeholder text. Open the step from the checklist and fill it in.
- An app step fails with “Needs reconnect”: the account's access was revoked or expired. Reconnect it in Settings → Integrations.
- Nothing happens when your form sends data: check the webhook is switched on and the request carries the secret header (403 means it's missing or wrong).
- A run shows as paused: it's waiting for someone in Reviews to approve or reject it.
- A step failed: open the run in History and check that step in the Trace tab for the error and what it received.
Generated from the agent's own workflow, so it always matches what the agent does. Last updated .