Hiring & customizing agents
A team's roster isn't fixed. You can hire new agents, retire ones you don't need, and tune how each agent behaves - both from the web app and by asking the CEO.
Hiring a new agent
Hire agent on the Team tab of the project's Team & Budget page asks how you want to go about it, and offers three ways:
- Browse the marketplace - take a proven role out of one of the ready-made teams. It arrives with a written system prompt, a budget and a face, and the CEO fits it to the team you already have. See Team marketplace.
- Ask the CEO - opens a chat thread for this project with the opening message written for you. Add what you need, send, and the CEO works out the role and drafts it. It checks the marketplace first and tells you which role it started from.
- Write the role yourself - the hire screen, where you fill in the role and its system prompt directly.
The three differ in where they end. A marketplace role is added by the CEO without a separate approval, because you already chose it off the catalog. The other two come back to you as an approval: the CEO writes or tidies the full role spec and files it, and you can modify the role, system prompt, budget, heartbeat and code access before approving. Nothing is added to the roster that way without your sign-off.
HQ is not staffed from here. It holds the CEO and Coach, who work across every project.
When you hire an agent you set:
- Role - its title and a short description of what it's responsible for.
- Reports to - the manager this agent answers to. This sets the reporting line in the org chart, which is what lets work be delegated to and from the agent, so it's worth getting right (it defaults to the Captain). You can change it later from the agent's settings, and the Captain/CEO can also adjust reporting lines during a coherence review.
- System prompt - the instructions that define how it works. Write the role itself:
Hezo adds the agent's identity (its team, the team's description, its manager) above what
you write, and its live context (skills, team preferences, project docs, today's date)
below it, on every run. Nothing is required of your text, and the strip above the editor
lists every block Hezo adds. If you want one of those values at a specific point in your
own wording instead, type
{{in the editor to insert it - Hezo then leaves its own copy of that value out. - Model - which provider/model it runs on (defaults to the team's model; override per agent if you want).
- Heartbeat - how often it wakes to look for work. There is no default: the cadence drives both how fast the agent picks up work and how much it spends, so you pick it yourself and the hire form will not submit until you have. The shortest cadence the scheduler runs is 60 minutes. When the CEO or a Captain files the hire instead, it asks you for the cadence before filing rather than choosing one for you. The agent's page shows a live countdown to its next heartbeat (hidden while the agent is disabled or paused).
- Budget - optional token limits (see Budgets & cost control).
- Code access - whether the agent works in the project's code workspace.
Once approved, the agent is onboarded into the team and starts picking up work on its heartbeat. The agent that proposed the hire is woken as soon as you decide, so it can act on your answer straight away: confirm the reporting line, finish the rest of the setup, or, if you denied it, revise the role or drop it. Denying wakes it for the same reason. Your decision also shows on the originating task, where the proposal card flips to hired or denied.
New agents wait for the team setup review
Adding an agent - by hiring one, or by provisioning a whole roster when a project is created - files a team setup review task automatically. That review is what fits the new agent to the team: it reconciles reporting lines, rewrites the descriptive blobs teammates read, and gives the agent the team context its every run is built on.
Until that review is done, any task assigned to the new agent is created Blocked, with the setup review listed as its blocker on the task page. Nothing is lost and nobody has to remember to sequence it: when the review is marked done, every task waiting on it moves back to Backlog and its assignee is woken automatically. This applies however the task was filed - by you in the web app, or by the CEO, a Captain or a teammate.
Agents already on the team are unaffected: they keep picking up work as normal while a new teammate's setup review is open. If you deliberately want a new agent to start before its review lands, remove the blocker from the task's page.
Editing system prompts
Every agent's system prompt is editable from its settings at any time. Changes take effect on the agent's next run, so you can correct course - tighten scope, add a convention, change tone - without rebuilding anything. An edit can never cost the agent its identity or live context: Hezo composes both around whatever you save. Switch to Preview to read the whole prompt as the agent receives it, with every value filled in.
When a built-in role improves
The built-in roles - the Captain, the CEO, the Coach and the rest - keep getting better between releases. Your agents do not pick those improvements up on their own, and that is deliberate: an agent's prompt is yours once it is hired. It carries whatever the Coach has taught it and whatever you have edited, and a release has no business overwriting either.
So Hezo offers the improvement instead of applying it. After an upgrade, any built-in agent whose role has moved on gets a card in your inbox: Updated role available. Accepting rewrites the role's own instructions and keeps everything added since, learned rules and your own additions alike.
Two things make this safe to accept:
- Your additions are kept exactly, not re-formatted or summarised. Hezo knows the role text the agent was hired on, so it can tell the release's words from everyone else's.
- It is one click back. The change is recorded as a revision like any other prompt edit, so the agent's settings page can roll it back if you don't like the result.
If you have edited the role's own instructions rather than adding to them, the card says so: the two versions disagree about the same lines, and accepting keeps the new role and the learned rules while dropping your edits. Declining keeps exactly what you have, and Hezo does not ask again for that version - though it will offer the next improvement when one arrives.
Reviewing an agent's runs
Every agent has an Executions tab listing its runs - what triggered each one, how long it took, what it cost, and the full log. The list opens on every run, newest first. The filter above it narrows to a single outcome: All, Succeeded (runs that finished cleanly) or Errored (runs that failed or timed out). A run that is still queued or running, or one that was cancelled, belongs to neither narrow view and appears under All. The choice is part of the page address, so a filtered view can be bookmarked or shared, and opening a run and coming back returns you to the view you were in.
A run waiting its turn shows as queued, not as an error - it keeps its place and starts as soon as whatever it is waiting for is free. A run waits for a container to free up when the instance is already at its limit. If the wait outlasts its patience the run is recorded as cancelled and the work goes back on the queue to be picked up again; that is not a failure, and it is why cancelled runs are their own thing rather than errors. Hover the queued run's info icon to see the reason. See how much can run at once.
The model provider can also turn a run away before the agent gets a turn, because the model is at capacity, the request was rate limited, or a subscription's usage allowance is spent. The run consumed nothing, so Hezo treats it the same way: the run is recorded as cancelled and the work goes back on the queue.
For capacity and rate limits, Hezo waits a few minutes before trying again, so it does not retry straight into a provider that is still busy. Nothing on your side clears this wait, since no container frees it; only the provider recovering does. Press Run now on the task to try again immediately. If the work is still being turned away after two hours, Hezo stops retrying and raises an item in your Inbox, so a long outage does not sit unnoticed. Switching the agent or task to another model is usually the fastest way through.
A spent usage allowance applies to the whole credential, so Hezo pauses every run on that credential until the reset time the provider gives. Agents on other tasks wait too, and none of them starts a container just to be refused. When the reset time comes, the waiting work starts again. Hezo raises one Inbox item when the pause begins, naming the credential and the time. To resume sooner, for example after adding credits, press Run now on a waiting task. If that run gets through, the rest of the work on that credential resumes with it. Replacing the credential in Settings > AI Providers also ends the pause. When the provider gives no reset time, Hezo tries a single run every half hour until one gets through.
When the pause ends, the waiting work does not all start at once. It resumes oldest first, one run every 30 seconds, so a few runs can show whether the allowance is really back before the rest start. If the provider turns the next run away, the pause starts again and the work still waiting stays queued. Work on other credentials is not affected.
Either Inbox item is a notice rather than a decision: click it and it opens the run behind it, inside the task, and clears itself on the way. Often you need do nothing at all, because the agent's next successful run clears it for you, on whichever task or project that run happens.
Cancelled covers one more case, and it is the only one that asks anything of you. If a run is queued but never begins - Hezo lost track of it before the agent launched - the work is put back on the queue and runs again on its own. Should that keep happening, Hezo stops after three attempts, says so on the run, posts a note in the task, and raises an item in your Inbox, opening on the run that failed just like the provider notice above, and cleared the same way by the agent's next successful run. A run that died before it had a task has nothing to open, so that notice keeps a Dismiss button instead. That run carries a Retry button, which is the only cancelled run that does: a run you stopped yourself, or one whose work is already back on the queue, has nothing left to press. A run like that is not counted as an error, so it does not raise the task's error marker; the note in the task and the Inbox item are how you find it.
Per-agent model override
By default the agents on a team share the team's model. You can override the model for any individual agent, so (for example) one agent runs on a frontier model for hard reasoning while the rest run on something cheaper and faster. Mixing providers within a single team is supported. See AI model support.
Retiring & reinstating agents
When a team no longer needs a role, you can retire (disable) the agent - from its settings in the web app, or just by asking the CEO. Retiring stops the agent from being scheduled and unassigns it from any open tasks, but keeps all of its history, so it's fully reversible: reinstate (enable) it at any time and it picks work back up on its heartbeat. The CEO actions this directly once you confirm, which is handy after a project's direction changes and several roles no longer fit. (A team's Captain can't be retired by the CEO - only an admin can, from the web app. The global CEO and Coach run coordination and review across every project, so they're essential and can't be retired at all.)
Other settings
You can also adjust an agent's heartbeat interval, its run time limit and its budgets over time, and pause or resume agents when you need to. The run time limit is how long one run of that agent may take before Hezo stops it and hands the work back to the queue. Raise it for an agent whose work is long, and lower it for one you want kept short. Standing preferences you give the CEO in chat are remembered and applied going forward.