Set up schoolAgent

schoolAgent is the AI agent that answers questions on your district's website and, for people who sign in, inside schoolOS. Admin › Agent › Configuration is where you decide how it looks, what it tells people before they chat, the instructions it follows, and where it's available.

Who can open it#

People whose role has Manage the agent (the Full level of schoolAgent in Admin › People › Roles), in an account whose plan includes schoolAgent. Without schoolAgent in the plan, the page sends you back to Admin.

Adding or changing knowledge on the Knowledge tab also needs Manage knowledge.

How saving works#

Each card has its own save button: Save Appearance, Save Access, Save Disclosure, Save Prompt, Save prompts and Save Availability. Nothing is saved until you select it, and a save only stores that card. If you leave the page first, your changes are lost.

Two things save the moment you pick a file: the Header Logo and the Launcher logo uploads.

A confirmation appears in the top-right corner after each save, or the reason it failed.

The tabs#

• Config. How the agent looks and behaves, and where it's available. This article.
• Knowledge. What the agent answers from. See Knowledge.
• Routing. When and where the agent hands a question to a person. See Route questions to a person.
• Deploy Code. Turning the agent on and putting it on your website. See Add schoolAgent to your website.

Whether the agent is live#

The top of the Config tab shows whether the website agent is on and whether its snippet has been seen on your site:

• Switched off, not installed. Nobody can see it. You can paste the snippet safely.
• Switched on, waiting for the snippet. It will appear the moment the snippet is on your site.
• Installed, but hidden. The snippet is on your site, but the agent is off.
• Live on your site. On, installed and answering.

The button next to it, Turn on in Deploy or Turn off in Deploy, takes you to the Deploy Code tab, where the switch is.

Under it, the Config tab has three parts: Appearance, Behavior and Availability.

Appearance#

Open Appearance Settings to change how the chat window and its launcher button look. The preview on the right (on wide screens) shows your changes as you make them, before you save. It uses your first name in place of {firstName}.

Identity#

• Agent Name. Shown in the chat window's header. Use a name families will recognize, like your district's name and "Assistant".
• Subheading. A short line under the name. **bold** and *italics* work.
• Default Welcome Message. The first thing people see when they open the chat. {firstName} becomes the first name of someone who's signed in, and "there" for everyone else. Bold, italics and links work.

If one of these uses words like "I" or "we", a hint suggests rewording it, because it reads as a person speaking. It's advice only: you can still save.

Branding#

• Use the account logo. On, the agent uses the logo from the Branding tab of Admin › Account › Account Settings, and follows it when it changes. Off, the agent keeps its own. If your account has no logo yet, the switch is off with a link to add one.
• Header Logo. The logo in the chat header. PNG, JPG or GIF. Uploading one turns Use the account logo off. Remove it and save to go back to the account logo.
• Theme. Match system (the default) follows each visitor's device. Light theme or Dark theme always shows that one, whatever the device asks for. Pin a theme if your brand only works one way. Otherwise, match the system: people who set their phone to dark usually want dark.
• Light Theme and Dark Theme above the colors choose which set of colors you're editing. Until you change a dark color, dark uses the light colors. Reset to light colors removes your dark colors again.
• Use the account colors. Shown when your account has brand colors. On, the light colors come from the Branding tab of Admin › Account › Account Settings and can't be edited here. The dark colors stay yours to set.
• Primary Color. The header, the visitor's message bubbles and the main buttons. It's also used for links, like the sign-in link.
• Text Color. The text on the primary color.
• Accent Color. Small highlights, like the typing indicator and badges.

Each color is checked for contrast. If text would be hard to read, it says so and offers a fix, like Use white text. Take the fix unless your brand rules say otherwise: people read the agent on phones, outdoors and at low brightness.

Launcher appearance#

The launcher is the round button that opens the chat on your website.

• Launcher logo. The image on the button. Use one at least 256 × 256 pixels, ideally with a transparent background. If it's too small for the size you pick, a warning tells you how big it needs to be. Without one, the button shows a chat icon.
• Launcher Size. From 40 to 100 pixels, labeled Small, Medium, Large or Extra large. The default is 60. Bigger is easier to find and tap, but covers more of your page.
• Shape. Circle (the default), Rounded square, Square, or Logo only. Logo only needs a launcher logo: the colored button disappears and your logo keeps its own outline. The button comes back while the chat is open.

Placement#

• Launcher Position. Bottom Right (the default), Bottom Left, Top Right or Top Left. Pick a corner your website doesn't already use for its own buttons.
• Launcher Offset. How far the button sits from the two edges, from 0 to 200 pixels. The default is 20. Raise it if the launcher covers a cookie banner or a "back to top" button.
• Launcher Border. An outline around the button, so it stays visible over a header or photo in a similar color. Width is 0 to 12 pixels; 0 means no border, and then Color is grayed out. Hidden for Logo only.

Select Save Appearance.

Embedded access#

Embedded access decides whether people must sign in before the website agent answers them.

Authentication Mode:

• Disabled - No sign-in required. Everyone chats as a guest. The simplest for families, but the agent never knows who's asking, so it only answers from knowledge for Public (all).
• Optional - Users can sign in or continue as guest. The default. Guests get public answers. People who sign in also get answers from knowledge meant for their group, like staff.
• Required - Users must sign in. Only people with a schoolOS account can chat. Choose it only if the agent is for staff or students, not the public.

Which should I choose?#

| Option | What it does | Choose it when | | --- | --- | --- | | Disabled | No sign-in screen. Everyone is a guest and gets answers from Public (all) knowledge only. | The agent is only for families and the public, and all its knowledge is public anyway. | | Optional | The chat opens on a choice: sign in, or continue as a guest. A guest choice is remembered in that browser, so they aren't asked again. | Families and staff use the same website, and some of your knowledge is for staff, students or guardians only. Most districts. | | Required | Nobody can chat without signing in to schoolOS. | The agent sits on a staff or student portal, and its answers aren't meant for the public. |

• A district with 12 schools puts the agent on its public website. Parents ask about calendars and enrollment, but teachers use the site too. With Optional, a parent continues as a guest and gets the public answer, and a teacher who signs in also gets answers from knowledge set to Staff.
• A district that only embeds the agent on its staff intranet, for password resets and Chromebook questions, picks Required. Nobody outside schoolOS can read those answers.

Authentication Message (Optional) is the line shown with the sign-in choice. It's hidden for Disabled, which has no sign-in screen. Leave it empty for the standard wording. Your saved message shows in the box when you open the page, and Save Access only changes it when you edit it. To go back to the standard wording, clear the box and save.

Select Save Access.

Behavior#

Disclosure and consent#

Disclosure & consent is what every conversation tells a person before it starts.

• AI & recording disclaimer. On by default. A notice shown before the first message that this is an AI assistant and the chat is recorded. You can edit the wording. Consent depends on it: with the disclaimer off, there's nothing to agree to.
• Require consent before chat. On by default. People must agree before they can type. They see Agree to the chat terms. and Don't record this chat.
• Consent decline message. Shown only after someone declines. They can still agree afterwards.
• "AI assistant" banner. Always on. A notice that stays at the top of the chat, on the website and in schoolOS: "AI assistant — not a person". There's no switch for it: every conversation says it's with an AI assistant.
• Directed to minors. On by default. Applies the stricter protections for children to every conversation, so nobody is asked their age, and reminds people it's an AI every hour instead of every three hours. The website widget and signed-in students always get these protections, because a visitor's age is unknown, so turning it off only affects signed-in staff and families.

When you turn any of these off, a warning lists what stops happening, like "conversations start without anyone agreeing to the terms". Requirements differ by state, so check the laws that apply to your students before you save.

Select Save Disclosure.

Trust and safety#

Two links, for reference: the schoolOS Privacy Policy, and Agent Guardrails, the safety, privacy and content rules every agent follows. You can't turn those rules off.

Prompt#

The instructions the agent follows, in four boxes: Prompt Intro, What You Do, What You Don't Do, and Tone and Behavior. They start from wording written for school districts, with your district's name filled in: answer only from your knowledge, don't help with homework, keep answers short, and point people in crisis to help. That starting wording is only used until you save. After that, the boxes always open with your saved prompt, just as you wrote it.

Change them to fit your district, like the topics families ask about most. Keep the limits in What You Don't Do unless you have a reason: they are what keeps the agent from guessing or wandering off-topic. Your prompt can't switch off the Agent Guardrails.

Otto keeps its own read-only limits whatever you write here.

Select Save Prompt.

Suggested prompts#

Starter questions people can tap before they type anything, on the website and in schoolOS. Use the questions families ask every week: "What time does school start?"

• Type one and press Enter, or paste several lines at once.
• Up to 8 prompts, each up to 200 characters, with no duplicates.
• A prompt can't ask the agent to do an admin task, like changing a record. Those are rejected when you save, with the reason.

Select Save prompts. Otto's starter questions are set on the Suggested tab of Admin › Otto › Prompts. See Set Otto's suggested prompts.

Availability#

Turn the signed-in AI experiences on or off for everyone in your account.

• Enable signed-in schoolAgent. The agent inside schoolOS, for people who are signed in. Off, nobody in your account can use it there. The website agent isn't affected: it's switched on and off on the Deploy Code tab.
• Enable Otto. Otto, for admins who can use it. Off, nobody in your account can.

Each still follows people's own permissions. Turning one on doesn't give anyone access they didn't have.

If the School Safety Team route has no email when you turn on Enable signed-in schoolAgent, you're asked first. See School Safety Team.

Select Save Availability.

Knowledge#

The Knowledge tab holds the documents, websites and verified answers the agent answers from.

• Sources. Everything the agent can read, with its type, its audience and when it last synced. Add knowledge source adds a website, pasted text, an uploaded document or files from a connected drive through the Add knowledge steps. Select a source's ... menu to edit it, change its audience or remove it.
• Removing a website. Removal is saved as a background job. The source shows Removing… until cleanup finishes; you can close the page. New crawl batches and scheduled re-syncs stop, and a running batch finishes before removal. Existing answers may still use the source until cleanup commits. If cleanup fails, the source shows Removal failed; choose Retry removal. Repeated removal requests reuse the same job. Removal cannot be undone.
• Health checks. The Health badge reads saved results. Open Health to queue missing or outdated checks in the background. Previous results stay visible while updates run; a new check is never shown as clear before it finishes. The page updates automatically. Refresh all requests a new check and stays disabled while checks are running. Failed checks keep the previous results and show a retry message. Closing the page does not cancel a saved check.
• Website pages. With background discovery enabled, adding a website first saves an unpublished draft. Discovery continues in the background even if you close the dialog. Open Manage pages and links to see progress, search discovered pages, inspect coverage by site, and review the selection. After a refresh finishes, Save selection updates the selected pages and links; confirm before removing indexed content. Review the separate Pages and External links lists, use Select all, Select first 50 or Clear, and set the name, audience and re-sync frequency. Newly discovered external links are selected by default for review; uncheck unwanted links before syncing. Their names can be edited. Reopening a previously saved selection keeps your choices. Select Start sync to process the saved website draft; discovery alone does not make pages available to the agent.
• Discovery controls. Pause discovery keeps progress. Resume discovery continues the same saved session and pending links while discovery is paused; it does not restart from the home page. Once discovery is complete, review the selected pages and start sync. Discovery pause, resume and cancel controls are not shown while syncing. Start sync opens the existing sync progress dialog. View sync progress and recovery opens the previous sync without restarting discovery. Use its failed-page rescan for recovery; use Discover new pages and re-sync only for a deliberate full refresh. Finish or cancel unfinished discovery before retrying a previous sync. If an allowance is reached, review the counts and choose Approve larger allowance & resume. You do not need to repeatedly select Continue discovery. Canceling an unpublished draft deletes that draft and its temporary results. Canceling discovery for an existing source keeps published knowledge and existing selections.
• Re-syncs and new pages. Manual full re-syncs and scheduled syncs discover new eligible website pages automatically. Pages you intentionally excluded stay excluded. New external links are selected by default in discovery review; clear any links you do not want before starting sync. Automatic refreshes continue using already approved external sources. Published external content stays available while it refreshes. If repeated refresh attempts fail, the last published content is retained and the link shows the refresh failure. If you choose to sync an incomplete discovery, acknowledge the warning first; existing pages will not be automatically deleted.
• Fresh discovery before sync. If a saved discovery needs a fresh check, choose Discover again from the beginning and confirm. This stops the old discovery and saves a new session for review. Saved selections and published knowledge stay in place; unsaved selection edits are discarded. Once sync has started, use sync recovery or a deliberate full re-sync instead.
• Removed pages. A missing link alone does not remove knowledge. Automatic removal requires complete discovery, a successfully published matching refresh, and confirmation that the original page returns Not Found or Gone. Confirmed deleted pages are also removed from the saved crawl selection, so future scheduled re-syncs do not recheck them from that list. If a page returns before deletion is confirmed, it is kept. Background discovery remembers confirmed missing URLs for that source and skips them until a recheck is due. The initial delay is one day, increasing to at most one week if the page stays missing. The next manual or scheduled discovery after that delay checks the URL even if the website no longer links to it. Restored pages are included again; timeouts and access blocks delay the check without counting as another confirmed deletion. Failed or incomplete discovery keeps existing knowledge. Operational failures and allowance pauses notify schoolOS Super Admins.
• External document removal checks. Website removal checks do not treat a missing Google Drive file, calendar feed, externally hosted PDF, or unpublished menu as proof of deletion. Those sources continue through their usual ingestion flow; existing published content and saved selections are retained when deletion cannot be confirmed. One failed removal check does not stop checks of other pages. Temporary website verification failures retry per link with a delay and a maximum number of attempts. If they remain unresolved, the refresh keeps that content, lists the retained links under Skipped links, and notifies schoolOS Super Admins for review. A website URL that redirects outside the website is also retained rather than deleted from the redirect's response.
• Verified Answers. Approved answers to common questions. A published answer can be given as-is when someone asks something close to it.
• Calendar PDFs. Supported single-page school-calendar tables keep dates paired with events, including breaks that continue from December into January.
• School-year dates. First- and last-day questions use calendar evidence. Phrases such as “for students” describe the audience; to request a specific audience page, name the page explicitly.
• Health. Gaps (questions the agent couldn't answer, got a thumbs-down, or answered with low confidence) and Stale & broken knowledge (answers whose source page changed or disappeared, and sources whose last sync failed). The tab shows how many are open.

A website and a source from a connected drive, help center or wiki each have How often: bring it in Once, or Keep in sync hourly, daily, weekly or monthly. See Once, or keep in sync?. You can also add sources from the Knowledge tab of Admin › Account › Import Data.

Add knowledge#

Add knowledge source walks through three steps, or four for a website. You can go back to an earlier one by selecting it at the top.

1. Source. Choose Website, Paste, Upload, Google Drive or OneDrive, then give it the link, the text, the file or the folders. For a website, select Next and schoolAgent reads the site and finds its pages before moving on.
2. Pages (websites only). The site's pages, grouped by their top-level section (Home page, /about, /families…), every one ticked. Untick a section to leave it out, or open it to pick its pages. Linked documents below lists the files and pages elsewhere that the site links to, such as a handbook PDF; they're ticked too.
3. Audience. Choose Who can see answers from this. A website starts on Public (all), everything else on Everyone signed in. A website or a drive also has How often; a new website keeps in sync monthly.
4. Review. Check the name, how often it syncs, how much is coming in (a website's page count, the words you pasted, the file, or the folders to import) and who can see it. Add optional guidance on when schoolAgent should use it, then select Add knowledge.

A website's ... menu has:

• Edit connection. The same Pages, Audience and Review steps, opened on what's synced now; select any step at the top. Pages reads the site again, so pages added since the last sync show up unticked, marked New when you tick them and Remove when you untick one that's synced. Review lists what changes, and Save keeps it.
• View sync log. Every page read, with what happened to each.
• Resync. Reads the whole site again now; pages that haven't changed are skipped. Right after a full read, it retries just the pages that failed instead.
• Remove. Takes the website and everything read from it out of knowledge.

Help desks and Confluence aren't added here: choosing them points to their own page, where you pick which sections sync.

When a website can't be read

If schoolAgent can't read the site, a message opens over the dialog with the reason, and you stay on Source to fix the link or Try again. Use another source switches to Upload.

| Message | What happened | What to do | | --- | --- | --- | | Cloudflare blocked the site | The site uses Cloudflare's bot protection, which stopped schoolAgent before it read any pages. | Ask whoever manages the website to allow schoolAgent's reader in Cloudflare. The message shows its name, schoolOS-KnowledgeBot/1.0 (+https://theschoolos.com), with a Copy button. Until then, add the same information as an upload, pasted text or a drive folder. | | The site turned schoolAgent away | Another firewall, or a sign-in page, answered instead of the site. | The same: ask the web team to allow the reader, or add the information another way. | | The site didn't answer in time | It took longer than a minute. | Check the site opens in a browser without signing in, then try again. schoolOS support is told. | | We couldn't find the site | The address doesn't exist. | Check the spelling, or copy the link from your browser's address bar. | | No pages found | The site answered but had nothing schoolAgent could read. | Try the link of a page with the content itself, or upload it. schoolOS support is told. |

Each source is only used for people in its audience. Public (all) includes guests on your website; the other audiences need people to sign in. Adding or changing knowledge needs Manage knowledge.

Staff diagnostics#

schoolOS platform staff can run Test Knowledge for the selected account, including while impersonating an account administrator. The test runs in the background. Closing the report does not stop it; reopen it to see progress or use Stop to request cancellation. The worker sends the summary to the staff member who started the test.

A staff forced full re-sync also clears stored HTTP validators so source pages are read again. Normal re-syncs can still reuse unchanged content. Widget installation diagnostics distinguish a recent verified sighting from one older than seven days and warn when the widget was seen on a different website.