# Hawi > Hawi is an AI agent operations platform for small retail and commerce teams. Named agents handle configured order, stock, supplier, and customer-support work while people retain the decisions they choose to review. ## Reading notes - This document is generated on the server from Hawi's authoritative public documentation corpus. - It contains no user, workspace, session, credential, or private operational data. - Marketing diagrams and dashboard figures are examples or sample data, not customer results or performance benchmarks. - Connector availability depends on operator configuration, customer connection, and any vendor approval required for that connector. - Approval routing is configurable per agent and action type; do not turn that configuration into an absolute runtime guarantee. - Prices are intentionally omitted here. Read the live pricing page for current amounts. ## Public pages - [Home](https://hawiagents.com/): Product overview and examples - [Act](https://hawiagents.com/act): Agent roles, handoffs, and execution - [Approve](https://hawiagents.com/approve): Configurable approval routing - [Boards](https://hawiagents.com/boards): Operational boards and work structure - [Intake](https://hawiagents.com/intake): Work capture, routing, and boards - [Monitor](https://hawiagents.com/monitor): Run records and operational review - [Integrations](https://hawiagents.com/integrations): Customer-connectable provider catalogue - [Marketplace](https://hawiagents.com/marketplace): Public agent marketplace - [Pricing](https://hawiagents.com/pricing): Current plans and billing mechanics - [Developers](https://hawiagents.com/developers): Developer platform entry point - [Security](https://hawiagents.com/security): Security and data-handling information ## Documentation corpus ## Start here What this is, and the shortest path to an agent doing one real job. ### What Hawi is Source: https://hawiagents.com/docs/what-hawi-is Named agents that work orders, stock and customer messages across the systems a shop already runs, on a board a person can read. Hawi is an operations surface for small commerce teams. You describe the jobs you repeat — chasing a late supplier, answering “where is my order”, watching stock cover on the lines that actually sell — and you give each one to a named agent. The agents read from the systems you already run, write back to them, and put what they did on a board you can read without asking anyone. The word that does the most work in that paragraph is “named”. Hawi is not one assistant with a text box. It is several agents with separate briefs, separate tool access and separate spending ceilings, which hand work between each other and to people. Atlas takes orders, stock and suppliers. Mira takes the inbox. Vela takes calls. Those are defaults, not fixtures; you rename and rebrief all of them. #### Product boundaries - Customer messages require a channel you connect and an agent you brief. Hawi has no storefront chat widget. - Your shop platform, accounting system and helpdesk remain the source systems. Hawi reads and writes across them. - A new workspace starts with no connections, no agents and a per-agent spending ceiling of zero. You enable each capability from there. - Agents use written briefs, tool lists and limits. There is no canvas of connected workflow boxes. #### Who it fits Dropshippers, marketplace sellers, vintage resellers, retailers and wholesalers — teams between roughly two and forty people where one person is doing the operational work of three. It also serves larger companies that need several teams running agents against shared connections with reporting that suits a role, which is why workspaces, roles and per-workspace connection selection exist at all. > **The shape of a Hawi day** > Work arrives on its own from the channels you connected. Agents pick up what matches their brief. Anything you routed to a person waits in a queue with your name on it. In the morning there is a brief saying what moved, what stalled and what is still waiting. That is the whole loop; everything in these docs is a detail of it. #### The five stages The product and most of this documentation follow five stages. A single order can move through all five over a week. - **Intake:** Mail, marketplace messages and stock alerts become board items carrying a source, a status and an owner. - **Watch:** Stock cover is recalculated from sales, listings are compared with the stock sheet, and supplier follow-ups are scheduled. - **Act:** A named agent with a defined brief, a model, a tool list and a ceiling does the work and hands off what is not its job. - **Approve:** The actions you chose to route to a person wait in a queue showing the current record beside the proposed change. - **Monitor:** A daily brief, and a trace of any result back through its inputs, tool calls, handoffs and decisions. > **Trivia** > The five stages were seven for about a fortnight. Boards and Limits were stages six and seven before they were moved out to their own pages, because a stage that every other stage passes through is not a stage — it is the floor they stand on. ### Quickstart Source: https://hawiagents.com/docs/quickstart Workspace, one connection, one agent, one ceiling. About twenty minutes, most of it waiting for a provider to authorise. This is the shortest path from nothing to an agent doing one real job. It deliberately connects one system rather than all of them, and briefs one agent rather than a team, because the failure mode for every operations tool is a fortnight of configuration before anything is worth looking at. 1. **Open a workspace.** A workspace is the boundary everything else sits inside: connections, boards, agents and the people you invite. Most shops need exactly one. Open a second only when you genuinely run two businesses that should not see each other’s orders, because nothing is shared between them by design. 2. **Connect wherever orders actually arrive.** One system, not five. For most people that is a marketplace or a storefront. A provider is connected once to your account and a workspace then selects that connection, so a second workspace can reuse it without the credential being copied anywhere. 3. **Brief one agent on one job.** Pick something you repeat every week and could describe to a new starter in two sentences. Chasing late suppliers and flagging stock cover are where most people begin. Name it, write the brief, and choose which tools it may touch. 4. **Set the ceiling and the queue.** Two settings decide how much rope the agent has: the spending ceiling it works inside, which starts at nothing, and which of its actions come to a person before they go out. Raise the first slowly. See Limits and ceilings. 5. **Leave it a week, then read the brief.** After about a week there is enough to look at: what moved, what queued, and where the agent asked for help. That is the point at which adding a second agent is worth doing, and not before. > **Do not start with the inbox** > Mail feels like the obvious first connection and is the worst one to learn on. It has the highest volume, the most ambiguity and the most expensive mistakes. Start somewhere with structured records — a marketplace, a storefront, a stock sheet — and connect mail once you have read a week of traces and know how the agent behaves. #### What you need before you start - An account, and an email address you can receive at. Sign-up is its own flow and is not covered here. - Administrator access to whichever system you are connecting first. A provider connection almost always needs someone who can authorise an application against the account. - A rough idea of one repeated job. Not a specification — two sentences. #### What is deliberately not in the quickstart Voice, custom connectors, the developer API and multi-workspace setups are all real and all documented, and none of them belong in a first hour. They each assume you already know what a run looks like when it goes well and what it looks like when it does not. ### Core concepts Source: https://hawiagents.com/docs/core-concepts The eight nouns the rest of the documentation assumes you know. Eight nouns carry most of the product. Everything else in these pages is built out of them, and the fastest way to read the rest is to be sure of these first. - **Account:** You. Sign-in, billing identity, and any personal credit balance. An account can belong to several workspaces and its balance is not workspace-scoped. - **Workspace:** The operational boundary. Agents, boards, connections and members all live inside one. Nothing crosses between workspaces except by an explicit cross-workspace handoff. - **Connection:** An authorised link to one external system, held against your account and selected by a workspace. The credential itself never enters the workspace record. - **Agent:** A named worker with a brief, a model, a tool list, a spending ceiling and a run history. Agents are standing, not per-conversation. - **Board:** Where work is visible. Items carry a source, a status, an owner — who may be a person or an agent — and their full history. - **Item:** One piece of work. An order exception, a stock question, a supplier chase, a customer message. Items are what agents pick up and what people read. - **Run:** One attempt by one agent at one item, recorded with its inputs, tool calls, handoffs, cost and outcome. Runs are the unit of the audit trail. - **Credit:** The unit of metered work. Model calls, tool calls and voice minutes consume credits at a rate set by the live pricing version, not by anything written on this page. #### How they fit together _The containment order, outermost first_ ```text account └── workspace ├── members (people, with roles) ├── connections (selected from the account's authorised providers) ├── agents │ ├── brief, model, tool list, ceiling │ └── runs ──────────┐ └── boards │ └── items ─────────┘ (a run is always against an item) ``` > **Owner is not always a person** > An item’s owner can be an agent. This is deliberate and it is the single most useful thing on a board: the column tells you at a glance which work is currently a machine’s problem and which is yours. An item with no owner is in triage and belongs to nobody yet. > **Trivia** > “Run” beat “task”, “job” and “execution” in naming, on the grounds that it is the only one of the four that is already a noun and a verb in warehouse English. Nobody says “I executed the reorder”. ### The first week Source: https://hawiagents.com/docs/first-week What actually happens between opening a workspace and trusting it, day by day. The quickstart is twenty minutes of setup. This is the week that follows it, which is the part that decides whether the thing gets used. It is written from what the product does rather than from a rollout methodology, and the only instruction that really matters is the one on day one: pick a job small enough to be boring. #### Day one — one connection, one agent, no ceiling Connect the system where your orders arrive. Brief one agent on one repeated job. Leave its spending ceiling at nothing, which is where a new agent starts, and route everything you can to the approval queue. The agent will read, classify, draft and hand off; it will not spend. That is the correct first day. #### Days two and three — read the traces, not the board The board tells you what happened. The trace tells you why, and in the first week why is the only thing worth your attention. Open three or four runs in full and read what the agent looked at before it decided. Two things usually show up: a brief that is more ambiguous than it looked, and a source the agent keeps consulting that turns out not to be authoritative. > **A growing triage column is a briefing problem** > Items arrive unowned and sit in triage until a brief matches them. If that column keeps growing, the work arriving is not the work you described. That is worth fixing before adding a second agent, because a second agent with the same gap just produces two triage columns. #### Day four — rewrite the brief once By now you will have seen the agent do something reasonable that you did not want. Almost always the fix is one of the two sentences most briefs are missing: what to do when unsure, and what never to do. Add them, and leave everything else alone so you can tell what the change did. #### Day five — raise the ceiling by a small amount Set it to a figure you would shrug at losing over a week. Not a figure that covers your busiest day. The point of the first raise is to see what the agent does when spending is possible at all, and a small number tells you that just as well as a large one. #### Day six and seven — the first brief that matters After a full week the daily brief has something to compare against. What settled, what stalled, what waited on you and for how long. The number to look at is the oldest waiting item: if something sat in the approval queue for fourteen hours, the queue is not being read, and no amount of agent capability fixes that. > **Trivia** > The most common first agent is supplier chasing, and the reason is boring in a useful way: it is high-frequency, low-stakes, entirely text, and everyone already knows what a good outcome looks like. It is the job most likely to survive the first week without anyone arguing about it. ### Who it fits, and who it does not Source: https://hawiagents.com/docs/who-its-for The shape of operation this suits, and four where something else is the better tool. Hawi fits operations where one person is doing the work of three: orders arrive from several places, stock needs frequent checks and the customer inbox competes with everything else. That is usually a team of two to forty people, though the shape matters more than the count. #### The shape it fits - Work arrives continuously from systems you already run, rather than being entered by hand into one place. - The same handful of exceptions repeat every week — late supplier, wrong address, damaged item, oversell. - Somebody could describe each of those exceptions to a new starter in two sentences. - There is a person who would read a morning summary and act on it. #### Where something else is the better tool - **A single high-value negotiation:** One deal a month, each one different, each one worth arguing about. Nothing here beats a person with a phone, and the setup cost is not recovered. - **Work with no external system:** If the orders live in a spreadsheet on one laptop and nothing else, there is nothing to connect. Get the data somewhere addressable first; that is a bigger win than any agent. - **A compliance process that must be identical every time:** A deterministic workflow tool is the right shape for something where the same input must always produce byte-identical output. Agents are for judgement against messy input. - **Customer-facing chat on your storefront:** There is no shopper-facing widget. Agents work the inbox and the board behind it; they are not a front-of-house chatbot and adding one is a different product. > **The honest test** > Write down the job you would give the first agent. If you cannot describe it in two sentences without saying “it depends”, the problem is not the tool — it is that the job has not been decided yet, and no software resolves that on your behalf. ### How this differs from the things it resembles Source: https://hawiagents.com/docs/how-it-differs Against a chatbot, an automation builder, a helpdesk macro, and a virtual assistant. Four things get compared to this, and the differences are structural rather than a matter of quality. None of the four is worse at what it is for. #### Against a chatbot A chatbot exists for the length of a conversation. An agent here is standing: it holds a brief, accrues a run history, owns items on a board, and is still there on Monday having done things while you were not watching. The difference shows up in the second week, when you want to know what it did on Thursday. #### Against an automation builder A canvas of boxes and arrows does the same thing every time, which is exactly right for a deterministic process and exactly wrong for “this supplier replied with something ambiguous”. Agents are briefed in sentences and bounded by settings rather than drawn, and the trade is predictability for coverage of the messy cases. #### Against a helpdesk macro A macro fires on a rule you wrote and applies a template. An agent reads the thread, checks the order, decides whether the template applies, and hands off when it does not. A macro cannot decline to run. #### Against a virtual assistant The closest comparison in behaviour, and the one where the differences are most worth stating plainly: an agent works continuously rather than in shifts, has no context beyond its brief and the systems you connect, and produces a trace of every decision. A person brings judgement about things nobody wrote down, and does not need the brief to include what to do when unsure. | | Chatbot | Automation builder | Agent here | | --- | --- | --- | --- | | Lifetime | One conversation | One trigger | Standing | | Handles ambiguity | Sometimes | No | Yes, or hands off | | Record of what it did | Chat log | Run log | Trace with inputs, tools, cost | | Owns work | No | No | Yes, on a board | | Hands to a person | No | By branch | By brief, with evidence | ### Before you start Source: https://hawiagents.com/docs/readiness-checklist The eight things worth having ready, and the two decisions worth making first. None of this is required to open a workspace. It is what makes the first week productive rather than exploratory. #### Have ready - Administrator access to whichever system your orders arrive in. Almost every connection needs somebody who can authorise an application against the account. - The name of one repeated job, written in two sentences. - A sense of what that job costs when it goes wrong, because that is what sets the first spending ceiling. - One person who will read the approval queue. Not a rota — one person, at first. - An email address that reaches someone, on the account you register providers with. Approval decisions go there. - Your stock sheet, wherever it lives, and an honest answer about whether it is current. - The last four exceptions you handled by hand. These become the first agent's test cases. - Half an hour, twice, in the first week — one to set up, one to read traces. #### Decide first - **Which single system to connect:** Not all of them. Wherever your orders actually arrive. Structured sources before mail, always. - **What the agent must never do:** Two or three things, decided before it runs rather than after it surprises you. This is the sentence most briefs are missing and the one that most changes behaviour. > **Do not connect everything on day one** > Every connection widens what the first agent can see and lengthens the trace you have to read to understand it. Five connections on day one means every diagnosis in week one has five candidate causes. ## Workspaces The boundary everything sits inside, and the people in it. ### Workspaces Source: https://hawiagents.com/docs/workspaces The boundary everything sits inside, when to open a second one, and what does not cross between them. A workspace holds agents, boards, connections and people. It is the unit of isolation: two workspaces share nothing by default, cannot see each other’s items, and do not pool credits from workspace settings. If you have ever asked “should this be one workspace or two”, the answer is one, unless the two halves genuinely must not see each other’s orders. #### When a second workspace is right - Two businesses with separate books, separate suppliers and separate staff. - A client-services arrangement where each client’s data must stay apart. - A sandbox you are willing to break, kept away from the one that answers real customers. #### When it is wrong - Separating by channel. One workspace with several available connections can handle multiple channels together, and an order that came from one and ships against stock counted in another is a single item, not two. - Separating by team. That is what roles are for. - Separating by season or campaign. Boards and filters handle that, and a workspace you abandon in February still holds its connections. #### What crosses a workspace boundary | Thing | Crosses? | Notes | | --- | --- | --- | | Your sign-in | Yes | One account, many workspaces. You switch without signing in again. | | Personal credit balance | Yes | Balances are account-scoped, not workspace-scoped. | | Provider connections | Partly | Authorised once against the account, then selected per workspace. The credential is not copied into the workspace. | | Agents | No | An agent belongs to one workspace and is not visible from another. | | Boards and items | No | Never visible across a boundary. | | Run history | No | Stays with the workspace the run happened in. | | A handoff | Only explicitly | Cross-workspace delegation is a separate, deliberate arrangement and never implicit. | > **Deleting a workspace** > Removing a workspace removes its boards, items and run history. The provider connections it selected survive, because they belong to the account rather than to the workspace — but any agent brief written inside it does not. Export anything you want to keep first. ### People and roles Source: https://hawiagents.com/docs/people-and-roles Who can see a board, who can brief an agent, and where a role actually comes from. People are invited to a workspace, and what they can do there follows from the role the workspace gives them. Roles are resolved on the server from account entitlements and workspace membership on every request. They are not stored in your browser and they are not something the interface decides. > **Why that last sentence is in the documentation** > An earlier version of the settings object kept a role field in browser storage, defaulting to administrator. Nothing read it, so nothing was ever wrong — but the first feature to gate on it would have made every visitor an administrator of their own client. It was removed, and the rule that replaced it is worth stating publicly: no security decision in Hawi is made from a value the browser can edit. #### What a role governs - Whether you can see a board, and which boards. - Whether you can write or change an agent’s brief, model, tool list or ceiling. - Whether you appear in the approval queue as somebody who can release a held item. - Whether you can select connections for the workspace or invite other people. #### Team conversation Workspace members talk in a persisted conversation inside the workspace, and a message can be lifted onto a board when it needs an owner, a status or agent work. Agents do not post into that conversation. It is a room for the people, and the boundary is deliberate: a channel where a machine can speak is a channel people stop trusting for decisions. > **Trivia** > A refund asked for in team conversation becomes a held item, not a payment. This is the most common thing people try on their first day, usually as a test, and the answer surprises them enough that it is worth writing down. ### Workspace settings Source: https://hawiagents.com/docs/workspaces/settings What is configured at the workspace level rather than per agent or per account. Three levels of configuration exist and it is worth knowing which is which, because a setting looked for at the wrong level is the most common reason somebody concludes a thing cannot be done. | Level | Holds | Examples | | --- | --- | --- | | Account | You, across every workspace | Sign-in, billing identity, credit balance, provider authorisations | | Workspace | The operational boundary | Members and roles, which connections are selected, Automatic Purchasing | | Agent | One worker | Brief, model, tool list, spending ceiling, control mode, approval routing | #### Automatic Purchasing lives here It is a workspace permission, enabled and acknowledged by the workspace creator. It is not part of an agent's configuration, it is not implied by any control mode, and raising an agent's autonomy does not turn it on. If you are auditing a workspace, check it directly rather than inferring it from anything else. #### Connection selection Provider authorisations belong to your account; a workspace selects from them. Selecting one makes it available to be added to an agent's tool list — it does not give every agent access. Both steps are required and they are separate on purpose. > **Trivia** > Nothing security-relevant is stored in the browser. An earlier version of the settings object carried a workspace role that defaulted to administrator and a two-factor flag, neither of them read anywhere. Both were removed rather than left dormant, because the first feature to gate on either would have trusted a value the browser can edit. ### Inviting people Source: https://hawiagents.com/docs/workspaces/inviting What a new member sees, what they can do before a role is set, and when to add the second person. A person is invited to a workspace and their capabilities follow from the role it gives them. Roles are resolved server-side from account entitlements and workspace membership on every request, so nothing a browser can edit decides what somebody may do. #### When to add the second person As soon as there is an approval queue with anything in it. The most common failure of an otherwise working setup is a queue with fourteen hours in it and one person who did not know they were on it. A second reader is worth more than a second agent. #### What a new member should read first - The status vocabulary, so “held” and “stopped” mean the same thing to everyone. - The approvals page, if they are going to be on the queue. - One real trace, chosen by whoever set the workspace up. Reading somebody else's trace teaches more than any description of tracing. > **Team conversation is for people** > The workspace conversation is persisted and is between human members; agents do not post into it. A message can be lifted onto a board when it needs an owner, a status or agent work, and that lifting is the only crossing point between the two. ### Running several workspaces Source: https://hawiagents.com/docs/workspaces/several What is shared, what is not, and how cross-workspace delegation differs from both. Most operations need one. Several make sense when two businesses genuinely must not see each other's orders, when a client-services arrangement requires each client kept apart, or when you want a workspace you are willing to break. #### Switching One account, many workspaces, no second sign-in. Your credit balance is account-scoped and follows you; boards, items, agents and run history do not, and are never visible across a boundary. #### Cross-workspace delegation Work can be handed between workspaces, and it is always an explicit arrangement rather than something that happens because two workspaces share an owner. Without one, an agent cannot see anything outside its own workspace, let alone hand to it. This is the mechanism behind agent-to-agent handoffs across a boundary and it is deliberately not implicit. | | Same workspace | Across workspaces | | --- | --- | --- | | Agent sees the item | Yes, if briefed for it | Only through an explicit delegation | | Trace stays continuous | Yes | Yes, across the delegation | | Connections shared | Yes, once selected | No — each workspace selects its own | | Members shared | No | No | > **A sandbox workspace still spends real credits** > Isolation is about data, not billing. A workspace you opened to experiment in draws on the same account balance as the one answering real customers, so give its agents a small ceiling like any other. ## Agents Briefs, models, handoffs, and the limits you set. ### Agents Source: https://hawiagents.com/docs/agents A named worker with a brief, a model, a tool list, a ceiling and a run history. An agent is standing rather than conversational. It is not created when you open a chat and discarded when you close it; it exists in the workspace, holds a brief, accrues a run history, and is still there on Monday. Everything you configure about one falls into five parts. - **Name:** What it is called on boards, in traces, in handoffs and in the daily brief. Names matter more than they look like they should: a board where three items are owned by “Assistant” is unreadable. - **Brief:** What the agent is for, in sentences. It shapes most of the agent's behaviour and is often under-written. - **Model:** Which model runs it. Chosen per agent, not per workspace, because a supplier-chasing agent and a returns agent do not need the same capability. - **Tools:** Which connected systems it may touch, and whether it may write to them or only read. - **Ceiling:** The spending limit it works inside, and which of its actions go to a person’s queue rather than out directly. #### Writing a brief that works The best test for a brief is whether a new starter could follow it without asking a follow-up question. Briefs that fail in practice are almost always too short and too abstract — “handle customer emails” contains no decision anybody could make. Briefs that work name the job, the boundary, and what to do when unsure. _A brief that produces predictable behaviour_ ```text Chase suppliers who are late against the delivery date on the purchase order. Chase once at three days late and once more at seven. Use the supplier's own thread if one exists rather than starting a new one. If a supplier gives a new date, put it on the item and stop chasing. If a supplier disputes the order contents, hand off to a person and do not negotiate. Never agree to a price change. Never confirm a substitution. ``` > **The two sentences most briefs are missing** > “What to do when unsure” and “what never to do”. Without the first, an agent guesses; without the second, it is helpful in a direction you did not want. Both are worth more than another paragraph describing the happy path. #### The default three _Starting points, not fixtures. Rename and rebrief all three._ | Agent | Default brief area | Typical first job | | --- | --- | --- | | Atlas | Orders, stock and suppliers | Recalculating stock cover and chasing late purchase orders | | Mira | Inbox and drafted replies | Turning customer mail into board items and drafting the reply | | Vela | Calls and follow-up | Answering the phone under your rules and logging what was agreed | > **Trivia** > Atlas, Mira and Vela are all named after things you navigate by — an atlas, a Latin wonder, a star in Carina used for southern-hemisphere fixes. Nothing in the product depends on this and no fourth default has ever needed a name. ### Models Source: https://hawiagents.com/docs/agents/models The six models an agent can run, what they cost relative to each other, and why there is no place to paste your own API key. A model is chosen per agent. Hawi owns and secures the provider credentials, so OpenAI and Anthropic appear here as model choices rather than as connections you authorise — there is no personal-API-key field anywhere in the agent flow, and that is a design decision rather than a gap. _Indicative credits are for roughly 1,000 input and 500 output tokens under the current pricing version, for at-a-glance comparison only._ | Model | Provider | Identifier | Tier | Indicative credits | Positioning | | --- | --- | --- | --- | --- | --- | | 5.6 Sol | OpenAI (ChatGPT) | `gpt-5.6-sol` | Powerful | 18,400 | Strongest OpenAI option. Costs about 5x Luna. | | 5.6 Terra | OpenAI (ChatGPT) | `gpt-5.6-terra` | Balanced | 9,200 | Balanced capability and cost. | | 5.6 Luna | OpenAI (ChatGPT) | `gpt-5.6-luna` | Efficient | 3,680 | Fast and cheap. Good default for routine work. | | Fable 5 | Anthropic | `claude-fable-5` | Highest capability, highest credit use | 32,200 | Highest capability available. Burns credits fastest. | | Opus 5 | Anthropic | `claude-opus-5` | Premium | 16,100 | Deep reasoning. Costs about 4x Sonnet. | | Sonnet 5 | Anthropic | `claude-sonnet-5` | Advanced | 6,440 | Capable all-rounder. | > **The indicative figure is never what you are charged** > The authoritative charge is calculated server-side at the rate version live when the request starts. The number in that column exists so you can tell that one model costs roughly five times another before you pick it. A figure here that has drifted from the database is a display bug on this page, not a billing one on your account. #### Picking one The default is 5.6 Terra (`gpt-5.6-terra`), which is the balanced middle of the OpenAI range. Most routine operational work — classifying an inbound message, deciding whether stock cover has dropped below a threshold, drafting a supplier chase — does not need more than that, and the difference between the cheapest and the most capable model on this list is roughly nine times the credit burn per request. - Routine, high-volume, well-bounded work: the efficient tier. Triage, classification, templated replies. - Judgement against messy input: the balanced or advanced tier. Reading a supplier’s ambiguous email, reconciling a listing against a stock sheet. - Work where being wrong is expensive and rare: the premium or highest tier. Reserve it for the agent that handles exceptions, not the one that handles volume. #### Changing a model later You can change an agent’s model at any time and it applies to the next run. If a stored selection points at a model that has since been retired, the product does not quietly route you somewhere else — it surfaces that the selection was migrated and asks you to pick again. Silently substituting a model changes behaviour and cost without anybody being told. > **Trivia** > The identifier column is the exact wire value sent as `model`, and the backend validates it against the same list twice: once that the identifier exists, and once that it belongs to the provider selected beside it. Sending a valid Anthropic identifier under the OpenAI provider is rejected before it reaches anybody’s API. ### Handoffs Source: https://hawiagents.com/docs/agents/handoffs How work moves between agents, and from an agent to a person, carrying its evidence. A handoff moves an item from one owner to another and carries the item, the evidence gathered so far, and the run history with it. This is the difference between several agents and several separate tools: the second agent does not start from the beginning, and the person who eventually reads it can see every step without asking. #### What travels with a handoff - The item itself, with its source and current status. - Everything the previous agent read, including which tool calls returned what. - The reason for the handoff, written by the agent that made it. - The full run history, so a trace is continuous across owners rather than restarting. #### Handing off to a person An agent that reaches the edge of its brief hands off rather than guessing. Where that lands depends on how you configured the agent: a plain handoff puts the item in somebody’s ownership on the board, and an action you routed to the approval queue arrives there instead, with the current record shown beside the proposed change. > **Cross-workspace handoffs are explicit** > Work can be delegated between workspaces, but never implicitly. It is a deliberate arrangement between two workspaces, and without one an agent cannot see, let alone hand to, anything outside its own. > **Trivia** > The reason field on a handoff is written by the agent handing off, not by the one receiving. It reads slightly oddly in traces — an agent explaining itself to a colleague — and it is the field support asks for first, so it has survived two attempts to remove it. ### Limits and ceilings Source: https://hawiagents.com/docs/agents/limits The per-agent spending ceiling that starts at nothing, the approval queue you configure, and what each one is and is not. Two controls decide how much rope an agent has, and they are different things that people frequently merge. One is about money. The other is about which actions pause for a person. Configuring one does not configure the other. #### The spending ceiling Each agent works inside a spending ceiling, and a new agent’s ceiling is nothing. Nothing is a real value, not a placeholder: until you raise it, an agent can read, draft, classify and hand off, and has no budget for anything that spends. Raising it is a deliberate act per agent, and it is the setting to move slowly. > **Raise it in steps you would be relaxed about losing** > The useful mental model is a float in a till rather than a credit limit. Set it to the amount you would shrug at if a week of work went sideways, read the traces, then raise it. There is no advantage to setting a high ceiling early, and the cost of doing it is only visible afterwards. #### The approval queue Separately, you choose which of an agent’s actions go to a person before they go out. Those arrive in a queue showing the current record beside the proposed change, so the decision is a comparison rather than a description. Releasing or holding is recorded against your name and the time you did it. This is a routing control that you configure per agent and per action type. It is worth being exact about what that means, because it is easy to read as something stronger: the queue is where the actions you routed to it wait. Which actions those are is your configuration, and it is the thing to review when you change a brief, add a tool, or raise a ceiling. | Control | What it governs | Where it lives | Default | | --- | --- | --- | --- | | Spending ceiling | How much an agent may spend | Per agent | Nothing | | Approval routing | Which actions wait for a person | Per agent, per action type | Set during setup | | Tool list | Which systems an agent may touch, and read versus write | Per agent | Nothing selected | | Automatic Purchasing | A separate, acknowledged permission enabled by the workspace creator | Per workspace | Off | > **Automatic Purchasing is its own switch** > It is a separate permission that the workspace creator enables and acknowledges. It is not part of, implied by, or inherited from any autonomy setting, and turning up an agent’s autonomy does not turn it on. If you are auditing a workspace, check it directly rather than inferring it. #### Reviewing what you configured - After changing a brief. A wider brief with the same routing is a wider set of unattended actions. - After adding a tool, particularly a write-capable one. - After raising a ceiling. - After adding a person to the workspace, since the queue is only useful if somebody reads it. ### Writing briefs Source: https://hawiagents.com/docs/agents/briefs How briefs shape agent behaviour, with four worked examples and their failure modes. A brief is what an agent is for, in sentences. It is not a prompt in the sense of a clever incantation, and it is not a specification. The useful test is whether a new starter could follow it without asking a follow-up question — and the reason briefs fail is almost never that they are too short, it is that they describe only the happy path. #### The four parts - **The job:** What this agent is responsible for, stated once. One job per agent; an agent with three jobs does all three worse than three agents would. - **The boundary:** Where the job stops. This is what stops an agent being helpful in a direction you did not ask for. - **When unsure:** What to do rather than guess. Without this an agent guesses, because guessing is the only option you left it. - **Never:** The short list of things that are wrong regardless of context. Keep it short; a list of twenty is a list nobody can hold. #### Worked example — supplier chasing ```text Chase suppliers who are late against the delivery date on the purchase order. Chase once at three days late and once more at seven. Use the supplier's own thread if one exists rather than starting a new one. If a supplier gives a new date, put it on the item and stop chasing. If a supplier disputes the order contents, hand off to a person and do not negotiate. Never agree to a price change. Never confirm a substitution. ``` #### Worked example — inbound customer mail ```text Turn customer mail about orders into board items and draft the reply. Attach the order reference where the message names one, or where the address and the recent order list identify it beyond doubt. If it does not, ask the customer for the order number rather than guessing. Draft replies in the same register the customer used. Do not apologise for delays that have not happened. Anything about money — refund, discount, goodwill, replacement — is drafted and routed to a person, never sent. Never quote a delivery date the courier has not confirmed. ``` #### Worked example — stock cover ```text Watch cover on the forty lines that sell most, recalculated from actual sales rather than a fixed reorder point. Raise an item when cover falls below twenty-one days, and again at ten. Include the current rate of sale and the last supplier lead time. If the sheet and the listing disagree on quantity, raise it as a reconciliation item and do not reorder against either number. Never place an order. Draft it and route it. ``` #### Worked example — returns triage ```text Sort inbound returns into: damaged in transit, not as described, changed mind, and outside the window. Ask for a photograph where the customer says damaged and has not sent one. One request, not two. Changed-mind returns inside the window follow the standard process. Everything else goes to a person with the evidence attached. Never tell a customer a return is approved. Never tell one it is refused. ``` #### How briefs fail | Symptom | Usually means | Fix | | --- | --- | --- | | Everything ends up handed off | The boundary is drawn tighter than the job | Widen the boundary, or narrow the job to match it | | The agent is confidently wrong | No “when unsure” clause | Add one. It is the single most effective sentence in a brief | | Triage keeps growing | The brief does not match what arrives | Read five triage items and write the brief for those | | Two agents pick up the same item | Overlapping briefs | One job per agent; overlap is a briefing bug, not a scheduling one | | Output drifts over weeks | The brief describes a goal, not a job | Replace the goal with the behaviour you want | > **Change one thing at a time** > A brief rewritten in five places at once produces behaviour you cannot attribute. Change one clause, leave it a few days, read the traces. This is slower and it is the only way to learn what your own instructions do. ### When an agent misbehaves Source: https://hawiagents.com/docs/agents/troubleshooting A diagnostic order for the six things that actually go wrong, starting with the trace. Work through these in order. The order is not arbitrary — it runs from the things that are cheap to check and commonly wrong, to the things that are expensive to check and rarely wrong. 1. **Open the trace, not the board.** The board shows the outcome. The trace shows the inputs, every tool call and what it returned, the decision, and the cost. Nearly every question about agent behaviour is answered in the tool-call list, and usually by something returning less than expected rather than by the agent reasoning badly. 2. **Check whether the run stopped or failed.** These are different outcomes and they mean different things. Stopped is correct behaviour — a source was unreachable, a limit was reached, an input did not make sense. Failed is an error. Reading a week of stops as failures is the most common misdiagnosis there is. 3. **Check the tool list before the brief.** An agent that never does a thing you asked for frequently cannot: the tool is not on its list, or the connection is read-only where the job needs a write. This looks exactly like a briefing problem and is not one. 4. **Check the ceiling.** An agent whose ceiling is nothing will read, classify, draft and hand off, and will not spend. If work stops precisely at the point money is involved, this is why, and it is the intended behaviour rather than a fault. 5. **Check the approval queue.** Work that looks stalled is often work that is waiting, correctly, on a person who does not know they are on the queue. Look at the oldest waiting item before concluding anything about the agent. 6. **Then, and only then, look at the brief.** If the tools are right, the ceiling is right, the queue is being read, and the trace shows the agent had what it needed and still chose wrongly — now it is the brief. See writing briefs for what is usually missing. #### Two things that look like agent problems and are not - **A connector that is listed but not connected:** The catalogue lists every connector Hawi has a definition for. A definition is not a live connection. If an agent cannot see a system, check the connection is added to the workspace and verified before you look at anything else. - **A model change nobody made:** If an agent's stored model has been retired, the product surfaces that the selection needs re-picking rather than quietly routing elsewhere. An agent that has stopped running may be waiting for that choice. > **What to send support** > The run, not a description of it. A trace answers questions a summary cannot, and the first thing anybody will ask for is the run identifier. For anything intermittent, two examples — one is an anecdote. ### Control modes Source: https://hawiagents.com/docs/agents/control-modes The three governance settings, what each one changes, and what none of them is. An agent runs under one of three control modes. They are a governance setting you choose per agent, and changing one changes how much of its work is routed to a person before it goes out. - **human_in_the_loop:** The most routed. Work is prepared and presented for a decision rather than dispatched. This is where a new agent doing anything consequential belongs. - **guarded_control:** The middle setting. Routine work proceeds; the categories you marked as needing a person still come to the queue. - **full_control:** The least routed. Reserve it for agents whose entire brief is reading and classifying, and revisit it whenever you widen that brief. > **A control mode is a routing choice, not a runtime guarantee** > It decides what gets prepared for a person rather than dispatched. It does not, on its own, describe what an agent is technically incapable of. Read it as “how much of this agent's work do I want to see first”, and pair it with the spending ceiling and the tool list, which are the other two levers. #### The three levers together | Lever | Answers | Default | | --- | --- | --- | | Tool list | What systems can this agent touch at all, and read or write? | Nothing selected | | Spending ceiling | How much may it spend? | Nothing | | Control mode | How much of its work comes to me first? | Set during setup | The tool list is the strongest of the three and the one people forget. An agent with no write access to a system does not need a control mode to stop it writing there. > **Automatic Purchasing is not one of these** > It is a separate workspace-level permission that the creator enables and acknowledges. No control mode turns it on, and turning an agent to full control does not inherit it. ### Tool lists Source: https://hawiagents.com/docs/agents/tools How an agent reaches a system, why two gates apply, and what the narrower one is. An agent can only touch systems on its tool list, and only in the way the list allows. This is separate from what the workspace's connection permits, and both apply. #### Two gates, and the narrower wins | Gate | Set where | Question it answers | | --- | --- | --- | | Connection scope | When the provider is authorised | What could anything in this workspace do with this system? | | Tool list | Per agent | What may this particular agent do with it? | A workspace can hold a write-capable connection while every agent in it is read-only through it. That is the safe way to introduce a provider: authorise it at the scope you eventually want, and give the first agent read access only, until you have read a week of traces. #### Capabilities Beyond connectors, an agent carries a small set of capability switches. They are coarse by design — an on/off for a whole class of behaviour rather than a matrix. - **Generative interface:** Whether the agent may structure its output as summary cards and charts rather than prose. - **Voice:** Whether it may use the voice pipeline. See the voice page for which parts of that are connected today. - **Financial bridges:** Open-banking ingestion. Reading is what this enables; anything outbound is routed to a person regardless of the agent's other settings. #### Zero-trust settings - **Input sanitisation:** Ingested payloads are stripped of scripts and injection attempts. Server-enforced, not a client-side convenience. - **Rate limiting:** Hard quotas on prompts, tokens and concurrency, with automatic throttling rather than failure. - **Metric syncing:** Continuous heartbeat, token and log reporting to the telemetry endpoint. Turning it off makes an agent harder to diagnose. > **The agent master configuration is a preview** > This surface is behind a flag and reads safe defaults when the backend is not connected. Its activation token is `null` until a real issuer provisions one and is never fabricated on the client. If you are looking at it and nothing saves, that is why — and the honest failure is the intended one. ### When agents work Source: https://hawiagents.com/docs/agents/scheduling What starts a run, active hours, and why continuous is rarely the right answer. An agent does not run on a clock of its own. It runs when something starts it: a watcher whose check comes due, an arriving message, a person handing it a card, or a rule you wrote. Each watcher carries its own cadence, and the agent page shows the source, its health and when it is next due. That is why two agents in the same workspace can be busy at completely different rates, and why pausing a watcher stops only that watcher — the others keep running, and anything already in flight finishes. #### Active hours Separately, you choose when agents work at all: always, on a daily window, or on a custom cadence measured in minutes. The custom range runs from every minute to once a week. > **Continuous is usually the wrong answer** > A one-minute loop against a supplier's website is a hundred times the requests of an hourly one for information that changes twice a day. It costs credits, it is more likely to hit the provider's own rate limit, and the run that gets throttled is recorded as stopped — which makes your daily brief harder to read for no benefit. #### Queue priority is different Your plan carries a queue priority — low, standard, fast track or high priority. That governs how your runs are scheduled against everyone else's under load. It is not a measure of how fast a model responds, and it does not change your agent's interval. ### Creating, pausing and retiring Source: https://hawiagents.com/docs/agents/lifecycle What happens to work in flight when an agent changes, and the one change that needs care. Agents are standing, so they change while work is in progress. Most changes are safe to make at any time; one is not. | Change | Applies | Work already running | | --- | --- | --- | | Brief | Next run | Finishes under the old brief | | Model | Next run | Finishes on the model it started with | | Tool list | Next run | Finishes with the tools it started with | | Spending ceiling | Next run | Finishes inside the ceiling it started under | | Control mode | Next run | Finishes under the routing it started with | | Pause | Immediately for new work | In-flight runs complete rather than being cut | #### The change that needs care Rotating a provider credential. Everything about the agent survives — connection, workspace selections, tool list, brief — but a run already talking to that provider with the old credential can fail. Rotate at a quiet hour if the provider is one an agent polls continuously. #### Retiring an agent - Its run history stays with the workspace. Removing an agent does not remove the record of what it did. - Items it owned need a new owner. They do not silently return to triage. - Anything of its sitting in the approval queue is still a decision somebody has to make. > **Pause before you delete** > Pausing stops new work and leaves everything else intact, which is almost always what somebody actually wants when they say an agent is misbehaving. It is also reversible, and reading a paused agent's traces is how you find out what to change. ## Work The five stages, boards, and voice. ### Boards Source: https://hawiagents.com/docs/boards Where work is visible: items with a source, a status and an owner who may be a person or an agent. A board is the readable surface of the workspace. Every piece of work is an item on one, carrying where it came from, what state it is in, and who currently owns it. The owner column is the one that makes a board worth having: it tells you at a glance which work is a machine’s problem and which is yours. #### Item anatomy - **Source:** Where it came from. A marketplace message, a mail thread, a stock alert, a call, a person lifting a message out of team conversation. - **Status:** Where it is in its life. See the status vocabulary for the full list and what each one commits to. - **Owner:** A person or an agent. An item with no owner is in triage and belongs to nobody yet. - **Reference:** The external identifier where one exists — an order number, an invoice, a purchase order. What you would search for in the other system. - **History:** Every run against the item, every handoff, and every decision, in order. #### Triage Items arrive unowned. Triage is the column where they sit until an agent whose brief matches picks one up or a person assigns it. A triage column that keeps growing is the most useful diagnostic in the product: it means the work arriving does not match any brief you have written, which is a briefing problem rather than a capacity one. > **Reassignment rather than dragging** > Work moves between columns by changing owner and status, not by being dragged from one to another. The column an item sits in follows from which of those changed, so the board cannot show a state the record does not have. ### Intake Source: https://hawiagents.com/docs/intake Turning mail, marketplace messages and stock alerts into board items with a source, status and owner. Intake is the stage where unstructured arrivals become items. Mail threads, marketplace messages and stock alerts each become a board item with its source recorded, so that six weeks later the trace still says where the work came from rather than only what was done about it. #### What gets an item and what does not Not every message deserves a board item, and a system that makes one for each is a worse inbox with more steps. Intake creates items for arrivals that carry an implied action. A supplier confirming a date you already have does not; a supplier proposing a different date does. - A customer asking where an order is: an item, with the order reference attached. - A stock alert crossing a threshold you set: an item, owned by whichever agent watches that line. - A marketing newsletter from a supplier: not an item. - A delivery confirmation matching what was expected: recorded against the existing item. > **Connect mail last** > It is the highest-volume, most ambiguous and most expensive source to learn on. Connect structured sources first, read a week of traces, then add mail. ### Watch Source: https://hawiagents.com/docs/watch Recalculating stock cover from sales, comparing listings against the stock sheet, scheduling supplier follow-ups. Watch is the stage that notices things before somebody complains about them. It recalculates stock cover from actual sales rather than from a static reorder point, compares what is listed against what is on the sheet, and schedules follow-ups against suppliers who are late. #### Cover, not quantity Cover is how long the stock you hold will last at the rate it is currently selling, expressed in days. It is the more useful number of the two because it moves when demand moves: forty units is comfortable for a line selling one a week and a crisis for one selling ten a day. A reorder point set in units goes stale silently; cover recalculated from sales does not. | Signal | What it usually means | Typical action | | --- | --- | --- | | Cover falling faster than usual | Demand has moved, or a listing went live somewhere new | Recalculate, then draft a reorder at the new rate | | Cover flat while sales continue | The stock sheet is not being updated from sales | A reconciliation problem, not a stock one | | Listing quantity above sheet quantity | Oversell risk on whichever channel is ahead | Reconcile before it sells through | | Supplier past the delivery date on the order | Late, or delivered and not recorded | Chase once, then again, then hand off | > **Trivia** > Cover is reported in whole days and rounded down. Nineteen-and-a-half days of cover is shown as nineteen, on the grounds that everybody who has ever run out of stock did so on the half day nobody counted. ### Approvals Source: https://hawiagents.com/docs/approvals The queue where the actions you routed to a person wait, showing the current record beside the proposed change. You choose which of an agent’s actions go to a person before they go out, and those arrive here. The queue shows the current record beside the proposed change, so the decision in front of you is a comparison rather than a description of one. Releasing or holding is recorded against your name and the time you did it. > **What this page is careful not to claim** > The queue is routing that you configure, per agent and per action type. It is not a promise about what an agent can and cannot do at runtime, and Hawi does not advertise one. Which actions wait here is your configuration, and it is worth re-reading whenever you widen a brief, add a write-capable tool, or raise a ceiling. #### What a queued item shows - The current record, as it stands right now in the source system. - The proposed change, exactly as it would be applied. - Which agent proposed it, against which item, and the run that produced it. - The evidence the agent gathered, so the decision does not require re-reading the thread. #### Releasing and holding Releasing applies the change and returns the item to its agent to continue. Holding stops it and leaves the item owned by a person, which is the right outcome when the answer is “not like that” rather than “no”. Both are recorded; a held item shows who held it and when, and that record is what the daily brief counts. > **A queue nobody reads is worse than no queue** > Routing an action to a person moves the work rather than removing it. The failure mode is a queue with fourteen hours in it and one person who did not know they were on it. Check that somebody in the workspace is actually looking, and check it again when you add people. ### Monitor Source: https://hawiagents.com/docs/monitor The daily brief, and tracing a result back through its inputs, tool calls, handoffs and decisions. Monitor answers two questions at two different scales. The brief answers “what happened” in about ninety seconds. The trace answers “why did that happen” for one specific result, in as much detail as exists. #### The daily brief A short read covering what settled overnight, what stalled, and what is waiting on a person. It is deliberately not a dashboard: there are no charts, because a chart of yesterday is a thing you glance at rather than a thing you act on. Everything in the brief links to the item behind it. #### Traces A trace is the full record of a run: what the agent read, which tools it called and what each returned, what it decided, what it handed off and to whom, what it cost, and how it ended. Traces are continuous across handoffs, so following an item that passed through three agents reads as one sequence rather than three. | Outcome | Meaning | | --- | --- | | Settled | The agent completed the work within its brief. | | Handed off | The agent reached the edge of its brief and passed the item on, with its reason recorded. | | Waiting | An action was routed to a person and is in the approval queue. | | Stopped | The run ended itself — a source was unreachable, a limit was reached, or an input did not make sense. | | Failed | The run ended on an error rather than a decision. These are the ones to read first. | > **Stopped is not failed** > A run that stops itself because a supplier’s site timed out twice has behaved correctly. Counting stops as failures makes the daily brief unreadable within a fortnight, which is why they are separate outcomes. ### Voice Source: https://hawiagents.com/docs/voice Speech generation, call preview, and an exact account of which parts of voice are wired up today and which are not. Voice is the least finished area of the product and this page is written to say so precisely, because the alternative is somebody planning a week around a capability that is not connected yet. #### What works today - Speech generation through a protected server route, when its provider credentials are configured for the deployment. This is real audio from a real provider. - Choosing a voice per agent. - The call-outcome and transcript surfaces, as clearly labelled previews running on illustrative data. #### What does not work yet - Live inbound and outbound calling. This needs a telephony provider and a backend pairing contract that are not wired into the product. - Echo pairing, which is currently browser-local rather than a real device pairing. - Local voice-note recording, which is pending delivery support. > **Preview surfaces are labelled in the product too** > Every one of the above is marked as a preview where it appears, and none of them fabricates a result. If a preview surface ever shows you something that looks like a completed real call, that is a bug worth reporting rather than a feature that quietly shipped. #### Voice is priced separately Voice is an add-on with its own monthly charge and a bundle of included minutes, rather than something folded into every tier. The current figures are read from the live billing catalogue and shown on the pricing page; this page deliberately does not repeat them, because a price written into documentation is a price that goes stale without anybody noticing. > **Trivia** > The nine speech connectors in the catalogue and the seven voice ones are different categories on purpose. Speech is turning text into audio and audio into text; Voice is the telephony that carries it. Several vendors appear in one and not the other, and a couple appear in both under different keys. ### Worked examples Source: https://hawiagents.com/docs/work/exceptions Four operational exceptions end to end: a lost parcel, an oversell, a late supplier, a damaged item. Each of these follows one piece of work from arrival to settlement, naming which stage does what. They are the ordinary exceptions of a small commerce operation, which is what the product is shaped around. #### A parcel is scanned to the wrong postcode 1. **Intake.** The customer messages the marketplace asking where the order is. It becomes a board item with the source recorded and the order reference attached, unowned, in triage. 2. **Act.** The agent whose brief covers order exceptions picks it up, reads the tracking, and finds a scan against a postcode that is not the delivery address. 3. **Act.** It drafts the customer reply and opens a claim with the courier where the connection allows it. Both are actions; whether either goes out unattended is your routing configuration. 4. **Approve.** If you routed customer replies about delivery failures to a person, the draft waits with the tracking evidence beside it. Releasing sends it; holding leaves the item owned by you. 5. **Monitor.** The trace carries the tracking read, the claim, the draft and your decision, in order, with your name on the release. #### The same unit sells twice Two channels, one physical unit, and the stock sheet updated after both sales. Watch catches this as a reconciliation rather than as a stock alert, because the quantity is not wrong on either channel individually — they disagree with each other. - Watch compares the listing quantity against the stock sheet and raises the disagreement as an item, rather than reordering against either figure. - The agent does not decide which customer loses. That is routed to a person with both orders and their timestamps. - Once you decide, the correction is applied to whichever system was wrong, and the customer message goes through the same drafting and routing as any other. > **This is the case to configure routing for first** > An oversell is the exception where the fastest possible automatic response is also the worst one. Whatever else you let run unattended, this is worth sending to a person. #### A supplier is a week late 1. **Watch.** The purchase order passes its delivery date. A follow-up is scheduled rather than sent immediately, because one day late is noise. 2. **Act.** At three days the agent chases in the supplier's existing thread. At seven it chases again. 3. **Act.** The supplier replies with a new date. The agent puts it on the item and stops chasing — the brief told it to, and the stopping is the part that makes this useful rather than annoying. 4. **Watch.** Cover is recalculated against the new date. If the new date puts cover below the threshold, that is a new item, not a continuation of this one. #### An item arrives damaged The customer says it arrived broken and does not attach a photograph. The agent asks once, records the request against the item, and waits. If the photograph arrives it goes on the item as evidence; if it does not, the item ages and appears in the daily brief as waiting rather than as settled. The refund itself is money, so it is drafted with the evidence and the current order record beside the proposed change, and it goes wherever you routed refunds. Nothing about the agent's confidence changes that routing — it is a property of the action type and your configuration, not of how sure the agent was. ### The daily brief Source: https://hawiagents.com/docs/work/daily-brief What is in it, what is deliberately not, and the one number worth reading first. A short read covering what settled overnight, what stalled, and what is waiting on a person. It is designed to be finished in about ninety seconds, and everything in it links to the item behind it. #### Read the oldest waiting item first Not the settled count. The settled count is pleasant and tells you nothing you need to act on; the oldest waiting item tells you whether the approval queue is being read at all. A queue with fourteen hours in it is the single most common way an otherwise working setup stops delivering. #### What is in it | Line | Answers | | --- | --- | | Settled overnight, by agent | Did the routine work happen | | Runs that stopped themselves | Was a source unreachable, or a limit reached | | Runs that failed | Is something actually broken | | Waiting on a person, with the oldest | Is the queue being read | | New in triage | Is work arriving that no brief covers | #### What is deliberately not in it - Charts. A chart of yesterday is something you glance at rather than act on, and this is a page you act on. - Credit spend as a headline. It belongs on the account, where the authoritative figure lives, not in a summary that would make it look like the point of the morning. - Anything congratulatory. A brief that celebrates is a brief people stop reading. > **Trivia** > Stopped and failed are separate lines rather than one “problems” count. Merging them makes the brief unreadable within a fortnight, because stops are routine — a supplier's website times out, a rate limit is hit — and a count that mixes them stops meaning anything. ### Items in depth Source: https://hawiagents.com/docs/work/items Every field on a board item, where each one comes from, and what happens when two arrivals are the same thing. An item is one piece of work. Everything on a board is one, and every run is against one. The fields are few on purpose — an item that carried everything would be a database row rather than something a person can read at a glance. - **Source:** Where it came from, recorded at intake and never rewritten. Six weeks later this is what tells you whether a problem arrived by mail, by marketplace message, from a stock alert, from a call, or because somebody lifted it out of team conversation. - **Status:** Where it is in its life. See the status vocabulary; the words mean the same thing on the board, in the brief and in the trace. - **Owner:** A person or an agent. Unowned means triage — arrived, matched by no brief yet. - **Reference:** The external identifier where one exists: an order number, a purchase order, an invoice. What you would type into the other system. - **Evidence:** What has been gathered. Tracking reads, photographs a customer sent, the supplier's reply. This is what makes an approval a comparison rather than a description. - **History:** Every run, handoff and decision against this item, in order. #### When the same thing arrives twice A customer who messages on the marketplace and then emails about the same order has produced two arrivals and one problem. The reference is what ties them together: where both carry the same order number, the second attaches to the existing item rather than opening a new one. Where neither carries a reference — a message that says only “where is my stuff” — there is nothing to match on, and two items is the honest outcome. This is one of the strongest arguments for briefing an agent to ask for an order number rather than to infer one: the inference is what creates a wrong merge, and a wrong merge is much harder to notice than a duplicate. #### Aging Items carry how long they have been in their current state, and that is what the daily brief reports as the oldest waiting item. An item aging in triage is a briefing gap; aging in the approval queue is a reading gap; aging in working is usually a source that keeps timing out. ### Reading a trace Source: https://hawiagents.com/docs/work/traces What a trace contains, in what order, and the three things to look at first. The trace is the record of one run: what the agent read, which tools it called and what each returned, what it decided, what it handed off and to whom, what it cost, and how it ended. It is continuous across handoffs, so an item that passed through three agents reads as one sequence rather than three. #### Read it in this order 1. **The outcome, at the bottom.** Settled, handed off, waiting, stopped or failed. This tells you which kind of question you are asking. A stop is correct behaviour and a failure is not, and reading a week of stops as failures is the most common misdiagnosis there is. 2. **The tool calls, in the middle.** Not the agent's reasoning — what came back. Most surprising behaviour is a tool that returned less than expected, an empty list where there should have been three rows, a field the provider stopped sending. The agent then reasoned correctly from bad input. 3. **The inputs, at the top.** What the agent was given to start with. If the tool calls look right and the outcome still looks wrong, the question moves here: did it receive the item you think it received. #### What a handoff looks like inside a trace A handoff carries the item, the evidence gathered so far, the run history, and a reason written by the agent handing off. The reason reads slightly oddly — an agent explaining itself to a colleague — and it is the field support asks for first, which is why it has survived two attempts to remove it. #### Cost Each run records what it consumed. A run that retried twice was metered three times, and the trace shows all three attempts rather than only the one that worked. If an agent's spend looks higher than its output suggests, the retries are usually where it went. > **Secrets are not in the trace** > Connector secrets are redacted before the trace is stored, not before it is displayed. If you ever see something that looks like a credential in a trace, that is worth reporting immediately rather than assuming it is a display artefact. > **Trivia** > Run status is deliberately least-privilege: it reveals no provider name and no raw error text. A failure says a run failed and where, not which vendor returned which stack trace — because a raw provider error is a reliable way to leak infrastructure detail into a surface a customer can read. ### Team conversation Source: https://hawiagents.com/docs/work/collaborate The room for the people, why agents are not in it, and how a message becomes work. Workspace members talk in a persisted conversation inside the workspace. It sits after the approval gate in the product's own ordering, and that placement is deliberate: put earlier it reads as a chat feature, put after it reads as the room where a held decision actually gets made, which is what it is. #### Agents do not post here This is a boundary rather than an unfinished feature. A channel where a machine can speak is a channel people stop trusting for decisions, and the value of this room is that everything in it was said by a colleague. #### Turning a message into work Any message can be lifted onto a board when it needs an owner, a status or agent work. The item carries the conversation as its source, so the trace six weeks later still says the work started because somebody raised it at 11:20 in the operations channel. > **A refund asked for in chat becomes a held item, not a payment** > This is the thing people try on their first day, usually as a test, and the answer surprises them enough to be worth stating plainly. Lifting a message creates work; it does not dispatch it. ### What creates work Source: https://hawiagents.com/docs/work/what-arrives Every route by which an item can appear, and the threshold each one applies. Five routes, and each applies a threshold. A system that made an item for every arrival would be a worse inbox with more steps, so intake is deliberately selective. | Route | Creates an item when | Does not when | | --- | --- | --- | | Customer message | It carries an implied action — a question, a complaint, a request | It is an acknowledgement or a thank-you | | Stock alert | Cover crosses a threshold you set | Quantity changes without crossing one | | Supplier reply | It proposes something different from what was agreed | It confirms what you already have | | Scheduled check | A comparison finds a disagreement | Everything reconciles | | A person | They lift a message or create one directly | — | #### Webhooks versus polling Some providers push events; others are polled on the agent's interval. A pushed event arrives within seconds and is verified before anything reads it; a polled one arrives at the next interval. Neither is better in general — pushing is faster and depends on the provider being correct about what it sends, polling is slower and sees the true current state. > **An unverifiable pushed event is dropped** > Signature verification fails closed. A provider whose signing scheme is not implemented is refused rather than trusted, and an event outside the allowlist for that connector is ignored even when correctly signed. You will notice a missing integration before you notice a wrong one, which is the intended trade. ## Connections Available connectors, how one is authorised, and where secrets live. ### Connections Source: https://hawiagents.com/docs/connections How an external system is authorised once against your account and then selected by a workspace, and the four states a provider can be in. A connection is an authorised link to one external system. It is held against your account, and a workspace then selects it. That two-step exists so a second workspace can use a provider you have already authorised without the credential being copied into a second place — the workspace record stores the selection, never the secret. #### The four states, and why they are distinct Providers are not uniformly “connected”. They reach Hawi by four different routes with genuinely different properties, and the product keeps them apart rather than flattening them into one green tick. A provider that is visible is not described as connected until its own flow has confirmed it. | State | What it means | Who holds the secret | Example | | --- | --- | --- | --- | | Native OAuth | You authorise Hawi from inside the provider’s own consent screen. | Hawi, as a refreshable token. | A registry-approved OAuth provider | | Encrypted seller credential | You supply a credential through a secure setup flow; it is encrypted at rest and never displayed again. | Hawi, encrypted. | A registry-approved credential provider | | Verified connector | A connector definition that has been checked against the provider’s API before it is offered. | Varies by provider. | Only providers shown as available in the product | | External setup | Configured outside Hawi and pointed at it, typically for systems with no public authorisation flow. | You, in the external system. | A provider configured in its own administration surface | > **Read the scope before you add one** > Every connection shows the read and write scope it would grant before you add it to a workspace. That screen is the last cheap moment to notice that a connector wants write access to something you only wanted read from. Scopes are per connector, not per category, and two connectors in the same category routinely differ. #### Read and write A connection’s scope and an agent’s tool list are two different gates, and both apply. A workspace can hold a write-capable connection while every agent in it is restricted to reading through it. The narrower of the two wins, which means the safe way to introduce a new provider is to add it at the scope you eventually want and give the first agent read-only access to it. > **Availability is provider-specific** > A connector definition, an operator-configured provider, and a customer-connectable provider are different states. The public catalogue includes only the last of those; the signed-in product checks the live deployment before it offers a connection. ### The connector catalogue Source: https://hawiagents.com/docs/connections/catalogue Customer-connectable providers from the connector registry. This directory shows only providers the customer-facing registry currently marks connectable. A connector definition can exist internally without appearing here, and its presence in the codebase is not a claim that customers can connect it. > **This table is generated** > It is read from the customer-connectable projection of the connector registry. Disabled, internal, incomplete and operator-only providers are not promoted into this table. > **The live directory is authoritative** > Use the integrations directory for the current customer-connectable list. Documentation does not copy internal connector definitions into a second catalogue. #### Reading the categories Categories are an organising convenience, not a permission boundary. Nothing in the product grants access “to Commerce” — access is per connector, and two connectors in the same category can hold entirely different scopes. The category exists so that a person looking for their marketplace does not have to scroll every row. > **Trivia: why the number is what it is** > The number is derived from the eligible list rather than typed into documentation. Internal definitions and providers that still need operator or vendor work do not increase it. ### Custom connectors Source: https://hawiagents.com/docs/connections/custom Pointing Hawi at a system that is not in the catalogue, and how each operation is risk-classified. When a system is not in the public catalogue, a workspace may still have a separately configured custom route. Generic REST, webhook, external MCP and bring-your-own-key definitions exist in the internal catalogue, but they are not advertised as customer-connectable unless the live product offers their setup flow. - **generic_rest:** Describe the endpoints and Hawi calls them. The most common route for an in-house system. - **generic_webhook:** The external system calls Hawi when something happens. Use this when the source of truth pushes rather than being polled. - **external_mcp:** Point at an MCP server and its tools become available to agents in the workspace. - **user_byok:** A bring-your-own-key arrangement for a provider you already hold credentials with. #### Risk classification Every operation exposed by a custom connector is classified when the connector is scanned, into a risk level and an operation type of read or write. The classification is conservative in a specific way: an operation is only treated as a read when it is both marked read-only and uses a method that does not write. An endpoint declared read-only that turns out to POST is classified as a write, because the declaration is the part somebody can get wrong. > **A custom connector is your API surface** > A custom connector is checked against what you told it. Scope it as narrowly as the job needs, and give the first agent that uses it read-only access until you have read a week of traces. ### Connection security Source: https://hawiagents.com/docs/connections/security Where credentials live, what is never shown again, and what Hawi will not do with a secret. Provider credentials are held against your account and encrypted at rest. They are not copied into workspace records, are not readable from the browser, and are not returned by any API — including the developer API, which has no scope that could ask for one. #### What you can and cannot see - You can see that a connection exists, what it is for, and which workspaces have selected it. - You can see the read and write scope it grants, before and after adding it. - You can see a hint — enough characters to tell two credentials apart — and never the value. - You cannot retrieve a secret after supplying it. If you have lost it, replace it rather than recovering it. #### Redaction in traces Connector secrets are redacted from the run trace before it is stored, not before it is displayed. That ordering matters: a value redacted at display time is still in the record for anybody who reaches the record another way. > **Rotating a credential** > Rotation replaces the stored value and leaves the connection, its workspace selections and every agent tool list intact. Nothing needs rebriefing. Runs already in flight against the old credential are the only thing that can fail, so rotate at a quiet hour if the provider is one an agent polls continuously. > **Trivia** > The public site’s content security policy sets `img-src` to `'self'` only. It is unrelated to connections and it catches people out constantly: a component pasted in from elsewhere with images on a CDN renders broken locally while the image URL returns a perfectly good 200 in a terminal. The fix is to mirror the asset rather than to widen the policy. ### When a connection will not connect Source: https://hawiagents.com/docs/connections/troubleshooting The five things that break an authorisation, in the order they break. A connection fails in a small number of ways, and they look similar from the outside. This is the order to check them in. 1. **The redirect URL does not match, character for character.** The most common failure by a distance. A trailing slash, `www`, `http` instead of `https`, or a different path all count as different URLs. Providers reject the exchange with a message that says the URI is invalid and not which character is wrong. 2. **The account you authorised with cannot grant what was asked.** Some scopes need an administrator. The consent screen appears, the person clicks through, and the exchange fails or comes back with fewer scopes than requested. Authorise with an account that administers the organisation. 3. **The provider needs someone to approve the application first.** Several providers gate production access behind a review. Until it clears, the application often works for a small number of nominated test accounts and for nobody else — which reads as an intermittent fault rather than as a pending approval. 4. **The verification call failed even though authorisation succeeded.** Authorisation and verification are separate. A connection is not verified until one harmless read has come back. If authorisation succeeded and the connection is not verified, the token exists and does not have the access it needs. 5. **The workspace never selected the connection.** A provider is authorised against your account, and a workspace then selects it. Both steps are required. An agent that cannot see a system it was briefed on is usually looking at a workspace that has not selected the connection. > **A rotated credential does not rebrief anything** > Rotation replaces the stored value and leaves the connection, its workspace selections and every agent tool list intact. If a rotation appears to have broken something, look at runs that were in flight at the moment of the change rather than at the configuration. > **Listed is not connected** > The public catalogue lists only customer-connectable connectors. An internal definition is not a public listing; a connection is a provider that has also been authorised and verified for your account. If an offered connector will not complete its connection, report it rather than retrying indefinitely. ### Webhooks Source: https://hawiagents.com/docs/connections/webhooks How inbound provider events are verified, and why an unverifiable one is dropped. Some providers push events rather than waiting to be polled. Those arrive at a workspace-specific address, and every one is verified before anything reads it. #### The address carries the installation ```text https://hawiagents.com/api/integrations/webhooks/{connector}/{installation_id} ``` The installation identifier in the path ties an inbound event to one workspace connection. The request signature provides authentication. Keep the identifier private even though it carries no authentication authority. #### Verification fails closed - Signatures are checked against the shared secret before the body is parsed. - Where a provider signs with a timestamp, the timestamp is checked too, so a valid signature captured and replayed later is rejected. - A provider whose scheme is not implemented is refused rather than trusted. An unverifiable event is dropped, not accepted with a warning. - Events outside the allowlist for that connector are ignored even when correctly signed. > **Failing closed means you will notice a missing integration before a wrong one** > The alternative — accepting an event you cannot verify — turns a webhook endpoint into an unauthenticated way to write into somebody's workspace. Dropping it produces a support conversation; accepting it produces an incident. #### Registration Most connectors need the webhook registered by hand in the provider's console. A few can register it themselves once connected. The connector's own setup screen says which, and where it is manual it shows the exact address to paste. ### Scopes, read and write Source: https://hawiagents.com/docs/connections/scopes How access is decided, why a declared read can be classified as a write, and what to grant first. Every connection grants a scope, and every operation inside it is classified as a read or a write. Both matter, and they are decided in different places. #### The classification is conservative on purpose An operation counts as a read only when it is both declared read-only and uses a method that does not write. An endpoint someone declared read-only that turns out to POST is classified as a write, because the declaration is the part a human can get wrong and the method is not. | Declared | Method | Classified as | | --- | --- | --- | | Read-only | GET | Read | | Read-only | POST / PUT / PATCH / DELETE | **Write** — the declaration is not trusted over the method | | Write | Anything | Write | #### What to grant first 1. **Authorise at the scope you will eventually want.** Re-authorising later means going back through the provider's consent screen, and on some providers back through an approval. Widening once at the start is less disruptive than widening in week three. 2. **Give the first agent read access only.** The tool list is the narrower gate and it is per agent. A write-capable connection with a read-only agent behind it is a safe place to start. 3. **Read a week of traces before adding write.** You are looking for what the agent consults and how often, not for mistakes. Most surprises at this stage are about volume rather than judgement. > **Scopes differ within a category** > Nothing grants access to an entire category. Connectors are individual, and two in the same category routinely ask for very different things. The scope screen before you add one is the last cheap moment to notice. ### Setting up, by connection type Source: https://hawiagents.com/docs/connections/by-state The four routes a provider reaches Hawi by, and what each asks of you. Providers are not uniformly “connected”. They arrive by four routes with genuinely different properties, and what you have to do differs in each. #### Native OAuth 1. **Start the connection in Hawi.** You are sent to the provider's own consent screen. 2. **Authorise with an administrator account.** Some scopes cannot be granted by an ordinary member. Authorising with the wrong account is the second most common failure after a mismatched redirect URL. 3. **Come back and wait for verification.** Authorisation and verification are separate. The connection is not usable until one harmless read has come back. #### Encrypted credential 1. **Generate the credential in the provider's own settings.** Usually a key pair or a token, with a permission level you choose there. 2. **Paste it into the secure setup flow.** It is encrypted at rest and never displayed again. You will see a hint — enough to tell two apart — and never the value. 3. **Verification runs the same way.** One harmless read. If it fails, the credential exists and does not have the access the connector needs. #### Verified connector A connector definition checked against the provider's API before it is offered. From your side it behaves like one of the two above; the difference is on Hawi's side, in what was confirmed before the option appeared. #### External setup Configured in the external system and pointed at Hawi, typically where a provider has no public authorisation flow. You hold the configuration; Hawi holds nothing it could revoke, which is worth knowing when you come to disconnect. > **Disconnecting is not the same in all four** > Where Hawi holds a token it can revoke it. Where you supplied a credential, disconnecting drops the stored copy and the revocation is yours to do in the provider. The interface says which; it does not imply a revocation that did not happen. ### Commerce connections Source: https://hawiagents.com/docs/connections/commerce What is specific about shops and marketplaces, and the two questions to settle before connecting one. Commerce connections carry two properties nothing else in the catalogue does: they are the source of truth for money that has already moved, and they are usually not the only such source. Both change how you should set them up. #### Settle these two first - **Which system owns stock?:** If two channels both hold a quantity and neither is authoritative, an agent comparing them can only ever raise a disagreement — which is useful, and is not the same as being able to correct one. Decide which is the sheet and which is a listing. - **What is an order's identity?:** The reference an agent attaches to items. Where a marketplace order number and your internal number differ, pick one and be consistent, because that field is what merges two arrivals about the same problem. #### Per-shop rather than per-account Several commerce providers issue credentials scoped to a single shop rather than to a seller account. Two shops means two connections, which the connection model already supports — but it also means the shop is part of the connection's identity, and naming your connections after the shop rather than the platform saves confusion in month two. #### Marketplaces have approval queues Several marketplace providers review applications before granting production access, and the reviews are not quick. Where that is the case, the practical consequence is that the application should be submitted at the start of the work rather than when everything else is ready. > **Check the connector's current state before planning around it** > A connector being in the catalogue means Hawi has a definition for that provider. Whether it can complete a connection today is shown on its own setup screen, and that is the thing to check before building a process on top of it. ### External MCP servers Source: https://hawiagents.com/docs/connections/mcp Pointing an agent at tools you host, and where the trust boundary sits. One of the four custom-connector routes is an external MCP server. Point at one and its tools become available to agents in the workspace, which is the shortest path from an in-house system to something an agent can use. #### Where the trust boundary sits A catalogue connector was checked against its provider before being offered. An MCP server you point at was not — it is checked against what it tells Hawi about itself. Every operation it exposes is classified when the server is scanned, and the conservative rule applies: an operation is a read only when it is both declared read-only and uses a method that does not write. - Scope the server as narrowly as the job needs. It is your API surface, and a tool you expose is a tool an agent can reach. - Give the first agent read-only access to it until you have read a week of traces. - Ambiguous operations are classified conservatively as approval-gated writes rather than as reads. #### Hawi's own MCP server Separately, Hawi publishes an MCP server so that an MCP-compatible product can work with a Hawi workspace from the outside. Its read tools cover agents, approvals, calls, service health and analytics. Its small write set previews every change and does nothing until it is called again with an explicit confirmation. > **It says so when it is not configured** > Without a backend address and a token, every tool on that server returns a plain “not configured” message naming the two settings it needs. It does not return placeholder data, and a tool that answered with invented figures would be worse than one that refuses. ## Billing Credits, plans and seats. ### Credits Source: https://hawiagents.com/docs/billing/credits The unit of metered work, what consumes it, and why no number on this page is a charge. Credits are the unit of metered work. Model calls, tool calls and voice minutes consume them. A plan grants a monthly allowance, balances are held against your account rather than a workspace, and an agent’s spending ceiling is expressed against the same unit. #### What the charge is calculated from The authoritative figure is calculated server-side at the rate version live when the request starts. Not when it finishes, and not from anything displayed in the interface beforehand. That ordering means a long-running job is charged at the rate it began under, and it means the indicative figures shown in the model picker are comparisons rather than quotes. > **Anything you read as a credit figure outside your account is indicative** > The model table in these docs, the hints in the agent builder, and any arithmetic you do from them are all for choosing between options. Your account’s own usage is the only place a real number lives. #### What consumes credits | Activity | Roughly proportional to | | --- | --- | | A model call | Input and output tokens, multiplied by the model’s rate. The spread across the six models is roughly nine to one. | | A tool call | The call itself, not the size of what it returns. | | A voice minute | Wall-clock minutes, against the add-on’s included bundle first. | | A retry | The same as the attempt it retries. A run that failed twice was metered twice. | > **Cost-indexed rather than gated** > Expensive models are not withheld from cheaper plans. A request against the highest-capability model simply consumes more credits than one against the most efficient. What matters is knowing that before you pick, which is what the tier column in the model table is for. > **Trivia** > The credit figures in the model picker are quoted for 1,000 input and 500 output tokens. The 2:1 ratio is not arbitrary — it is roughly the shape of an operational request, where the agent reads a thread and writes a short decision. A coding workload would invert it and the comparison would come out differently. ### Plans and seats Source: https://hawiagents.com/docs/billing/plans What a plan row carries, why no figure is written down here, and how trials and annual pricing behave. A plan carries a monthly credit allowance, a maximum number of agents, a queue priority, a minimum seat count where one applies, and a set of entitlements. Prices are per seat. Every one of those figures is read from the live catalogue at request time, so the pricing page is the only correct place to read them. > **Why this page has no numbers on it** > The catalogue the pricing page reads is the same one the wallet is granted from. A constant written here would be a second source of truth, and it would drift the first time finance changed a number without anybody touching the application. Documentation that is confidently out of date about money is worse than documentation that sends you one click away. #### What a plan row contains - **Monthly credits:** The allowance granted each period. - **Maximum agents:** How many agents the workspace may hold. - **Queue priority:** One of low, standard, fast track or high priority. It governs how runs are scheduled under load, not how fast a model responds. - **Minimum seats:** Where a plan has one. Business plans generally do; individual plans generally do not. - **VAT treatment:** Whether the published figure includes or excludes VAT. Shown on the pricing page beside the figure, never inferred. - **Entitlements:** The feature flags the plan carries. Resolved server-side from account entitlements and membership. #### Trials A plan advertises a free trial only when a real trial length exists behind it in the catalogue. A missing, negative or fractional value reads as no trial rather than as a guess, because every wrong answer here is visible to a buyer as a promise about when they will be charged. #### Annual pricing Where an annual interval is offered, it is quoted per seat per month alongside the monthly figure, not only as a yearly total. Buyers compare the two on the monthly number; quoting only the annual total makes the cheaper option look like the expensive one. A plan with no configured annual price simply does not offer the interval, rather than showing an empty toggle. > **The beta is not free** > Beta testers pay. The one-year term that appears in the beta programme is a term, not a price, and it has been misread as one before. If you are joining the beta, read the pricing page for what you will be charged. ### Voice billing Source: https://hawiagents.com/docs/billing/voice Why voice is an add-on rather than a tier feature, and how minutes are counted. Voice is priced as a monthly add-on with a bundle of included minutes, rather than folded into every plan. The current figures are read from the live billing catalogue and shown on the pricing page; this page does not repeat them, because a price written into documentation goes stale without anybody noticing. #### Why an add-on Voice carries a per-minute cost to a telephony provider that has no relationship to how many agents or seats a workspace has. Folding it into every tier would mean every customer paying for capacity most of them never use, and the ones who do use it paying the same as the ones who do not. #### How minutes are counted - Wall-clock minutes of connected call time, against the included bundle first. - A call that ends because funding ran out is settled as partially completed rather than as failed. The work that happened is recorded, and so is where it stopped. - A transcript is saved before settlement, so a failure to settle does not lose the record of what was said. - Speech generation outside a call is metered as ordinary credit use, not as voice minutes. > **Much of voice is not connected yet** > Speech generation is real where its credentials are configured. Live inbound and outbound calling needs a telephony provider and a backend pairing contract that are not wired into the product, and Echo pairing is currently browser-local. See the voice page for the exact division. Nothing bills for a capability that is not connected. ### Reading your usage Source: https://hawiagents.com/docs/billing/usage Where the authoritative figure lives, what the run lifecycle meters, and how to forecast. Your account is the only place a real number lives. Everything else — the model picker's indicative figures, the tables in this documentation, arithmetic you do from either — exists to help you choose between options before you commit. #### The lifecycle a metered run goes through 1. **Reserve.** Headroom is set aside before the work starts, against the rate version live at that moment. A run cannot begin without it. 2. **Authorise.** The reservation is checked against entitlements. A workspace without the entitlement does not reach a provider at all. 3. **Execute.** The work happens. Provider calls are made here and nowhere earlier. 4. **Meter.** What was actually consumed is recorded, which is usually less than was reserved. 5. **Settle.** The reservation is released and the real charge applied. > **A run that fails halfway is settled as partial, not as free** > If a provider failed after billable work had happened, the usage that occurred is recovered and settled. If there is no recoverable usage, the reservation settles at its ceiling rather than at zero. Both are deliberate: work that cost money is charged for, and a failure is not a way to get work for nothing. #### Forecasting - Take one agent's first full week and multiply. The first week is usually the most expensive per item, because briefs are being corrected and runs are retrying. - Retries are the usual surprise. A run that failed twice was metered three times, and the trace shows all three. - Model choice dominates everything else. The spread across the six models is roughly nine to one for the same request. - Interval dominates volume. A one-minute loop is sixty times an hourly one for information that changes twice a day. ### Running out, and auto-recharge Source: https://hawiagents.com/docs/billing/running-out What stops, what finishes, and the three outcomes an automatic top-up can have. Metered work stops when there is nothing left to reserve against. It stops at the reservation, which is before a provider is called — so running out costs you the work you did not do, not a partial charge for work half done. #### What happens to work in flight - A run that has already reserved finishes inside its reservation. - A voice call whose funding stops is settled as partially completed rather than as failed, and the transcript is saved before settlement — so a failure to settle does not lose the record of what was said. - New runs do not start. They are not queued indefinitely either; the daily brief shows them as stopped. #### Auto-recharge Where it is configured, a top-up is attempted automatically. It is atomic and grants exactly once after payment succeeds, so a retry cannot double-grant. It has exactly three outcomes. | Outcome | Means | What to do | | --- | --- | --- | | Not attempted | A precondition was not met — no verified payment method, a limit reached, or it is switched off. A reason is recorded. | Read the reason. It names the precondition. | | Attempted and succeeded | Payment took, credits granted once, with a payment reference. | Nothing. | | Attempted and failed | The charge did not succeed, with a failure code. | The failure code is a payment problem, not a Hawi one. Check the card. | > **Auto-recharge is not a spending limit** > It refills a balance; it does not cap what agents do with it. The per-agent spending ceiling is the control that limits spend, and turning on auto-recharge without reviewing ceilings widens what can happen unattended rather than narrowing it. ### Seats, teams and shared credit Source: https://hawiagents.com/docs/billing/seats-and-teams What a seat buys, why balances are account-scoped, and how larger arrangements differ. Prices are per seat, and a seat is a person rather than an agent. Adding agents does not add seats; adding colleagues does. A plan's maximum-agents figure is the separate limit on how many agents a workspace may hold. #### Balances follow the account, not the workspace Your credit balance is account-scoped. Switching workspaces does not switch balance, and a workspace you opened to experiment in draws on the same balance as the one answering real customers. That is why a sandbox workspace still needs sensible ceilings. #### Minimum seats Some plans carry a minimum seat count and some do not — business plans generally do, individual plans generally do not. Where one applies it is shown on the pricing page beside the figure, because a per-seat price with an unstated minimum is a misleading price. #### Larger arrangements Enterprise credit can be shared across a billing hierarchy, which is what lets several teams draw on one arrangement while keeping their workspaces isolated from each other. The isolation is unchanged by the sharing: workspaces still see nothing of one another, and the sharing is about where the credit comes from rather than what anybody can read. > **Queue priority is part of the plan, not an add-on** > Low, standard, fast track or high priority. It governs how your runs are scheduled against everyone else's under load. It is not a measure of model speed and it does not change an agent's interval. ## Developer API Three read-only endpoints and the keys that reach them. ### The developer API Source: https://hawiagents.com/docs/api Three read-only endpoints, two scopes, bearer authentication, and keys you issue and rotate yourself. The public API is small and read-only on purpose. It is not a second interface onto the whole product; it exists so that a workspace and its file listing can be read by something you build. Every endpoint is under `/api/v1`, and every request carries a bearer token. > **Read-only means read-only** > There are exactly 6 scopes and both are reads. There is no scope that creates an agent, releases an approval, or moves money, and there is no undocumented one — the scope list on this page is imported from the same constant the server validates against. #### Base URL ```text https://hawiagents.com/api/v1 ``` > **The API stays on the apex** > Moving the documentation to its own subdomain does not move the API. `docs.hawiagents.com/api/...` is not an API address, and the host routing deliberately excludes `/api` on both hosts so that it never becomes one by accident. #### The endpoints | Method | Path | Scope required | | --- | --- | --- | | GET | `/api/v1/auth` | None beyond a valid key. Reports what the key can do. | | GET | `/api/v1/workspaces/{workspaceId}` | `workspace:read` | | GET | `/api/v1/workspaces/{workspaceId}/files` | `files:read` | #### Scopes | Scope | Grants | Used by | | --- | --- | --- | | `workspace:read` | Read the workspace this key belongs to. | `GET /api/v1/workspaces/{workspaceId}` | | `files:read` | List file metadata for that workspace. | `GET /api/v1/workspaces/{workspaceId}/files` | #### One key, one workspace A key is issued against a single workspace and is bound to it. Passing any other workspace identifier returns `404`, whether or not that workspace exists. There is no key that spans workspaces; if you need to read two, issue two keys. > **Trivia** > There are two things in this codebase that could reasonably be called “the API”. `/api/v1` is this one. `/api/developer-platform` is the OAuth application surface that installed apps authenticate against, and it has a completely different error envelope and rate-limit model. If a response you are looking at does not match this page, check which one you called. ### Authentication Source: https://hawiagents.com/docs/api/authentication Key format, the one moment a secret is visible, expiry options, and rotation. Every request carries a bearer token in the `Authorization` header. A request with no header, or a header that does not begin with `Bearer `, is rejected as `401` before any lookup happens — the same response an expired key gets, and deliberately so. _A minimal authenticated request_ ```bash curl https://hawiagents.com/api/v1/auth \ -H "Authorization: Bearer hawi_sk_XXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXX" ``` #### What /auth returns Call it first when something is not working. It answers the question “is this key valid, and what is it allowed to do” without touching any data. ```json { "authenticated": true, "keyId": "…", "workspaceId": "…", "scopes": ["files:read", "workspace:read"], "expiresAt": "…", "totalRequests": 1284 } ``` - **keyId:** The key's identifier. Safe to log; it is not the secret. - **workspaceId:** The one workspace this key can read. Any other id returns 404. - **scopes:** Sorted, de-duplicated, and exactly what was granted at issue. - **expiresAt:** When the key stops working. There is no non-expiring key. - **totalRequests:** Lifetime request count for this key. Useful for spotting a key that is being used somewhere you forgot about. #### Key format Keys are issued as `hawi_sk__`. The public id identifies the key so it can be looked up, rate-limited and revoked; the secret is the part that proves you hold it. > **The secret is shown once** > At creation, and never again. Afterwards the product shows a hint — the first characters of the public id and the last few of the secret — which is enough to tell two keys apart in a list and useless to anybody who obtains it. If you lose a key, rotate it. There is no recovery path and the absence of one is the point. #### Expiry A key is issued with an expiry chosen from 7, 30, 90, 365 days. Ninety is the default and is the right answer for most integrations. | Expiry | Suits | | --- | --- | | 7 days | A one-off script, a migration, something you are debugging. | | 30 days | A contractor, a trial integration, anything you expect to revisit. | | 90 days | The default. A running integration with an owner who will notice the rotation. | | 365 days | A long-lived internal service. Set a calendar reminder at eleven months, because nothing else will. | #### Rotation Rotating issues a new secret against the same key with a fresh expiry. Rotate on a schedule, when somebody with access leaves, and immediately if a key has appeared anywhere it should not — a log, a screenshot, a repository, a support ticket. > **Trivia** > `sk` is the industry convention for “secret key”, and it is in the prefix so that automated secret scanners recognise the string in a commit. A key that leaks into a public repository is far more likely to be caught by a scanner matching the prefix than by anybody reading the diff. ### Read a workspace Source: https://hawiagents.com/docs/api/workspaces GET /api/v1/workspaces/{workspaceId} — the fields it returns and the two ways it 404s. ```http GET /api/v1/workspaces/{workspaceId} ``` Requires `workspace:read`. Returns the workspace the key is bound to. The identifier must be a valid UUID and must match the key's own workspace; anything else is a `404`. _200_ ```json { "workspace": { "id": "…", "name": "…", "createdAt": "…" } } ``` #### Three fields, and why not more Identifier, name, creation time. Member lists, connection lists, agent counts and billing state are all deliberately absent: each would widen a read-only key into something that discloses who works at a company, what systems they run, and what they spend. If the API grows, it grows by adding a scope, not by widening this response. #### When it returns 404 - The identifier is not a valid UUID. - The identifier is a valid UUID for a workspace that does not exist. - The identifier is a valid UUID for a workspace that exists but is not this key's workspace. > **All three are the same response on purpose** > Distinguishing them would let anybody holding one valid key discover which workspace identifiers exist by trying them. The cost of collapsing them is a slightly less helpful error; the cost of separating them is an enumeration oracle. ### List workspace files Source: https://hawiagents.com/docs/api/files GET /api/v1/workspaces/{workspaceId}/files — metadata only, paginated, never file content. ```http GET /api/v1/workspaces/{workspaceId}/files?limit=50&cursor=… ``` Requires `files:read`. Returns file metadata for the key's workspace, newest first. It does not return file content and there is no scope that does — this endpoint tells you what exists, not what is in it. _200_ ```json { "files": [ { "id": "…", "name": "supplier-invoice-2210.pdf", "contentType": "application/pdf", "size": 184320, "validationStatus": "…", "createdAt": "…" } ], "hasMore": true, "nextCursor": "eyJvZmZzZXQiOiI1MCJ9" } ``` - **name:** The original filename, normalised. Control characters and bidirectional-override characters are stripped when the file is stored, so a filename cannot be used to disguise its extension in a listing. - **size:** Bytes. - **validationStatus:** What the upload checks concluded. Files are verified by signature rather than by extension, so a renamed executable is rejected at upload rather than listed here as a document. - **hasMore:** Whether another page exists. Read this rather than comparing the array length against your limit. - **nextCursor:** Opaque. Pass it back verbatim. `null` when there is nothing more. #### Ordering Newest first, by creation time and then by identifier. The second key matters: without it two files created in the same instant could swap places between pages and one of them would never be returned. ### Pagination Source: https://hawiagents.com/docs/api/pagination Cursors, the default and maximum page size, and what an invalid cursor does. Listing endpoints are cursor-paginated. You ask for a page size, read `nextCursor` off the response, and pass it back on the next request until `hasMore` is false. | Parameter | Default | Maximum | Notes | | --- | --- | --- | --- | | `limit` | 50 | 100 | A value above the maximum is clamped rather than rejected. A value below 1, or one that is not a whole number, falls back to the default. | | `cursor` | — | — | Opaque. Pass back exactly what you were given. | _Walking every page_ ```bash cursor="" while : ; do page=$(curl -s -H "Authorization: Bearer $HAWI_KEY" \ "https://hawiagents.com/api/v1/workspaces/$WS/files?limit=100${cursor:+&cursor=$cursor}") echo "$page" | jq -r '.files[].name' [ "$(echo "$page" | jq -r '.hasMore')" = "true" ] || break cursor=$(echo "$page" | jq -r '.nextCursor') done ``` > **Do not construct a cursor** > It is a base64url-encoded structure and its contents are an implementation detail that is allowed to change. A cursor you build by hand may work today and stop working without a version bump, because it was never part of the contract. A cursor that does not decode returns `400` with `{"error": "Invalid page cursor."}`. #### Pages are a snapshot of nothing There is no transaction spanning your pagination. A file uploaded while you are on page three can appear on a later page, and one deleted can vanish from a page you were about to request. For a listing that changes slowly this is invisible; for anything you intend to reconcile against, record the time you started and treat the result as approximate. ### Rate limits Source: https://hawiagents.com/docs/api/rate-limits Two stages — one by network origin, one by key — the headers they set, and how to back off. Every `/api/v1` request passes two limiters in order. The first counts by network origin and runs before authentication, so an unauthenticated flood is stopped without a database lookup. The second counts by key, per endpoint, and runs after the key has been verified. | Stage | Counted against | Limit | Window | | --- | --- | --- | --- | | Network | The calling origin, before authentication | 600 requests | 60 seconds | | Per key — `/auth` | Your key | 300 requests | 60 seconds | | Per key — workspace read | Your key | 300 requests | 60 seconds | | Per key — file listing | Your key | 300 requests | 60 seconds | > **The three per-key limits are separate budgets** > Exhausting the file listing does not stop you reading the workspace. They are counted under different scopes, so a busy listing loop cannot starve a health check. #### Headers | Header | When | Meaning | | --- | --- | --- | | `RateLimit-Limit` | Whenever the limiter is enforcing | The ceiling for the window. | | `RateLimit-Remaining` | Whenever the limiter is enforcing | What is left in this window. | | `Retry-After` | On a 429 | Seconds to wait. At least 1. | #### Backing off - Honour `Retry-After` when it is present. It is computed from the window, not guessed. - Otherwise back off exponentially with jitter. A fixed interval across several clients reconverges into the same spike that caused the limit. - Do not retry inside a request somebody is waiting on. Queue it. - If you are polling, poll less. Six hundred reads a minute is a great deal of polling for data that changes hourly. > **A 503 with Retry-After: 5 is not a rate limit** > In production, if the distributed limiter itself is unavailable, requests are refused with `503` and `{"error": "This service is temporarily unavailable."}` rather than being let through unmetered. It fails closed. Treat it as a short outage and retry; it is not something your traffic caused. ### Errors Source: https://hawiagents.com/docs/api/errors The error shape, every status the API returns, and the header that tells you which of two 401s you hit. Errors are a flat object with a human-readable `error`, and a machine-readable `code` on the two authentication failures. Every error response is `Cache-Control: no-store`. _401_ ```json { "error": "A valid Hawi API key is required.", "code": "invalid_api_key" } ``` | Status | `code` | Means | | --- | --- | --- | | 401 | `invalid_api_key` | No `Authorization` header, a header not starting with `Bearer `, or a key that is unknown, expired or rotated. | | 403 | `insufficient_scope` | The key is valid but was not issued with the scope this endpoint requires. Rotation does not fix this; a new key with the right scopes does. | | 400 | — | `{"error": "Invalid page cursor."}` — a cursor that does not decode. | | 404 | — | `{"error": "Workspace not found."}` — not a UUID, not a real workspace, or not this key's workspace. All three are the same response. | | 429 | — | `{"error": "Too many requests. Please wait and try again."}` with `Retry-After`. | | 503 | — | Either load protection is unavailable, or a listing could not be loaded. Retry with backoff. | #### The WWW-Authenticate header Both authentication failures set it, and it is the fastest way to tell them apart from a client that only logs status codes. ```http 401 WWW-Authenticate: Bearer realm="hawi", error="invalid_token" 403 WWW-Authenticate: Bearer realm="hawi", error="insufficient_scope" ``` > **401 or 403 tells you which thing to fix** > A `401` is about the key itself — wrong, absent, expired. A `403` is about what the key was allowed to do when it was issued. Retrying helps neither, and issuing a fresh key only helps the second if you change the scopes. #### What to send support - The endpoint and the method. - The status and the `code` if there was one. - The `keyId` from `/api/v1/auth` — never the key itself. - The approximate time, with a timezone. ### Your first API request Source: https://hawiagents.com/docs/api/quickstart From nothing to a verified key and a real response, in about five minutes. 1. **Issue a key.** In the developer console, against the workspace you want to read. Choose the scopes you need and an expiry; ninety days is the default and the right answer for most integrations. 2. **Copy the secret now.** It is shown once. Afterwards you get a hint, which is enough to tell two keys apart and useless for anything else. 3. **Confirm it works before writing any code.** One request to `/auth` tells you the key is valid, which workspace it is bound to, and what it may do. _Confirm the key_ ```bash export HAWI_KEY="hawi_sk_…" curl -s https://hawiagents.com/api/v1/auth \ -H "Authorization: Bearer $HAWI_KEY" | jq ``` _Read the workspace it is bound to_ ```bash WS=$(curl -s https://hawiagents.com/api/v1/auth \ -H "Authorization: Bearer $HAWI_KEY" | jq -r .workspaceId) curl -s "https://hawiagents.com/api/v1/workspaces/$WS" \ -H "Authorization: Bearer $HAWI_KEY" | jq ``` _The same thing, from Node_ ```javascript const KEY = process.env.HAWI_KEY; const base = "https://hawiagents.com/api/v1"; async function get(path) { const res = await fetch(base + path, { headers: { Authorization: `Bearer ${KEY}` }, }); if (!res.ok) { const body = await res.json().catch(() => ({})); throw new Error(`${res.status} ${body.code ?? ""} ${body.error ?? ""}`.trim()); } return res.json(); } const { workspaceId } = await get("/auth"); const { files } = await get(`/workspaces/${workspaceId}/files?limit=25`); console.log(files.map((f) => f.name)); ``` > **Take the workspace id from /auth** > A key is bound to one workspace, and `/auth` tells you which. Hard-coding an identifier means an integration that breaks silently with a 404 when the key is reissued against a different workspace. ### Writing a client Source: https://hawiagents.com/docs/api/clients Retries, backoff, pagination and the four failures worth handling separately. The API is small enough that a client is a hundred lines. Most of the work is in handling the four failures differently, because retrying the wrong one wastes time and retrying another makes things worse. | Status | Retry? | Because | | --- | --- | --- | | 401 | No | The key is wrong, absent or expired. Retrying sends the same wrong key. | | 403 | No | The key lacks a scope. Only a new key with different scopes fixes it. | | 404 | No | Not this key's workspace. Retrying will not change whose workspace it is. | | 429 | Yes, after `Retry-After` | A limit, not a fault. The header tells you how long. | | 503 | Yes, with backoff | Load protection or a transient read failure. Not caused by your traffic. | #### Backoff - Honour `Retry-After` when present; it is computed from the window rather than guessed. - Otherwise exponential with jitter. A fixed interval across several clients reconverges into the spike that caused the limit. - Cap the total attempts. A client that retries forever turns a five-minute provider blip into an outage of its own making. - Never retry inside a request a person is waiting on. Queue it and answer. #### Pagination Read `hasMore` rather than comparing the array length against your limit, and pass `nextCursor` back verbatim. Do not construct a cursor: it is opaque, its contents are an implementation detail, and one you build by hand can stop working without a version bump because it was never part of the contract. #### Keys in a client - Read the key from the environment. Never from a file in the repository, and never as a default argument. - Log the `keyId` from `/auth`, never the key. - Set a rotation reminder shorter than the expiry. Nothing warns you. - One key per integration. A shared key means a rotation takes down everything at once and you cannot tell which caller hit a limit. ### Handling keys safely Source: https://hawiagents.com/docs/api/security What a leaked key can and cannot do, and what to do in the first ten minutes. #### What a leaked key can do Read the one workspace it is bound to, at the scopes it was issued with, until it expires. That is the whole blast radius, and it is small by construction: there is no write scope, no scope that returns a provider credential, and no key that spans workspaces. #### What it cannot do - Create, change or delete anything. Both scopes are reads. - Read another workspace. Any other identifier returns 404 rather than data. - Retrieve a provider credential. No scope exposes one and no endpoint returns one. - Read file contents. The file endpoint returns metadata only. #### The first ten minutes 1. **Rotate it.** This is the whole remedy and it takes seconds. A rotated key's old secret stops working immediately. 2. **Check totalRequests.** `/auth` reports the key's lifetime request count. A number far above what your integration should have made tells you it was used. 3. **Work out where it went.** A log, a screenshot, a repository, a support ticket, a shared password manager entry. The route matters more than the key, because the route will happen again. 4. **Shorten the expiry on the replacement.** If a key leaked once, thirty days is a better default than ninety until you have fixed the route. > **The prefix is there to help scanners** > `hawi_sk_` follows the industry convention for a secret key so that automated secret scanning recognises it in a commit. A key that leaks into a public repository is far more likely to be caught by a scanner matching the prefix than by anybody reading the diff. ## Interface Settings, accessibility and the keyboard. ### Interface settings Source: https://hawiagents.com/docs/interface/settings Theme, density, text size, motion, and how much of the machinery you want to see. The signed-in product carries real interface settings rather than a theme toggle and a shrug. They apply immediately, persist per browser, and several of them are accessibility features rather than aesthetics. | Setting | Values | What it changes | | --- | --- | --- | | Theme | Light, dark, system | The whole console. Applied without a flash on load. | | Density | Compact through comfortable | Scales the spacing unit application-wide, so every padding, gap and row moves together. | | Text size | Default, large | Base text size. Everything is sized relative to it, so it scales rather than overflowing. | | Interface mode | No-code, low-code, dev | How much technical detail is shown: as intended, agents’ working visible, or extra backend detail. | | Agent avatars | On, off | Whether agents are shown with a mark beside their name. | | Notification style | Several | How arrivals are announced. | | Agent active hours | Preset or custom | When agents work, with a custom cadence in minutes. | > **The public site does not follow the theme setting** > The marketing site and these documentation pages are permanently dark by design, and the theme control governs the signed-in console only. This is not an oversight and there is no hidden preference that changes it. > **Trivia** > Settings are stored in the browser and read back without any check that the browser has not edited them, which is exactly why nothing security-relevant is kept there. Two fields that were — a role defaulting to administrator, and a two-factor flag — were removed unread. Roles are resolved server-side on every request. ### Accessibility Source: https://hawiagents.com/docs/interface/accessibility The four controls that are first class, the contrast floor, and what is not claimed. Four accessibility controls ship in the product, are user-controllable, and are treated as first class — meaning future work is not permitted to regress them. - **High contrast:** Stronger text and border contrast throughout. - **Reduce transparency:** Opaque surfaces, with no blur behind bars and panels. - **Reduce motion:** Transitions drop to an opacity step and decorative animation stops on a static frame. The operating system’s own preference is honoured as well as the in-product one. - **Always show focus:** Keyboard focus outlines stay visible at all times rather than only after keyboard interaction. #### Contrast floor Body and placeholder text are held at a minimum of 4.5:1 against their background, and large text at 3:1. A one-pixel rule is never the only thing carrying a meaning; it is paired with a label, a weight change, or a background step. #### Motion Every result the product produces arrives with motion reduced, rather than being absent. That distinction is the whole rule: an animation may be how something arrives, and may never be whether it arrives. Interactive surfaces are completable by keyboard alone, and a change of state is announced rather than being carried only by the animation that accompanied it. > **What is not claimed here** > No external conformance standard has been confirmed for this product, so none is named on this page. The controls above are real and the contrast floor is enforced; a formal audit against a published standard is a different thing and has not been done. If you need one for procurement, ask rather than reading one into this page. ### Keyboard Source: https://hawiagents.com/docs/interface/keyboard The command menu, and how it is opened from anywhere. The command menu opens with ⌘K on macOS and Ctrl+K elsewhere, from anywhere in the console. It is a centred palette over a dimmed page with a single input: arrow keys move through the results and wrap at both ends, Enter runs the selection, Escape closes. | Key | Does | | --- | --- | | ⌘K / Ctrl+K | Open the command menu from anywhere. | | ↑ / ↓ | Move through results. Wraps at both ends. | | Enter | Run the highlighted result. | | Escape | Close. | > **On these documentation pages** > ⌘K opens the ask box instead, which searches these pages. Same key, same expectation, different corpus. > **Trivia** > An earlier attempt at the command menu had the sidebar trigger re-dispatch a synthetic ⌘K keyboard event on the window, on the theory that this would be tidier than a shared handle. It silently did nothing at all: synthetic key events do not drive another component’s listener in the way that intuition suggests. Cross-tree signalling in this codebase goes through an explicit function, and the episode is the reason there is a comment about it. ### Notifications Source: https://hawiagents.com/docs/interface/notifications The three styles, when agents work, and the custom cadence range. #### Style | Style | Behaviour | Suits | | --- | --- | --- | | Toast | A brief transient message | Working in the product with other things happening | | Banner | Persists until acknowledged | Anything you must not miss — the approval queue, for instance | | Silent | Nothing appears; the record still updates | Reading the daily brief and nothing else | > **Silent does not mean nothing is happening** > It suppresses the announcement, not the work. If you set it, the daily brief becomes the only thing telling you the approval queue has something in it — which is fine as long as somebody reads it. #### When agents work Three settings: always, a daily window, or a custom cadence. The custom range runs from every minute to once a week. | Cadence | Reasonable for | | --- | --- | | Every minute | Inbound customer messages, where latency is noticeable | | Every 5 minutes | Inbound customer messages, where latency is noticeable | | Every 15 minutes | Most order and inbox work | | Every 30 minutes | Most order and inbox work | | Every hour | Most order and inbox work | | Every 1.5 hours | Stock, suppliers, reconciliation | | Every 3 hours | Stock, suppliers, reconciliation | | Every 6 hours | Stock, suppliers, reconciliation | | Every 12 hours | Stock, suppliers, reconciliation | | Once a day | Reporting and weekly checks | | Once a week | Reporting and weekly checks | > **Slower is usually better than you expect** > A one-minute cadence against a supplier's website is sixty times the requests of an hourly one for information that changes twice a day. It costs credits, it is more likely to hit the provider's own rate limit, and a throttled run is recorded as stopped — which makes the brief harder to read for no benefit. ### How much you want to see Source: https://hawiagents.com/docs/interface/modes No-code, low-code and dev, and which one to pick in the first week. One setting decides how much of the machinery the product shows you. It changes what is displayed, not what happens. - **No-code:** The product as intended. Boards, briefs, approvals and the daily brief, without the internals. - **Low-code:** You see agents working — the tool calls as they happen, rather than only the result. This is the useful one in the first week, because it teaches you what a trace will contain before you go looking for one. - **Dev:** Extra backend detail. Identifiers, raw shapes, the things you would quote in a support conversation. > **Start in low-code, then go back** > Most people set up in no-code, get confused by something in week one, and never discover that low-code would have shown them the answer. Start there, and drop back to no-code once agent behaviour has stopped surprising you. #### The other display settings | Setting | Values | Changes | | --- | --- | --- | | Density | Compact, default, roomy | Scales the spacing unit application-wide, so every padding, gap and row moves together rather than only some of them | | Text size | Default, large | The base size everything else is relative to, so it scales rather than overflowing | | Agent avatars | On, off | Whether agents appear with a mark beside their name | | Agent loading style | Book, minimal | How an agent's working is presented while it runs | | Theme | Light, dark, system | The signed-in console only. The public site and these pages are permanently dark. | ### Files Source: https://hawiagents.com/docs/interface/files What a workspace accepts, how a file is checked, and why the filename is rewritten. Files attached to a workspace are stored privately and reached through signed URLs rather than public addresses. Every upload is checked before it is stored, and the checks are stricter than they look. #### Type is decided by signature, not extension A file's type comes from its content, not its name. A renamed executable is rejected rather than stored as a document, and an archive or executable is refused regardless of what it claims to be. #### What is rejected - Extension spoofing — the signature and the extension disagreeing. - Archives and executables. - Empty files. - Text that is not valid UTF-8, or that contains NUL bytes. - JSON that does not parse. - Anything over the size limit. #### Filenames are rewritten Only the basename is kept, and control characters and bidirectional-override characters are stripped from it. Those characters are how a filename is made to display in reverse — the trick that shows a file ending in `.txt` when it ends in something else — and removing them at storage time means no listing anywhere can be fooled by one. > **The API lists files but never returns one** > `files:read` returns metadata: name, type, size, validation status and creation time. There is no scope that returns content, and adding one would be a new scope rather than a widening of this one. ## Reference Vocabulary, glossary, and getting help. ### Status vocabulary Source: https://hawiagents.com/docs/reference/status-vocabulary Every status and outcome word the product uses, and exactly what each one commits to. The same words appear on boards, in the daily brief and in traces, and they mean the same thing in all three. Where two words look interchangeable in ordinary English they are kept apart here on purpose. | Word | Where it appears | Commits to | | --- | --- | --- | | Triage | Board column | Arrived, unowned, matched by no brief yet. | | Queued | Board column | Owned and waiting to be picked up. | | Working | Board column, trace | An agent is on it right now. | | Hold | Approval queue | Routed to a person and waiting on a decision. Not refused. | | Released | Approval queue, trace | A person applied the proposed change, and their name and the time are on the record. | | Settled | Board column, brief | Completed within the agent’s brief. | | Handed off | Trace | Passed to another owner, with a reason written by the agent that passed it. | | Stopped | Trace, brief | The run ended itself. A source was unreachable, a limit was reached, or an input did not make sense. Correct behaviour. | | Failed | Trace, brief | The run ended on an error rather than a decision. Read these first. | > **Hold does not mean no** > Holding is the right outcome when the answer is “not like that” rather than “never”. A held item stays owned by a person and can be released later, edited, or handed back to its agent with more instruction. ### Glossary Source: https://hawiagents.com/docs/reference/glossary Every term the product and this documentation use, in one list. In alphabetical order. Where a term has an ordinary meaning and a Hawi meaning, the Hawi meaning is the one given. - **Account:** A person’s sign-in and billing identity. Holds credit balances and provider authorisations. - **Agent:** A named worker with a brief, a model, a tool list, a spending ceiling and a run history. - **Automatic Purchasing:** A separate workspace permission, enabled and acknowledged by the creator. Never inherited from an autonomy setting. - **Board:** The readable surface of a workspace, holding items in columns. - **Brief:** What an agent is for, written in sentences. This field shapes most of its behaviour. - **Ceiling:** The spending limit an agent works inside. A new agent’s ceiling is nothing. - **Connection:** An authorised link to one external system, held against an account and selected by a workspace. - **Connector:** The definition of how Hawi talks to one provider. Public listings are limited to the customer-connectable registry. - **Cover:** How long current stock will last at the rate it is selling, in whole days, rounded down. - **Credit:** The unit of metered work. Consumed by model calls, tool calls and voice minutes. - **Entitlement:** A capability a plan carries, resolved server-side from account entitlements and workspace membership. - **Handoff:** Moving an item to another owner, carrying the item, the evidence and the run history. - **Item:** One piece of work on a board, with a source, a status, an owner and a history. - **Queue priority:** How a plan’s runs are scheduled under load. Not a measure of model speed. - **Registry key:** A connector’s internal identifier. It may appear in traces and error messages, but does not by itself mean the connector is customer-connectable. - **Run:** One attempt by one agent at one item, recorded with inputs, tool calls, handoffs, cost and outcome. - **Scope:** In connections, the read and write access a connector grants. In the API, what a key may do. - **Trace:** The full record of a run. Continuous across handoffs. - **Workspace:** The operational boundary. Agents, boards, connections and members live inside one. ### Getting help Source: https://hawiagents.com/docs/reference/support What to gather before asking, and what these documentation pages will never contain. #### Before you ask - For an API problem: the `request_id` from the error body, the endpoint, and the approximate time. - For an agent behaving unexpectedly: the run, not a description of it. A trace answers questions a summary cannot. - For a connection problem: the registry key, the state it is in, and whether it worked before. - For anything intermittent: two examples. One is an anecdote. #### What these pages will not contain Documentation is the surface people trust most and verify least, so it is worth saying plainly what is kept off it. - Customers, testimonials, benchmarks, case studies or press. None exist yet, and inventing one in an example is still inventing one. - Prices. They are read live from the billing catalogue and belong on the pricing page. - Absolute promises about what an agent cannot do at runtime. Controls are described as things you configure, because that is what they are. - Any credential, key, connection string or internal address, in an example or anywhere else. - Capabilities that are not connected yet, written as though they are. Where something is a preview, this documentation says so. > **Trivia** > The list above is shorter than it was. An earlier version of the marketing site advertised that money could not move and messages could not go out without a person approving them. It was removed across roughly twenty surfaces in one commit on 2026-08-28, and the rule that replaced it is the third bullet. ### Every limit in one place Source: https://hawiagents.com/docs/reference/limits The numbers scattered through these pages, collected, with what happens when you reach each one. Nothing here is new; every figure appears on the page it belongs to. It is collected because “what is the maximum page size” is a question people ask once and want answered without reading a page about pagination. #### The API | Limit | Value | On reaching it | | --- | --- | --- | | Requests per network origin | 600 / 60s | `429` with `Retry-After` | | Requests per key, per endpoint | 300 / 60s | `429` with `Retry-After` | | File listing page size | 50 default, 100 maximum | Clamped silently, not rejected | | Key expiry options | 7, 30, 90, 365 days | No non-expiring option exists | | Scopes | 2, both reads | A missing scope is `403`, not `401` | | Workspaces per key | 1 | Any other id is `404` | #### Agents and workspaces | Limit | Value | Notes | | --- | --- | --- | | Spending ceiling, new agent | Nothing | A real value, not a placeholder. Raise it deliberately. | | Models available | 6, across 2 providers | Chosen per agent, not per workspace | | Maximum agents | Set by plan | Read from the live billing catalogue | | Automatic Purchasing | Off | A separate acknowledged permission, never inherited from an autonomy setting | #### Connectors | Limit | Value | Notes | | --- | --- | --- | | Connector availability | Live registry | Only customer-connectable providers are listed | | Operation classification | Read or write | An endpoint declared read-only that uses a writing method is classified as a write | #### Files | Rule | Behaviour | | --- | --- | | Type checking | By file signature, not by extension. A renamed executable is rejected at upload. | | Filenames | Stored as a basename with control and bidirectional-override characters removed, so a name cannot disguise its own extension. | | Empty files | Rejected. | | Malformed text | Invalid UTF-8, embedded NUL bytes and invalid JSON are all rejected rather than stored. | ### Questions people actually ask Source: https://hawiagents.com/docs/reference/faq The dozen questions that arrive most often, answered in one line each where possible. - **Can an agent spend money on its own?:** That follows from two things you configure: the agent's spending ceiling, which starts at nothing, and which action types you route to the approval queue. Automatic Purchasing is a separate permission that a workspace creator enables and acknowledges, and it is never inherited from an autonomy setting. - **Do I need one workspace or two?:** One, unless you run two businesses that must not see each other's orders. Separating by channel, team or season is what connections, roles and filters are for. - **Can agents post in team conversation?:** No. That room is for the human members of a workspace. A message can be lifted onto a board when it needs an owner, and that is the crossing point. - **Why did my agent stop instead of finishing?:** Stopping is a correct outcome — a source was unreachable, a limit was reached, or an input did not make sense. It is recorded separately from failing for exactly this reason. - **Can I bring my own model API key?:** No. Hawi holds the provider credentials, so models appear as choices rather than as connections. There is no personal-key field in the agent flow. - **Is my data used to train models?:** Model calls go to the provider Hawi holds the credential with, under Hawi's agreement with them. What that agreement permits is a contractual question, and the honest answer is to read the current subprocessor list and agreement rather than a sentence in documentation. - **Can I export my data?:** Boards, items and run history belong to the workspace. Removing a workspace removes them, so export before deleting rather than after. - **What happens when credits run out?:** Metered work stops. A call already in progress settles as partially completed rather than being cut off and recorded as free. - **Does the API let me create anything?:** No. Two scopes, both reads. There is no write scope and no undocumented one. - **Why is a connector listed if I cannot use it yet?:** The catalogue lists every provider Hawi has a definition for. Whether a given one can complete a connection today depends on the connector; the setup screen tells you which state it is in. - **Is the beta free?:** No. Beta testers pay. The one-year term in the beta programme is a term, not a price. - **Where do I see what an agent actually did?:** The trace. It carries inputs, every tool call and what it returned, handoffs, decisions, cost and outcome, continuously across owners. ### How your data is handled Source: https://hawiagents.com/docs/reference/data-handling Where things are stored, what is never returned, and what this page does not claim. This describes what the product does. It is not a legal document and it does not replace one — the privacy notice, the data processing agreement and the subprocessor list are the authoritative texts, and where this page and those disagree, those are right. #### Where things live - **Boards, items and runs:** Inside one workspace, never visible from another. - **Provider credentials:** Against your account, encrypted at rest, never copied into a workspace record and never returned by any API. - **Files:** In a private store with row-level access rules, reached through signed URLs rather than public addresses. - **Session:** A cookie-backed session refreshed server-side. Nothing security-relevant is read from browser storage, because browser storage is a value the browser can edit. #### What is never returned - A provider secret, in any API response, including the developer API — there is no scope that could ask for one. - A developer key's secret after the moment it was issued. - Connector secrets in a run trace. They are redacted before the trace is stored, not before it is displayed. - Whether a workspace exists, to a key that cannot read it. #### What this page does not claim > **No certification is named here** > No external audit or conformance standard has been confirmed for this product, so none is claimed. The behaviours above are real and checkable in the product; a formal certification is a different thing and stating one that does not exist would be worse than saying nothing. If you need one for procurement, ask. > **Trivia** > Redaction happens before storage rather than before display, and the ordering is the whole point. A value redacted at display time is still in the record for anybody who reaches the record by another route — a support export, a database query, a backup. ### The security model Source: https://hawiagents.com/docs/reference/security-model Where each decision is made, what is server-enforced, and the rule behind all of it. One rule explains most of the design: no security decision is made from a value the browser can edit. Everything below follows from it. | Decision | Made | Not made | | --- | --- | --- | | Are you signed in? | Server-side, revalidating against the auth server | From the cookie's contents | | What is your role? | Server-side from account entitlements and workspace membership, on every request | From browser storage | | May this workspace use this connection? | Server-side, from the workspace's own selection | From what the interface offers | | May this agent touch this system? | Server-side, from the tool list | From the brief's wording | | Does this key have this scope? | Server-side, against the issued scopes | From the request | | Is this webhook genuine? | Server-side, by signature before the body is parsed | From the sender's claim | #### Fail closed Where something cannot be determined, the answer is no. An unverifiable webhook is dropped rather than accepted with a warning. A provider whose signing scheme is not implemented is refused rather than trusted. If the rate limiter itself is unavailable in production, requests are refused rather than let through unmetered. Each of these produces a support conversation instead of an incident, which is the trade being made. #### Isolation - Workspaces share nothing by default. Cross-workspace work requires an explicit delegation. - Provider credentials sit against the account, encrypted, and are never copied into a workspace record. - Files live in a private store with row-level rules and are reached by signed URL. - A developer key reads one workspace. Any other identifier is a 404, whether or not it exists. > **What is not claimed** > No external audit or conformance standard has been confirmed for this product, so none is named. The behaviours above are real and checkable; a certification is a different thing, and stating one that does not exist would be worse than saying nothing. ### What is not built yet Source: https://hawiagents.com/docs/reference/whats-not-built Every preview and gap in one list, so nothing here has to be discovered. Documentation that lists only what works reads as complete and is not. This is the other list. It is worth more than any feature page, because a reader who plans a week around a preview and finds out afterwards was misled by an omission rather than by a claim. #### Voice | | State | | --- | --- | | Speech generation | Real, where its provider credentials are configured for the deployment | | Choosing a voice per agent | Real | | Call outcomes and transcripts | Preview, on illustrative data, labelled as such in the product | | Live inbound and outbound calling | **Not connected.** Needs a telephony provider and a backend pairing contract | | Echo pairing | **Browser-local.** Not a real device pairing | | Local voice-note recording | **Pending delivery support** | #### Agent master configuration The capability and zero-trust configuration surface is behind a preview flag. It reads safe defaults when the backend is not connected, and its activation token is null until a real issuer provisions one — never fabricated on the client. If nothing saves there, that is the honest failure rather than a fault. #### Connections The catalogue lists every provider Hawi has a definition for. A definition is a description of how to talk to a provider; whether a given connector can complete a connection today is shown on its own setup screen. Check there before building a process on top of one. #### Live marketing demonstrations Three public demonstration endpoints exist and each degrades in the open when its credentials are absent — falling back to a labelled worked example, or saying plainly that the demo is not connected. None of them fabricates a result, and a failure is written in the panel where it happened. > **This page is a commitment, not a disclaimer** > If something moves from this list into the working documentation, it should move because it started working. If you find a capability described elsewhere in these pages that belongs here, that is a documentation bug worth reporting. ### Where everything is documented Source: https://hawiagents.com/docs/reference/where-things-are A map from the question you have to the page that answers it. The sidebar is organised by subject. This is organised by question, which is how people actually arrive. - **How do I start?:** Quickstart, then the first week. Before you start lists what to have ready. - **Is this the right tool for me?:** Who it fits, and how it differs from the things it resembles. - **What do these words mean?:** Core concepts for the eight nouns, the glossary for everything, the status vocabulary for what each state commits to. - **Why did my agent do that?:** Reading a trace. Then when an agent misbehaves for the diagnostic order. - **How do I make it do what I want?:** Write the brief first, then set the tool list, then choose the control mode. Each step narrows the next. - **How do I stop it doing something?:** Tool lists first, limits and ceilings second. The tool list is the stronger control. - **Why can it not see my shop?:** When a connection will not connect, then setting up by connection type. - **What will this cost?:** Credits for the mechanism, reading your usage for forecasting, the pricing page for figures. - **What happens when I run out?:** Running out, and auto-recharge. - **How do I read this programmatically?:** Your first API request, then writing a client. - **Is my data safe?:** The security model for how, how your data is handled for what, connection security for credentials. - **Does this actually work yet?:** What is not built yet. Read it before planning around anything. - **Something is broken.:** Getting help, and what to gather before asking.