PIES Studio 1.9 · Documentation
This page is the short version. The Agentic AI manual walks through every screen — New agent, Configure field by field, the agent page, playbooks, the delivery cockpit, errands, approvals, templates and troubleshooting — with pictures. Each section below links to the chapter that goes deeper.
PIES AI builds what you ask for, one conversation at a time. Agent work takes the same building power and runs it for you — on a schedule, from a webhook, on an event, or as a delivery building or changing an application, step by step, while you watch. There are three kinds of work, one door into all of them, and one feed where every one of them reports. This page covers what each kind is, who does it, how it starts, where you watch it and what survives when it ends.
Under Agents in the Studio sidebar there are three entries, and that is the whole feature:
The rule for where things live is short: the editor is design, the deployment is operate. An app's agent designs live in the editor under Build → Agents; who is posted on an environment, live or paused, is on the deployment page's Agents tab. More: Where things live.
Two questions decide what a piece of work is: does it end, and does it change the application's design or act on a running one. Answer both and you get three kinds.
| Delivery | Errand | Post | |
|---|---|---|---|
| What it is | Changes an app by running a playbook | One action on a running app | A standing agent posted on one environment |
| Who does it | The playbook's steps, one worker each | One worker | The posted agent itself |
| Lifetime | Ends when its steps have run | One run, ends with an outcome | Until you fire it |
| Has a board | Yes — cards on the application's board | No | No |
| Versioned | Works on a branch, with a baseline to roll back to | No | Yes, a numbered post per environment |
| Costs a seat | No | No | Yes, one agent seat per post |
| Lives in | App › Build › Deliveries | Activity, and the environment it ran on | Agents, and the deployment's Agents tab |
Underneath all three is the same thing: a run — one bounded conversation between the model and the app's tools, with a budget of iterations, minutes and tokens. That is why one feed can honestly show all work. More: Three kinds of work.
Builders are not agents. Every agent is an operator design; build work is a delivery.
Start work is one dialog, and every road leads to it:
Choose the app first, say what needs doing, and pick the kind — Start work proposes one from your wording. Then only what that kind needs:
A post is an agent on one environment, frozen at a version, on an agent seat. An agent is an operator design — brief, access, triggers and guardrails — and it never changes the app's design. There is no model picker: the model is set by your governance policy for the app. Every step of every run is recorded.
New agent is on the Agents page and on the + beside Agents in the app editor's Build explorer. From the sidebar it walks three steps — Who, Brief, Freedom. From inside an app, Who is already answered ("For your app", with not for this app? if it is wrong), so it walks two.
The result is a draft; nothing runs yet. There is no Role picker: the role shown on the roster is worked out from what the agent can do — its reach and its triggers. More: Agents and posts and Writing a brief.
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. The same agent can be posted on several environments at once, each post independent, with its own version and pause state.
The agent page's Where it is posted lists each environment, its version and who posted it, with Pause, Resume, Post again, Fire, and posting on another environment. Auto-post when the app deploys is Off, all environments or selected ones (templates: on).
Firing is per post. Firing an agent off production stops that environment's runs and nothing else. Deleting the application ends all of its posts and stops their runs. A post cannot be placed on a preview: deploy the app to an environment first, then post.
In the app editor the agent opens as design: there is no Post, Pause or Fire there, and a line under the header says where the agent is posted and sends you to Deployment → Agents. More: Posting it.
An app agent acts as one of your app's access groups — the same groups you define under Users & Access — and the app enforces that group's permissions on everything it does. Direct data reads are limited to the tables the group may read, and a query naming another table is refused by name — "Your access group (Sales) cannot read the table payroll." Rows the agent writes carry a system user named after its key, so your application's own audit shows PIES Agent · <group>. Templates ship each agent with its group set.
The deployment issues one app credential per access group, so a group you add to the design reaches an environment when you deploy there again; posting as a group that environment does not have yet is refused with a plain sentence. Agents created before Runs as existed keep the Administrator credential until you pick a group, and the page says so in amber. More: Governance and limits.
?deployment_id= to call one environment's post.More: Configure, field by field.
Only when you post again. The brief, access and grants (including Runs as), triggers, guardrails and approval mode are frozen into the post. Editing them changes nothing on the running agent until you Post again. When a design has been edited since it was posted, the header reads edited since posting.
Immediately. Pause and resume, tool auto-allow (Always allow), and the agent's memory.
More: What changes live.
More: Reading the agent page.
A run that did not complete says why on its row: Stopped by you, Replaced by a newer run, Ran out of time, Waited for an answer and gave up, Interrupted by a restart, or the last tool error. When the platform cannot reach a deployed app — after retrying a few times — the run ends with Environment unreachable from the platform: the app may still be running, but PIES has no network path to it.
Budgets are per run — iterations, tokens and minutes — plus monthly tokens (0 means no cap). Left empty, a run gets the platform defaults: 40 iterations, no token cap, 30 minutes (60 at most). A long run folds its history into a handover at three quarters of its iteration budget and continues, up to three times; a run that hits a limit ends with what it has. At its monthly token limit the agent is not started at all, and you are told what it has used. More: Inside a run.
An errand is one action on a running application: re-send the failed invoices from Friday, check every open ticket against its SLA. It has no board and produces no application version; it ends with an outcome.
Start one from Start work — it proposes Errand when your wording asks for one action — or from Run an errand on a deployment's Agents tab. Pick the environment, what it may touch, and the model. The run opens on its own page with its 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. More: Errands.
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 (Small, Mid, Strong), and whether it runs once per delivery or once per card. Nothing in a playbook is posted, versioned or seated.
Every workspace comes with three, marked Stock — edit or delete them like any other:
The Playbooks page has a workspace bar, a search over names, descriptions and step names, a Stock / Made here filter, and sorting by name, most used or most steps; Start delivery appears when you hover a row, and New playbook starts from a stock recipe or blank. Three principles the stock playbooks follow: whoever builds never closes a card — Verify closes it, with probe evidence; Verify never fixes; and the one Strong step is the one that has to be right first time.
The API still calls a playbook a squad, and the rules field is still charter on the wire: /agents/squads/list, /agents/squads/create and the rest are unchanged. If you script against PIES Studio, that is the word to use. Nowhere else does it appear.
More: Playbooks.
A delivery is build or change work on one application and one branch, with a board of cards and a baseline to roll back to. Find deliveries in the editor under Build › Deliveries; start one from Start work.
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.
The delivery opens in its cockpit:
Nothing reaches production without a deploy, which is a separate decision. More: Deliveries.
You are told, rather than left guessing. A delivery whose work was in flight is marked interrupted — "Interrupted by a restart — start the delivery again" — and offers Run again. A run reads Interrupted by a restart; run it again.
Activity is the one feed. Its tabs are Needs you, Running, Today, Failed and Everything, filterable by kind. Anything waiting on a human sits under Needs you: an approval, a decision in a delivery, a question an agent asked.
| Autonomy | What parks for approval |
|---|---|
| Supervised (default) | Any call that writes. Reads pass through, so an unattended run can look before it asks. |
| Autonomous | Nothing. It never asks, so keep it for read-only agents; the composer warns when an agent that can write is set this way. |
| Locked down | Every function call, reads included. |
Set it under Guardrails → Autonomy. Beside it, Who is asked decides where a parked call goes: Whoever posted it, The app's operators, or These people. An app agent's requests go to the app's operators for that environment, not to whoever built it.
Never approve blind. Open the card: who started the run and when, the function or query with its parameters as a table, the agent's own reason, the steps 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 adds a standing rule to the agent, effective immediately. Every decision is written into the run's steps, signed by whoever decided.
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 "Waited N min for an answer and gave up" — and still keeps what it found. More: Activity and approvals.
Every system template installs with an agent pack and sample data shaped so the agents find something on their first run; the gallery's What the agents will find names the rows.
Sample dates are relative, so "due next week" is true whenever you install. Sample rows are loaded only the first time the database is created. More: Templates with test data.
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. More: Troubleshooting.
See also: Agentic AI manual · Glossary · How PIES AI works · the user manual.