Build agents

Scheduled agents

Not every agent waits to be messaged. A scheduled agent has a goal and runs on its own, on a schedule or on demand, using its tools and knowledge to do work and report back.

The agent type

A scheduled agent is a bot with bot_type set to agent (versus chatbot). Instead of replying to incoming messages, it pursues an agent goal when it runs.

What you configure

Goal (agent_goal): what the agent should accomplish on each run.
Schedule (schedule): when it runs; the editor previews the upcoming run times, and next_run_at / last_run_at track its cadence.
Iteration budget (max_iterations) and a per-run timeout (timeout_seconds): bounds on how long and how hard it works.
Output (output_config): where its result goes (for example, email or a webhook tool).
Persistent conversation (persistent_conversation): whether runs share context. Off by default: each run starts a fresh conversation (best for unrelated tasks like article generation). On: all runs share one ongoing conversation, so each run sees the previous run's context (best for recurring work like monitoring).

These are fields on the bot. Set them in the editor or via the Bots API.

Planning & quality

Longer runs sometimes drift off course or hand back an answer in the wrong shape. A few optional settings on the Agent tab help a run stay on track. They are all off by default, so turn one on only when a plain run needs a steadier hand.

Re-plan every few steps. Have the agent stop and rethink its plan at a set interval, so a long run does not wander. Leave it off for short, direct tasks.
Goal-check model. Judge whether the goal is really met with a separate, usually stronger model instead of the agent's own. Useful when finishing early would be costly.
Output schema. Describe the exact shape the final result should take, written as JSON. The agent tries to make its output fit, and the run is flagged if it still cannot. Reach for this when the result feeds a spreadsheet or another system that expects fixed fields.
Run reflection. After each run the agent writes itself a short note about what it learned and opens the next run with it, so recurring work gets better over time.

Runs & results

Each run executes as a conversation you can read and trace, so you can see exactly what the agent did: the steps it took and the tools it called. Trigger a run on its schedule, or start one on demand from the dashboard. By default every run is its own fresh conversation. Turn on Persistent conversation to have all runs continue one shared thread instead.

When you start a run by hand, the Run now dialog includes an optional instructions box. Whatever you type there becomes the input for that one run, so you can point the agent at something specific - revise this, check that - without touching its standing goal or prompt. Leave it blank and the run behaves exactly as a scheduled one would. Instructions apply to that run only; nothing is saved to the agent. The same dialog appears whether you trigger from the agent's editor or from its conversation view.

When the agent uses a model that shows its thinking, you can watch it reason in real time. A thinking panel streams open while the model works and folds up to a short summary once the answer begins, and you can reopen it any time to read the full reasoning. Wherever the agent used a tool, you can also see a short note on why it chose that one. This lets you follow the agent's reasoning without guessing at it.

If a run is cut short by a restart, it shows as Interrupted in Conversations and can pick up where it left off. This is a pause, not a failure, and the transcript up to that point is kept.

Give a scheduled agent the tools it needs to act and the knowledge it needs to reason. The goal is only as achievable as the capabilities you give it.

Safety in autonomous runs

A scheduled or triggered run is autonomous, so no person is watching it. To limit the blast radius of a mistake or a prompt injection, Hania gates two kinds of tool in autonomous runs. Interactive chat and live runs are never gated; a tool that works when you're present may still be blocked when the same bot runs on a schedule.

Destructive tools are blocked. A tool classified destructive (delete, cancel, refund, wipe, run shell commands…) is blocked in autonomous runs, by classification, not by what the specific call would do. The bot doesn't crash; it receives the block as a tool result and adapts. Lift it per-bot with Allow destructive actions in autonomous runs (on the Agent tab), which lifts the block for all of that bot's destructive tools at once.
External sends must name the destination. A tool that sends data externally (email, an outbound API) is blocked in autonomous runs unless the destination is named in the agent goal, so a recipient can't be slipped in through injected instructions.

Prefer a least-privilege credential over the toggle: a read-only SSH account, a read-scoped API token, or a SELECT-only database user. That enforces the limit at the resource, where a prompt injection or a model mistake can't bypass it, and lets you classify the tool to match what it can actually do.

Approvals and the review queue

An agent does not have to guess on a judgement call. It can pause and ask you first, then pick up the same run the moment you answer. This happens in two ways.

Asking a question

Give the agent the Ask a Human tool, a credential-free built-in that you assign like any other tool, with no setup. When the run reaches a decision it should not make on its own, it stops gracefully and queues a question instead of guessing.

Questions land in the Review queue, under Operate in the sidebar, where the nav item shows a badge with the number of pending requests. Each request shows the agent's question, any context it attached, and the options it offered. You can approve, decline, or type free-form guidance in your own words, since the options are only suggestions. The moment you respond, the agent resumes from where it paused, with full context intact, and finishes the work.

Approving a tool before it runs

You decide which tools need a sign-off when you assign them to the agent. Each assigned tool has an Approval setting with three choices: Never (the default, where the tool just runs), Always (every use waits for you), and When destructive (it waits only for tools that delete data or send it somewhere external). Set it on the tools you want to keep a hand on and leave the rest on Never.

When a tool set to pause comes up in a run, the agent stops right before it and asks you to sign off on the exact action. The request shows the tool it wants to use and the arguments it plans to send, laid out so you can read them. You have three choices:

Approve to let it run exactly as shown.
Approve with edits after correcting an argument, for example fixing a recipient address or trimming a number, so the agent runs your corrected version instead.
Deny with a short reason, which the agent reads and then works around.

For an autonomous run, the approval waits in the Review queue alongside questions. For an interactive agent you are chatting with, the same approve, edit, or deny card appears right in the conversation, and the agent continues as soon as you decide.

How the queue behaves

One request at a time. While a request is pending, that agent's schedule is paused too, so requests never stack up.
72-hour window. A request left unanswered for 72 hours expires and can no longer be answered, and the run is closed. Answer before the countdown runs out.
Anyone on the team can answer. The queue is shared across your workspace, with no per-request assignment.

A paused run also shows as Paused, awaiting input in Conversations until it is answered, or Expired if the window lapses. Interactive chat agents do not use the queue for questions; they ask you inline in the conversation, the same place a tool approval card appears.

Email alerts for new requests are best effort and only fire when the agent has an email tool with recipients set. The Review queue is the source of truth, so answer there.