Packaged AI capabilities that merchants and partners install and use. Topology-deterministic workflow-graphs with predictable cost, multi-tenant safety, and a Qiiub-curated catalog.
Phase 21 · DesignSpec v3.18 ADRs · 0072-0079
What is an "agent" in Qiiub?
It's a workflow-graph with LLM nodes. Qiiub designs the graph in code; the LLM only reasons inside the nodes you placed. This is fundamentally different from the popular "agent" idea.
What people imagine
"AutoGPT-style" autonomous agent
The LLM decides what to do on every loop iteration with no script.
Open loop: think → act → think → act → ... no clear cap.
Can drift out of scope, do unexpected things.
Unpredictable cost: 1 task can use 5 or 50 LLM calls.
Hard to audit, debug, bill.
Legitimately scary in a multi-tenant POS handling money.
What Qiiub Agents are
Workflow with LLM nodes
Qiiub writes the graph for each agent: fixed steps, fixed order.
Some nodes call an LLM, others call tools, others are conditionals.
The LLM only reasons within the node it's invoked from — it doesn't decide which node comes next.
Predictable cost: you know how many LLM calls each agent does.
Audit per-step in AiAgentRunStep.
For tasks that genuinely need open-ended reasoning, a specific node can run a bounded mini ReAct loop (max-steps, max-tokens).
Architecture in 5 layers
From user to storage. Every agent run flows top-down through these layers and is bound to a tenant the entire time.
1Users
Merchant Portal (qiiub-portal) and Partner Portal (qiiub-admin). Browse, install, configure, and use agents.
2Channels
In-app action (button on a record) · In-app chat (side panel, SSE streaming) · Event trigger (POS event or cron) · Email outbound (with human approval).
3Runtime
Workflow Graph Executor walks the graph node-by-node · AI Provider Router picks model per node (OpenAI / Anthropic) · Tool Dispatcher calls in-process handlers · Risk Gate decides auto / draft / approval based on the tool's risk-level.
🛡 Multi-tenant boundary — MerchantId / PartnerId fixed by JWT at run start, immutable for the entire run. Output sanitizer + EF global query filter + RLS as last guards.
4Tools
Each tool is an in-process IToolHandler<TIn,TOut> (application service) shared with the corresponding FastEndpoint. Zero HTTP loopback. Reuses every existing validator, MerchantId-first filter, and audit log.
5Storage + async
CentralDB: 6 new tables (AiAgent · AiAgentInstall · AiAgentRun · AiAgentRunStep · AiAgentConversation · AiAgentTrigger) + 2 nullable columns added to AiRequestLog. Async stack: Azure Service Bus + Container Apps + KEDA autoscaling. Scheduled messages for approval expiration (no DB polling).
Anatomy — the 8 pieces of an agent
An agent is more than a prompt. Eight components work together; understanding what each one does (and where it lives in the code) is essential for design and review.
1
Entry
Input / Request
What triggers the agent — a chat message, a POS event, a button click, a cron tick.
Channel handlers → AiAgentRun
2
Identity
System Prompt
Who the agent is and what it does. Immutable for the run.
AiAgent.SystemPrompt
3
Brain
LLM Provider + Model
Which LLM reasons in each node. OpenAI or Anthropic in v1.
IAiCompletionService
4
Context
Memory (3 types)
Short-term per run · Multi-turn for chat · Per-merchant configuration. RAG / long-term is post-v1.
AiAgentRunStep + Conversation + Install.Config
5
Hands
Tools
What it can do — application services declared with [ToolDefinition]. Same handler the FastEndpoint calls.
IToolHandler<TIn,TOut>
6
Brakes
Guardrails
7 layers: moderation in, anti-injection, scope check, system prompt, tool whitelist, output validation, moderation out.
5 layers of tenant isolation too
7
Output
Result
Typed JSON output + side effects in operational tables (PO Draft, email queue, notification).
AiAgentRun.Output
8
Forensic
Trace / Audit
Step-by-step log of what happened: every node, every LLM call, every gate decision.
AiAgentRunStep + AiRequestLog
Risk Gate — the gatekeeper of every tool
Each tool has a pre-assigned risk level. The Risk Gate is deterministic code that lives outside the LLM — it cannot be tricked by prompt injection.
read 📖
Auto-execute. Reads only, no side effects.
Examples:
get_product
list_top_sellers
get_customer_history
Approval: none. Audit-only.
draft 📝
Auto-execute, but the result is born inactive. Status=Draft, IsActive=false. Zero external side effects.
Examples:
create_po_draft
create_email_draft
generate_description
Approval: human activates the draft when they decide.
write ⚠️
Pause the run in AwaitingApproval. Tool intent saved but NOT executed. Human reviews, can edit, must explicitly approve.
Examples:
send_email
activate_po
publish_product
refund_payment
Approval: synchronous, explicit.
Catalog v1 — five flagship agents
Curated by Qiiub. Cover the 4 channels, the 3 risk levels, both audiences (merchant + partner), and the 3 sub-phases of v1.
① Sales Insights Chat
sales-insights-chat
merchantv1.01 cr/msg
Natural-language chat about your sales: top products, best day, average ticket, comparisons. Read-only, multi-turn.