Skip to content
Build Perch
Browse documentation

Agents

Short answer: An Agent is a saved AI worker: a standing prompt, a model, and a tool allow-list you configure once and reuse. Run it on demand from the Workers panel, from a workflow step, or by asking the AI in chat to delegate to it.

What is an agent?

An Agent bundles four things into one reusable, named worker:

  • A prompt: the standing instruction it gets on every run. Because an agent runs unattended and never sees your chat, the prompt needs to be self-contained: whatever background, format, or constraints the job needs have to be written into it.
  • A model: the specific chat model that runs the agent (any model your connected providers expose).
  • A tool allow-list: the exact tools the agent may call, each with its own approval mode (auto-run, or ask-first) and, if a validator is set, a validation mode (off, advisory, or blocking).
  • An optional validator model: a second model that reviews specific tool calls. Set per tool to advise (log a verdict, run continues) or block (halt the run for review on a failed verdict). Blocking is off by default so a validator misjudgment can’t wedge a run.

Beyond that core shape, an agent can carry: an input folder and output folder it reads from and writes to, a maintain target (a specific file the agent is only allowed to edit surgically, never overwrite wholesale), a deliverable output file it writes each run, and seed notes: starting guidance in a persistent notes.md file the agent reads every run and can update as it works. If a validator is configured, an optional reflection pass reviews the run afterward and can rewrite those notes to improve future runs.

Every run also appends to an operational report, so you can see exactly what an agent did on any given run.

Agents themselves don’t schedule or listen for incoming messages; that’s what Triggers are for, bound to a Workflow. Wrap an agent in a one-step workflow to put it on a timer or fire it from an email or Discord message.

How do I create and run an agent?

  1. Open the Workers panel and switch to the Agents tab.
  2. Create a new agent, or ask the AI in chat to save the current task as one (“save this as an agent that does X”). Either path opens the same editor for review before anything is saved.
  3. Set the prompt, model, and tool allow-list. Add a validator model and folder scope if the job needs them.
  4. Run it with Run now from its card, or delegate to it from chat once it’s saved.

When you delegate from chat, the AI can run the agent inline (the chat waits for the result) or in the background: the chat keeps going, and the result posts back into the conversation when the agent finishes, with a click-to-open notice if you’ve since moved to another chat. Either way, progress shows live in the Activity bar.

Good to know

  • The tool allow-list is a hard boundary: a tool not on the list isn’t callable by that agent, even if the same model would have access to it in a normal chat.
  • Sends (email, Discord messages, Notion writes) never auto-approve in chat, and on an unattended agent run they only go to destinations you pre-authorized when you set the agent up; anything else parks the run for your review instead of sending.
  • A Confine this agent option in the editor hard-locks the agent to its input/output folders (read-only from one, write-only to the other); see Scoped folders.
  • Every run gets a History card with one-click Revert; see Run history and revert.
  • Agents can’t delegate to other agents; that stays chat-only. They can generate images, speech, and music (held to a daily budget cap, default 50/day); video generation is chat-only. See Generating media.