When agents write back

The people closest to your customers learn things first: a new objection on a sales call, a support workaround, a change to how a feature behaves. Usually that knowledge stays in one chat window. Herald lets an agent put it back into the workspace while the person is still working, so everyone else's agent has it next time.

Who can edit

Sign-in connections can edit whatever the person signed in can edit, and publish whatever they can publish. Someone who can edit the whole workspace can suggest changes anywhere; someone who can edit one folder can only change that folder; someone who can only read can still keep their own private notes.

API keys can edit only if they were created with Can edit or Can edit and publish, and publish only with the latter. A read-only key gets no editing tools at all. A personal key is still limited to what its creator can edit and publish.

People and access explains the three levels. The short version: edit means drafts, publish means making them live.

What agents can do

Change	Takes effect
Create a page	As a draft
Create a table	As a draft
Add, change or remove rows in a table	As a draft
Edit part of a page (find and replace)	As a draft
Rewrite a whole page	As a draft
Change a page's title, folder, type, kind, tags, usage note, pin or expiry	Straight away
Move a page or folder	Straight away
Delete a page, table or folder	Straight away, to Recently deleted; anything published needs publish access
Publish a page	Straight away, and only with publish access
Give people access to a page or folder, or remove it	Straight away, and only with permission

Making a page a rule or always including it needs a connection that can edit the whole workspace, the same as in the app (or it's the person's own private note). Agents can't import, change the tag vocabulary or packs, or change who's in your organization.

Edits are drafts

This is the part that makes write-back safe. When an agent creates a page or edits a page's text, the change is saved to the draft. Every other agent keeps getting the published version until someone publishes the change: in the app, or with the separate publish_page tool where the connection has publish access.

So when a sales rep's agent adds "Customers on Bookwell often ask about data migration" to the Bookwell section, it doesn't instantly appear in every other rep's emails. It shows up in the Unpublished queue, where whoever owns that page can read the change, publish it, edit it first, or throw it away.

Page properties and moves are different: they apply straight away, because there's no draft version of a page's folder or tags. They can still be undone.

So do deletes. A deleted page stops reaching agents at once, so a connection can delete something published only where it could also publish it; with edit access alone it can delete drafts that were never published and empty folders. Agents are told to delete only when the person asks. What they delete goes to Recently deleted for 90 days, marked with the connection that deleted it, and is restored from there.

Publishing from an agent

Publishing is its own tool, publish_page, never a side effect of editing. An agent that edits a page is told the change is a draft; it publishes only when the person asks it to ("publish that", "make it live"), and only where the connection behind it has publish access: a sign-in connection wherever the person could press Publish in the app, an API key created with Can edit and publish. Everywhere else the tool is refused with a message saying the draft is published from the app.

Publishing a page this way is the same as publishing it in the app: it re-indexes the page, and shows up under Activity → Agent edits as "Published" with the connection that did it. A publish isn't undone from there; open the page to edit it or unpublish it. The REST API has the same thing as POST /pages/{page}/publish.

Reviewing and undoing

Every change an agent makes is listed under Activity → Agent edits, with the page, a summary ("2 edits", "created 'Data migration FAQ'", "moved 'Pricing FAQ' to Market / Battlecards"), and which connection made it: a named API key, or a sign-in connection and the person's email.

Undo next to an edit restores the page to how it was before that change. You can undo changes to pages you can edit. A publish has nothing to restore, so it has no undo; unpublish or edit the page instead.

To publish an agent's draft, open the page from Activity or from the Unpublished queue. Pages with unpublished changes open on a diff of exactly what will change.

Getting good edits

Agents only edit when asked to; their instructions say to change the context only when the user asks for that. So the workflow is simply to ask:

• "Add the objection this prospect raised, and how I handled it, to the Bookwell competitor page."
• "The refund window changed to 30 days. Update the refund policy."
• "Make me a private note with what I learned on this call."
• "Move the old launch pages into an Archive folder."

Behind the scenes, a well-behaved agent will call list_all_pages to find the page, read_draft to see its current text (which can differ from the published version), and then edit_page with a targeted change. It'll tell you the edit is waiting to be published. If you can publish, "and publish it" makes it call publish_page too.

When you hand an agent a list of records (accounts, plans, a CSV), it's told to make a table with create_table rather than a page, and to add to an existing table with add_rows when one already covers that kind of record. read_draft on a table shows its rows with their ids, which update_rows and delete_rows take. If you'd rather it never made tables, or always did for certain data, say so in your agent instructions.

A few habits help:

• Prefer small edits. edit_page changes just the part that's different. Asking an agent to rewrite a whole page invites it to "improve" things you didn't want touched.
• Ask for a new heading for a new topic. That keeps each section findable on its own.
• Review in the diff. The Changes view shows exactly what an agent changed, which is quicker than rereading the page.
• Name an owner. Pages with someone responsible for them get their drafts reviewed. Give people edit access to the folders they know best, and they'll see suggested changes to them in their Unpublished queue.

Access changes

update_owners lets an agent give someone in your organization access to a page or folder by email, or take it away. Because it changes who can see things, it needs extra permission: sign-in connections have it wherever the person could make the same change in the app, and API keys need Can change who has access to pages and folders ticked when they're created. These changes apply straight away. The people must already be members of your organization.

Agents are told to change access only when you ask them to.