AI

Power users decide which model does a job, what instructions it follows, and where its answer goes. All three are configuration: agents for the model, templates for the instructions, and the AI method or engine for the destination.

Agents

An agent is a named AI configuration. Every AI method takes an agent name, so the same installation can use one model for document extraction and another for reporting.

Setting	Purpose
Name	What templates, workflows, and API calls refer to.
Provider	Claude (Anthropic), Gemini (Google), OpenAI, or Amazon Bedrock.
Model	The provider’s model identifier.
API key entry	The name of the configuration entry that holds the key. The key itself is never stored on the agent.
Instructions	Standing guidance sent with every request.
Base agent and instructions mode	Inherit everything from another agent and override only what differs. The mode decides whether this agent’s instructions replace, append to, or prepend the base agent’s.
Retry count	How many times to retry a transient failure.
Scope	Optionally tie the agent to one record (for example, one client organization) instead of the whole installation.
Status	Only active agents are available.

Agents can be defined in the installation’s configuration or stored in the database. Database agents are picked up by every server in a farm automatically, on startup and on a polling interval, so a new or changed agent is available everywhere without a restart.

Live data in instructions

Instructions can pull current QBO data at run time. Write a method signature in braces, {ClassName/Operation?Parameters}, and QBO replaces it with that operation’s results as JSON, run under the calling user’s security, before the instructions reach the model. Use it to give an agent today’s fee schedule, a client’s guidelines, or a list of valid values without copying them into the instructions by hand.

Fallback agents

A cascade is an ordered list of agents tried in turn. QBO moves to the next agent when the current one fails with a matching error (by default, “document has no pages”; you can add others such as quota errors), or, if configured, when its response is empty, isn’t valid JSON or XML, or is a JSON null. Use it to try a fast, inexpensive model first and fall back to a more capable one.

External tools

QBO agents can use tools published by external MCP (Model Context Protocol) servers. Each server is configured by URL with no authentication, Microsoft Entra, a bearer token, or an API key header.

Where instructions come from

Each AI method reads its instructions from a template you already maintain, so changing behavior is a template edit.

AI method	Instructions and choices come from	Result
Classify a document	Your document templates that have a description. The description tells the model what that kind of document looks like.	Sets the document’s template. Pass a default template to use when nothing matches.
Label a record	Your labels for that kind of record that have a description.	Adds every matching label, dated today. Existing labels aren’t duplicated.
Review a record	A message template: its body is the instructions.	A message on the record with a subject, a Markdown memo, and a suggested priority and status. Its type defaults to AI Review.
Complete a form	A message template, plus the form template’s questions (label, tooltip, and allowed options).	Fills the form’s standard fields (dates and work estimates) and its answers, merged with any answers already there.
Update a record	An import template’s description, or a message template.	Sets the record’s fields from the model’s JSON.
Draft a reply	The inbound message and a summary of its parent record.	An unsaved reply, opened for editing.

Write descriptions the way you’d brief a new colleague: what the document or label is, and how to tell it apart from similar ones.

Scoring with AI

To extract values with AI, create a score template whose engine is an AI engine, and add a score item template for each value.

Engine	Reads	Use it when
AI score engine	The text of a document (converted to text first if needed) or a message’s subject and body	The text is clean, or you already OCR documents
AI modal engine	The original file: PDF, image, or audio	Layout, tables, handwriting, or images matter

For each score item template, set:

• Prompt: what to extract, in plain English, for example “the policy expiration date”.
• Value type: yes/no, number, date, money, or text. QBO converts the model’s answer to that type.
• Weight (optional): how much this item counts toward the score’s overall confidence.

Engine parameters on the score template choose the agent (AgentName) and whether to collect confidences (UseConfidence, on by default). The AI modal engine can also keep an uploaded file with the provider for a set number of minutes (FileExpirationMinutes), so scoring the same document repeatedly doesn’t upload it again.

Weighted confidence. Each item gets its own confidence. The score’s confidence is the weighted average across items that have one: an item with no weight counts as 1, a weight of 0 leaves the item out, and an item the model scored but couldn’t find a value for counts as 0. Rules and workflows can use these values like any other score data.

Importing with AI

Create an import template whose engine is the AI import engine:

• Applies to names the kind of record to create, such as Contact or LedgerItem.
• Description holds the instructions, including the structure you expect back. Describe any nested child records (for example, line items under an invoice) and QBO imports them with their parent.

The engine sends the document, and optionally a related record for context, to the agent, then saves the results through the standard import path, with the same validation and logging as any other import. Typical uses include contacts from a PDF and ledger items from an invoice.

For large volumes, the AI batch import engines submit a whole search of documents as one provider batch job, check back on a schedule (every 60 minutes by default), and run the template’s result method once per completed document.

Reporting questions

Plain-English reporting uses a dedicated SQL agent, named qbo-sql unless you configure another. QBO can create it for you once its provider, model, and API key entry are configured. The agent’s instructions carry your database schema; every generated query is checked to be a single read-only SELECT and validated against the schema without running it. If validation fails, QBO asks the model to correct itself, up to two times. If it still fails, QBO returns the last attempt with a warning to review it before running. A reply without a query (a clarifying question, or a note that the data doesn’t exist) is shown to the user as is.

The ad hoc reporting page validates against the qbo.AdHoc connection by default; point it at a login with read-only database permissions as a second line of defense.

Turning AI options on

Option	Requires
Classify and Transcribe on documents	AI configured for the installation, and the AttachmentAiClassify / AttachmentAiTranscribe permissions
Generate response using AI on replies	The Messaging application setting GenerativeAI set to True, and the MessageReply permission
Plain-English reporting	AI agents configured, and the ReportAiToQuery permission

Track token costs in a ledger

QBO can post the tokens each AI call uses to a ledger on the record, so AI cost is reported and invoiced like any other cost. Configure ledger usage for the installation:

Setting	Purpose
Input, output, cached input, and reasoning rates	Dollars per million tokens, per model. Model names match by prefix, so one entry can cover a family of models. Defaults apply to unlisted models.
Ledger template item	The default line item for AI usage. You can map each token type to its own line item for analysis.

Each call creates up to four ledger items, one per token type (input, cached input, output, reasoning), sharing one transaction number. Cached input defaults to the input rate and reasoning to the output rate, so the total is right even before you set those rates. Usage is only posted when the call names a ledger and runs as a known user.