Agentic AI manual

Chapter 1What agentic AI is in PIES Studio

PIES Studio has two very different jobs for AI, and the product keeps them apart on purpose.

• Operating a running app. An agent is a standing post on one environment of one app. It watches data, files findings, notifies people, and, within limits you set, acts. It never changes the app's design.
• Building or changing an app. A delivery runs a playbook. The playbook's steps run in order against a board of cards on a branch. When the delivery ends, nothing is left running.

An in-between form exists for one-off actions on a running app: an errand. It is a single run, nothing standing, nothing built.

Everything, whichever kind, is started from one door, Start work, and lands in one feed, Activity.

Chapter 2The three kinds of work

Runs underlie all three. A run is one bounded conversation between the model and the app's tools, with a budget of iterations, minutes and tokens.

Chapter 3Where things live

The rule is short: the editor is design, the deployment is operate.

Applications → your app → Editor → Build → Agents · design
Applications → your app → Deployment → Agents · operate
Agents · Playbooks · Activity · across all apps

Chapter 4Agents and posts

Creating an agent

New agent is on the Agents page in the sidebar, and on the + beside Agents in the app editor's Build explorer. From the sidebar it walks three steps. From inside an app, Who is already answered ("For your app", with "not for this app?" if it is wrong), so it walks two: Brief and Freedom.

1. Who. "Me — my assistant" acts with your permissions on any app you can open. "One app" lives inside one app and works with its data and users. A third card, "Build or change an app", is not an agent at all: it opens Start work for a delivery.
2. Brief. The job description. This is the only place an app agent's instructions live. Pick a starting card, give it a name (at least 3 characters, unique in the workspace) and write the brief. See Chapter 6.
3. Freedom. Autonomy (Supervised, Autonomous or Locked down), the app access group it runs as (Runs as), its reach in the app (read only, or read and write), and when it runs (when asked, every day, weekdays or every Monday at a time you choose). Runs as must be picked before Create. Finer triggers such as events and webhooks are set in Configure.

The result is a draft. Nothing runs yet.

Posting it

Posting puts the draft onto one environment. The post freezes a snapshot of the brief, tools and guardrails, takes an agent seat, and arms the triggers you chose. The same agent can be posted on several environments at once, each post independent. Templates can also mark an agent to post itself again whenever the app is deployed.

Configure, field by field

Configure has four steps: Brief, Access, Triggers and Guardrails, then Post on the deployment page. Every field below is the whole of what an agent can be set to. Changes to any of them wait for Post again, except where the table says live.

Live without Post again: Pause, Resume, tool auto-allow and Memory. Everything else is frozen into the post at Post again.

There is no Role picker. The role on the roster is worked out from what the agent can do: its reach and its triggers.

In the app editor the same four steps open as design: there is no Post, Pause or Fire, and a line under the header says where the agent is posted and sends you to Deployment → Agents to post it. A name already used in the workspace is refused with "An agent with this name already exists", both in New agent and when you rename it in Brief.

Lifecycle

What changes live and what waits for Post again

When a design has been edited after it was posted, the header reads "edited since posting" and each post shows "Edited since it was posted". Open the agent and choose Post again to put the edits live.

Chapter 5The agent flow, from trigger to report

This is what happens, in order, every time a posted agent runs. Nothing here needs you unless the agent asks.

1. Trigger. A schedule, an event in the app, a webhook, or you pressing Run now. The post's triggers are armed when it is posted and disarmed when it is paused.
2. Wake. The agent starts a run with its frozen brief, whatever memory it kept from earlier runs, and the generated contract of the app's tables and functions.
3. Look. It reads data and calls read-only functions freely. Each read is one iteration against the run's budget.
4. Act. When it wants to write, the approval mode decides: under Supervised the call parks until an operator approves it in Activity, under Autonomous it goes through, under Locked down every call parks. A parked call that nobody answers expires and the run continues without it.
5. Report. The run ends with a report: what it found, what it did, what needs a human. The report and every step are on the agent page under Runs and in Activity. Notifications go wherever the brief says.
6. Remember. Anything the agent chose to remember is patched into the live post at once, so the next run starts from it.

Reading the agent page

Chapter 6Writing a brief

Write the brief as a job description for someone who can only see the app's data and functions. Say what it watches, when it runs, what it does for each finding, what it never does, and when it asks.

You watch the Zetaris banking data for accounts drifting into risk.

Every morning at 07:00, and whenever a new transaction batch lands:
- Find accounts whose 30-day outflow exceeds 80% of their average balance.
- Find any account with three or more failed payments in the last 7 days.
- For each, add a row to Risk Watchlist with the reason and the figures you used.
- If an account is already on the watchlist, update its row rather than adding another.
- Notify the Credit Risk team with a one-line summary per account.

Never change balances, limits or customer records. If the data itself looks
wrong, stop and ask rather than guess. Show your arithmetic for any figure
you report.

Then in Freedom: read and write in the app, every day at 07:00, writes need approval. Add the batch-landed event trigger in Configure. The brief itself is what keeps it to the watchlist; the guardrails park any write for approval.

Reading a brief

Configure → Brief opens the brief as a document, not a text box. A line at the top gives the first sentence as the job, then the size: sections, checks, words, and roughly what the brief costs on every model call. With more than one section there is an Outline down the side; click a heading to jump to it, or click a section's heading to fold it. Words written in snake_case, such as stock_items, show as table-name tags.

A section headed "When you run" shows the live schedule beside it, or "No schedule armed". A section about what it reads shows its live access. Where the brief and the settings disagree, a warning names the problem and has a button to the setting: "The brief says it changes nothing, but Access lets it write to the app" opens Access, and "The brief describes a schedule, but no schedule trigger is armed" opens Triggers. The section involved is marked in the outline.

Editing a brief

Press Edit, or double-click the text. An empty brief offers Start from a template, which fills in the usual sections for you to replace. The editor works By section: a Role line, then a card per section with its heading, its text, numbered checks, and optional text after the checks. Each section and check can be moved up, moved down or removed. In a check, Enter adds the next one and Backspace on an empty check removes it. Add section offers the usual headings the brief does not have yet (What you read, When you run, What each run covers, What you report, What you must never do), or Custom. Boxes grow to show all their text.

Raw text shows the brief as the plain text the agent reads. A brief not written as "Heading: text" sections, a bullet list for example, stays in Raw text so switching cannot reflow it. Preview returns to the read view; Save stores exactly the text shown.

What not to put in a brief

• Anything about building screens, tables or functions. That is a playbook step, run by a delivery.
• Credentials or environment names. Access comes from grants, the environment from the post.
• Long tool lists. The agent already receives a generated contract of the app's tables and functions.

Chapter 7Playbooks

A playbook is the recipe a delivery follows: rules that every step runs under, and ordered steps, each with a role, the tools it may use, a model tier, and whether it runs once per delivery or once per card. A playbook holds nothing that is posted, versioned or seated. It is not a team.

When a delivery starts, PIES runs the playbook's steps in order. Each step is a separate worker in its own context, and steps hand over through the board's cards. When the delivery ends, none of them remain.

Stock playbooks

Every workspace comes with three, marked Stock. Edit or delete them like any other.

The Playbooks page

The page reads like Applications and Agents: a workspace bar across the top (the choice is shared with those pages), a search that matches names, descriptions and step names, a Stock / Made here filter, and a sort by name, most used or most steps. Each row shows its steps, how many run per card and how many deliveries have run on it; Start delivery appears when you hover the row. Fifty rows show at a time, with a button for the rest. New playbook sits in the header.

Editing a playbook

Open it from Playbooks. Name and description edit in place. Rules are one block of text injected into every step. Each step card has a title, a role, a model tier (Small, Mid, Strong), a per-card toggle, its brief, and the tools it may use (empty means the playbook's default tools). Add a step with the button under the list; reorder and remove from the card menu. Delete the playbook from the editor header menu. Three principles the stock playbooks follow and yours should too:

• Whoever builds never closes a card. Verify closes it, with probe evidence.
• Verify never fixes. It reports the exact symptom and leaves the card open.
• The one Strong step is the one that has to be right first time: screens and wiring, or the single builder.

Running one

A playbook runs by starting a delivery with it. Every playbook row and the editor header have Start delivery, which opens Start work with the playbook already chosen.

Chapter 8Deliveries

Starting

Open Start work from the Activity header, an app's Deliveries tab, the chat's Build something menu, New agent's "Build or change an app" card, or a playbook's Start delivery. Choose the app first, say what needs doing, pick Delivery, then the branch and playbook. Start delivery creates the delivery and starts its first step at once.

The cockpit

The delivery opens in its cockpit.

• Header: app, branch, playbook, who started it, and a status pill (Running, Paused, Awaiting decision, Stopped, Done, Failed). A delivery you stop is saved as Stopped, not Failed, and shows as Stopped in delivery history and Activity.
• Brief and Board: intake sizes the brief into cards; each card shows its state and the step working it.
• Route: the playbook's steps in order, with the runs of the steps that dispatch work under each, so you can see where the delivery is. Intake and architecture work shows in the Narrative.
• Live: the running step's trace, and a box to say something to it. What you type is handed to the running step at its next turn.
• Actions: Pause, Resume, Stop, Retry or Skip when a decision is waiting, Roll back to the baseline taken at start, Delete when nothing is running.

Chapter 9Errands

An errand is one action on a running app: "re-send the failed invoices from Friday", "check every open ticket against its SLA and tell me". Start work proposes Errand when the wording asks for one action. Pick the environment, what it may touch, and the model. The run opens on its own page with steps and outcome. An errand always runs Supervised: approvals for anything that writes go to you and to that environment's operations approvers, and whoever answers first decides.

Chapter 10Activity and approvals

Activity is the single feed. Its tabs are Needs you, Running, Today, Failed and Everything, filterable by app, environment and kind. Anything waiting on a human sits under Needs you: an approval, a decision in a delivery, a question an agent asked.

Finding things in Activity

The search box above the feed searches what runs actually did — the ask, the outcome, the error, and the names of the functions an agent called. Type a function name to find every run that touched it, or a word from an error to find every run that failed on it. The search is indexed, so it is as fast on a year of history as on a day, and it narrows the feed as you type. A search is part of the page's address, so the link can be shared and it survives a reload.

Two shortcuts arrive already narrowed. On an agent — its page's ⋮ menu or its row on the roster — See its activity opens the feed showing only that agent: its runs, and the approvals and questions it raised. On a playbook, the same entry under ⋮ shows every delivery started from it and the runs of its crews. Either way a chip names what you are looking at, and its × widens the view again. These are real filters, applied where the feed is read, so paging back through months of history stays complete.

Search covers what a run did, not every word it wrote. Runs whose detail has aged out of retention keep their place in the feed but cannot be found by content.

Approval modes

Set it on the agent under Guardrails → Autonomy. Beside it, Who is asked decides where a parked call goes: Whoever posted it, The app's operators, or These people (a list of emails).

Deciding an approval

An approval card in Needs you names the agent or errand, the app and environment, and says in words what it wants to do. Open the card before deciding. It shows who started the run and when, the function or query with its parameters as a table, the agent's own reason for the call, the steps it has taken so far, and a link to the run. Allow runs the call. Deny stops it and tells the agent why, if you leave a note. "Allow this for the rest of the run" stops the same action asking again in that run. "Always allow" approves it and adds a standing rule to the agent, so it never asks for that action again. Every decision is written into the run's steps, with the note signed by whoever decided.

When nobody answers

A parked call waits for the agent's wait window: unless the agent sets its own, 5 minutes for Run now and 15 minutes for scheduled runs, events and errands. If nobody answers in time the change is skipped, the agent is told, and the run carries on to its report, which ends "1 change was not approved, so it was not made." If the run's own time budget runs out first, the run ends as cancelled with the reason "Waited N min for an answer and gave up". It still keeps what it found, and says how many changes were not approved.

Approvals route by role: an app agent's requests go to the app's operators for that environment, not to whoever built it. Tool auto-allow lets you approve a tool once and keep the post moving.

Chapter 11Templates with test data

Every system template in the gallery installs with an agent pack and sample data shaped so the agents find something on their first run. The template's gallery text has a section What the agents will find naming the rows each agent will act on.

Try one in ten minutes

1. Applications → New Application → From Template → pick one, for example Restaurant Manager, and press Use this template.
2. Open the app. In the editor go to Configure → Secrets & environments → Environments → Add environment, set the deploy target to Kubernetes, pick your cluster connection and namespace, and Save. Then open Deploy in the left rail, choose File → New Request, pick Kubernetes and that environment, and follow the wizard to Active. Sample rows land with the build, and the deployer issues one app credential per access group, which is what each agent's Runs as needs. Dates in the sample data are relative, so "due next week" is true whenever you install. Sample rows are loaded only the first time the database is created. Publishing again, with or without database changes, keeps every row you or your agents have added.
3. The template's agents are posted for you when the app is deployed. Deployment → Agents lists them live. Post an agent is for one that is not posted yet.
4. Open an agent and press Run now, or wait for its schedule.
5. Read its report in Activity. For Restaurant Manager expect Lobster Bisque priced below cost, Chicken Parmigiana on orders while unavailable, and Seafood Platter with no sales.

Retail Banking Analytics reads accounts and transactions from a Zetaris connection you provide; its internal casework tables carry the planted scenarios.

Chapter 12Inside a run

A run is a loop: the model reads the brief and the app contract, picks a tool, sees the result, and continues until it reports or the budget ends. Three mechanisms keep long runs healthy.

Budgets

Iterations, minutes and tokens per run, set in Freedom. A run that reaches its minutes or tokens ends there and keeps what it found. A run that reaches its iterations compacts first (below); if it is still at the limit, it stops as Paused — "Stopped at its step limit" — and waits in Needs you, where Resume continues it and Run again starts fresh.

Compaction

At three quarters of the iteration budget the run folds its history into a structured handover and continues, up to three times. You see a compaction step in the trace.

Steering

Anything you say to a running step in the cockpit is handed to it at its next turn as a message from you. It is advice, not an order; the guardrails still apply.

Memory the agent writes is patched into its live post immediately. Everything else it learns stays in the run's trace.

Chapter 13Governance and limits

• An agent acts for someone, a person or an application, and can never exceed what that principal can do right now. Revoking a permission stops the agent in the same instant.
• Inside the app, an agent runs as the access group its designer chose. The app enforces that group's function permissions on every call, direct data reads are limited to the tables the group may read, and rows the agent writes carry a system user named after its key. Templates ship each agent with its group set.
• Every action is audited with the agent, the run, and the posted version, so what was running is never in doubt.
• Posts cannot live on previews. Builders are never posted; build work is a delivery.
• Approval routing is per environment. Production can require approvers that staging does not.
• Nothing deploys or restarts production from inside a run without explicit approval.

From a line in Activity to the audit trail

Every governed AI call is written to a tamper-evident log: hash-chained, signed, and carrying the agent, the run and the posted version inside the signed record, so attribution cannot be altered after the fact. Activity tells you what happened; the audit tells you what was permitted.

Two records answer two different questions, and it is worth knowing which you want. Decisions — in the workspace sidebar — is what an agent asked to do and how it was answered: approved, denied, nobody answered in time, or paused by the platform. PIES AI → Audit is what the model actually ran: every governed call, the policy that routed it, the provider and model that served it, hash-chained and signed. A refused write appears in both — as a denial in one, and as a call that never happened in the other.

The trail is shown where the work is, so tracing never means leaving the page. Open a run in an agent's Activity and press See the audit: underneath it you get both halves — the decisions that run asked for and who answered them, then the governed calls it made, with the policy, the model and what it cost. An agent's own Audit tab does the same for everything it has ever been permitted or denied, and a playbook's ⋮ menu for its crews, which have no agent record of their own and are traced by the playbook they were instantiated from.

Open the full log leads to PIES AI → Audit for the things only it can do: the whole tenant at once, the facet breakdowns, and CSV export for a SIEM. Its filter bar asks the few questions people actually ask — a time window, who acted, the source of the call (an agent run, a build, Studio chat, an app assistant) and the decision — with the rarer ones behind More. Acted by is a search box over the agents and playbooks that appear in that window, busiest first, and it names an actor that has since been deleted as exactly that rather than showing a bare identifier. Whatever is narrowing the log shows as a chip you can remove one at a time. Every row says who acted, with Open the run to go back to the work itself, so an incident review can start from either end.

A trace that finds nothing is usually telling the truth: a run that ended before it reached the model — stopped, or failed on its first tool — made no AI call to govern. The audit log lives under PIES AI → Audit and needs the audit-read permission, so it is available to administrators and compliance roles rather than to everyone who can see Activity.

Chapter 14What an agent remembers

An agent starts every run from the same place: its brief, the app contract, and one short note it keeps for itself. It does not remember its previous runs. That is deliberate — a run you can reproduce is worth more than one that quietly depends on something it saw last Tuesday.

The brief

What you wrote. Read on every run, never changed by the agent.

Memory

A curated note the agent keeps, rewritten whole each time — conventions, durable facts, your preferences. About 4,000 characters, injected into every future run. You can read and edit it yourself.

The run's own trace

Everything else it learned. It stays with that run and is not carried forward.

Two details matter in practice. Memory applies immediately — it is patched into the live post, so the agent uses what it just learned rather than waiting for the next post. And saving memory does not mark the post "edited since posting", because a notebook is not a change to the design. An agent may save it once per run; after that it is told to stop keeping notes and do the work.

Don't put secrets in memory. It is injected into every run and visible to anyone who can open the agent. Credentials belong in the app's environment, never in a brief or a note.

Chapter 15When an agent misbehaves

An agent that fails loudly is easy. The dangerous one fails quietly at 03:00 every night, and nobody notices for a fortnight. PIES Studio watches for three different kinds of wrong.

Failing

Three runs failing in a row marks the agent unhealthy: it turns red on the roster and whoever approves for it gets one notice with the reason. A single success clears it. One failure is weather; three in a row is a broken agent.

Failing often

The fleet view ranks every agent over the last 24 hours by failure rate, not by volume — so a bad agent with five runs outranks a healthy one with five hundred.

Saying nothing

A run can finish successfully and produce nothing. That is counted as an empty answer and ranked alongside failures, because it is the failure mode neither the run list nor the approval log catches.

Runs you stopped, and runs that hit their budget, are not counted against an agent's health. Stopping an agent is not the agent misbehaving.

It stops itself

Marking an agent red does not stop it. An agent that can change your app without asking, and is failing every time, should not keep trying until someone notices — so it pauses itself and asks to be resumed.

After three failures in a row, PIES Studio pauses the agent where it is failing — that environment, not the others — and sends whoever approves for it a notice titled Paused automatically, carrying the reason and a Resume button. The reason is exact: Paused automatically after 3 runs failed in a row. Last error: …, and the error quoted is the fault that stopped the run — not the agent's own account of what it was doing. You see it wherever you would look: the roster counts the agent under Paused and names the reason on its status dot, the notice carries the sentence in full, the deployment's Agents tab shows the post as Paused automatically with the reason and a Resume button, and Activity lists it as a notice offering Resume or Dismiss — never Deny or Allow, which mean nothing for an agent that has stopped itself. The agent page shows the failure behind it.

This applies to agents that can write to an app without asking. A read-only agent that fails keeps running and is simply marked unhealthy — there is nothing for it to break. A supervised agent is already held by its approvals: every change waits for a person, so the person is the brake.

You decide, under Configure → Guardrails → If it keeps failing:

Automatic default

Stop it if it can write to an app without asking; otherwise keep it running. The label tells you which applies to this agent.

Always stop it

Stop after three consecutive failures whatever its access.

Never stop it

Keep running however often it fails. On an agent that can write unattended, the product warns you plainly.

Resume clears the pause, the reason and the count, so the next failure starts a fresh count of three.

Chapter 16Auditing an agent

Two questions get asked after the fact, and they have two different answers.

Who allowed that?

The decisions log, under Governance, records everything agents asked and how it ended — answered, denied, dismissed or interrupted — including the changes a standing rule allowed without asking anyone. It outlives the inbox: an approval you answered months ago is still here.

Each row carries when, which agent, the action, what it touched, the outcome and who decided. Filter by agent, by person, by outcome or by period, and export the result as CSV. Every row also keeps the version that was running and the policy in force at the time — both drift, and an answer months later is worthless without them.

What did the model actually do?

Every call to a model is recorded in the governance audit, under Admin → Governance → Audit: who asked, which policy applied, the decision, the provider and model, the tokens and latency, and the prompt's fingerprint.

The log is built to be admissible. Each record is hashed, chained to the record before it and signed, so any alteration or deletion breaks the chain. Open a row to see its tamper evidence: the sequence number, the record's hash, the previous hash and the signing key. Auditors can replay the whole chain independently, and the verification either reports the chain intact or names the exact record where it broke.

Agent work carries its attribution inside the signed record — which agent, which run, which posted version, and for delivery work the playbook, the step and the person who started it — so attribution is as tamper-evident as the rest.

Chapter 17Pause, fire, delete

Three ways to stop an agent, and the difference matters when you are in a hurry.

Pause

Silences its triggers and keeps everything else. Schedules skip it, webhooks refuse. It is per environment — pausing Production leaves Staging running. Resume puts it back. Pausing is not an edit, so it never makes a post read "edited since posting".

Fire

Ends the posting. Runs in flight stop, recorded as stopped because the agent was fired. The design, its history and its memory all remain, and you can post it again later. Firing one environment does not touch the others.

Delete

Permanent. The agent is fired first so no armed trigger outlives it, then the agent, every post it ever had, and its runs, traces and parked approvals are removed.

Reach for pause when something is wrong and you want it to stop now; fire when it should not be working on this environment any more; delete only when you want it gone.

Delete removes the record. If you may ever need to answer "what did this agent do?", fire it instead. The decisions log and the governance audit keep their entries either way, but the agent's own run history goes with it.

Chapter 18Troubleshooting

I cannot pick a playbook when creating an agent

Correct. Playbooks are run by deliveries. Use the "Build or change an app" card, or Start delivery on the playbook.

Activity showed something running but nothing was happening

A delivery whose coordinator was lost in a restart. After a restart it is marked interrupted straight away; if the service that ran it never came back, within about four minutes. Either way it offers Run again.

My delivery says Not started

Open it and press Start. Deliveries created before 1.9's cockpit did not start automatically.

The post says "Edited since it was posted"

The design changed after it was posted. Open the agent and choose Post again to put the edits live.

Post an agent is disabled on an environment

Its environment was deleted or the deployment is not running. Previews have no Agents tab at all. Deploy to a real environment first.

The agent's first run stopped at its first read

Check its Autonomy. Under Locked down, reads park too. Supervised lets reads through.

A number in the report is wrong

Models can slip on arithmetic. Add "show your arithmetic" to the brief and give it the exact columns to compute from.

I changed the data model and published. Is my data safe?

Yes. Publishing never deletes data and never reloads the sample rows over it. New tables are created, with their sample rows. New columns are added. A column type is changed only when no value can be lost. A table or column you removed from the data model stays in the database, and the Deployment page lists it under Your data was kept. A type change that could lose data is refused, and that list names the table and column. To really remove old data, do it deliberately in the database.

Sample data looks stale

Sample dates are relative and resolve when the app is built, including dates stored as text. Data installed earlier keeps the dates of that day. Deploying again does not reload sample data into an existing database; install the template into a new environment to get fresh dates.

Chapter 19Glossary

Agent

An operator design: brief, access, triggers, guardrails. Becomes a post when you post it on an environment.

Post

An agent running on one environment, frozen at a version, on an agent seat. Post again puts a newer version live; Fire ends it.

Playbook

Rules plus ordered steps for build work. Stock ones: Full delivery route, One builder and a verifier, Fixer.

Delivery

Build or change work on one app and one branch, with a board of cards and a baseline to roll back to.

Errand

One action on a running app, one run, nothing standing.

Card

One requirement on a delivery's board, with acceptance criteria the Verify step can probe.

Run

One bounded conversation between the model and the app's tools.

Activity

The one feed of everything running and everything waiting on you.

Environment

A deployment of an app: where posts live and errands act.