Voltade's engineering blueprint for agentic AI in production.
The agent can only do what the typed tool catalogue allows.
Every customer-affecting change is reviewable and recorded.
Prior state is preserved so undo stays cheap.
Agentic AI is what you get when a language model becomes a colleague. The kind that reads transcripts, drafts replies, writes notes, schedules follow-ups, and hands off to humans when the situation warrants it. Done well, it removes hundreds of hours of repetitive work from a team's month. Done badly, it embarrasses the brand, leaks data, costs you years of customer trust, and the team finds out a week after the damage.
Most teams who have tried to put an agent in production have lived the gap between the two. The demo looked clean. The pilot worked on a Tuesday. By the time real customer messages started arriving, the agent had said something it shouldn't have, written into a field it wasn't authorised to touch, or quietly stopped working in a way nobody noticed for a week.
We've spent the last two years building Voltade's agentic platform to close that gap. It rests on three commitments. Firstly, every action the agent can take is a typed function in our codebase, with no hidden orchestration layer underneath. Secondly, the agent's view of the world is a filesystem of plain-text markdown files any human on the team can read, edit, and version-control in a normal text editor. Thirdly, every customer-affecting change flows through a propose-review-apply pipeline with full history; nothing important happens without a record of who decided what, and why.
The result is an agent that's bounded by design, reversible by default, and audited to the row. Those properties are the difference between an experiment and a production system. The rest of this document is how we got there.
There's a quiet truth in the agentic-AI conversation that the demos don't acknowledge. The hard part isn't building an agent that can do the work. The hard part is building one your operations director will let near a paying customer.
We see the same pattern across most of the projects that come to us already in flight. A team builds something impressive on a generic LLM. It passes the show-and-tell. Then someone asks the questions that decide whether it ever gets switched on:
Reasonable questions. They are the questions any operations team would ask of a new hire on day one. Most agentic-AI architectures cannot answer them without a long conversation about prompts, context windows, and vector stores, none of which a customer ever sees, and none of which constitute a real answer.
The trust gap is the distance between a working demo and a production system. It's where projects go to die. The architecture in this document is what we built to close it.
After 1000+ projects, three properties separate the agents that survive contact with real customers from the ones that don't. Every architectural decision we make is in service of one of them. None are optional.
The agent can only do what we let it do. A clever input cannot talk it into more.
A generic LLM with tool-use is a powerful thing. By default it's also a system where the agent's capabilities are bounded only by what someone can convince the model to attempt. That's the wrong default for production. Our agents don't have capabilities in the abstract. They have a specific, enumerated set of typed functions, each of which routes through a single service call with an input schema we wrote. The agent cannot run an action that isn't already in the codebase.
Anyone can open the file modules/messaging/tools/ and see every single action the agent can take in a conversation, in two screens. No hidden orchestration, no emergent behaviour. The map is the territory.
Every change the agent makes is reviewable, traceable, and explainable.
Some of our agents handle small writes, like appending a note to a customer's memory or flagging a conversation as stale. Some handle larger ones, like drafting a refund confirmation or updating a contact's tier. Either way, every customer-affecting write either auto-applies with a recorded reason, or queues for staff review with a diff that shows exactly what would change. The agent never updates state and leaves the team to discover it a week later.
When something goes wrong, and at some point something will, the question "what did the agent actually do?" has an answer that takes seconds to produce. Every mutation is a row in a change-history table with a before-state, an after-state, a rationale, a decider, and a timestamp.
When the agent is wrong, the undo is cheap.
The first two properties prevent the worst outcomes. The third is what happens when one slips through anyway. Our change-history pipeline records the prior state of every write the agent makes. A revert is a single write of that prior payload. No forensic exercise, no manual reconstruction, no phone call to engineering at 11pm on a Sunday.
We design for the assumption that the agent will eventually be wrong. The architecture is calibrated for that day, and only secondarily for the day of the demo.
Most agentic AI in the market today is what we'd call AI-bolted-on. A team built a CRM, a helpdesk, a customer-service platform, and then, in the last eighteen months, bolted an LLM on top that talks to it. The LLM lives in a sidebar. Behind the scenes it's plugged into the same internal APIs the human staff use, often with the same level of access. It writes into the same fields. It calls the same endpoints. The company hopes very much that the prompt is enough to keep it inside the lines.
It almost never is. We've taken over more than one project where the previous vendor's agent could, by design, update any contact field in the CRM from any conversation, with no audit trail beyond a generic "AI assistant edit" tag. That's what AI-bolted-on looks like in practice, and it's why those agents stay confined to read-only demos, never quite trusted with anything that touches a customer.
Voltade is agent-native. The platform was designed from the first commit to have the AI agent as a first-class participant. A peer to the human staff member, with the same trust scaling everyone else uses. Three commitments shape every part of the architecture:
Every action the agent can take is a typed function with a validated input schema, a single service call underneath, and a declared trust tier. There is no "let the agent figure it out" layer. If the action isn't in modules/*/tools/, the agent cannot perform it. Period.
That's what makes the agent's behaviour boundable in production. We extend what the agent can do by adding a file. We cannot fail to know what it can do, because the catalogue is the codebase.
Identity, conversation transcripts, contact records, business policies, learned skills, and the agent's own memory all appear to the agent as plain-text markdown files at known paths in a virtual workspace. The agent navigates them with the same shell commands a software engineer would use: cat, ls, grep, echo >>. Customer memory lives at /contacts/<id>/MEMORY.md. Brand policies live at /drive/BUSINESS.md. The agent's job description lives at /agents/<id>/AGENTS.md. Staff context lives at /staff/<id>/MEMORY.md.
The point of this choice is human legibility. Staff can read every file the agent reads and edit every file the agent can edit, in a normal text editor. There is no embedding store to peer into, no opaque vector retrieval, no agent-internal scratchpad we have to dump and reconstitute. The agent's context is, quite literally, a set of markdown files on a virtual disk. Your team can see what it sees.
There are three ways the agent can change anything in the system: by appending prose to a memory file, by running a CLI verb that updates a structured field, or by calling a typed tool that produces a customer-visible side effect. There is no fourth shape. There is no back door. Every change the agent makes falls into one of these patterns, each of which is auditable and replayable. The ones that touch customer-affecting state route through the propose-review-apply pipeline before anything is committed.
That's what answers the second-day question, "What did the agent actually do?", by construction. There is no place to look that isn't one of the three.
Architectures don't make systems safe by themselves. Invariants do. Properties the system maintains no matter what input it receives. We hold the platform to a small number of these. They are the ones you should be able to ask any agentic vendor about and get a single-sentence answer.
The instructions that govern the agent are computed once when the agent wakes up, and held byte-identical across every turn of that wake. We compute a cryptographic hash of the prompt at the start and record it. If the same agent woke up on the same trigger tomorrow, the hash would match.
A drifting system prompt is the most common source of an agent that "starts strong and ends weirdly." It also defeats the prefix-caching most LLM providers offer, balloons cost, and breaks reproducibility. None of those are acceptable on a production system.
The platform has three trust rungs: contact, staff, admin. Every conversation the agent runs is assigned a tier based on who initiated it. A wake started by a customer message inherits contact-tier trust; the agent can only see the actions any staff member would expose to a customer. A wake started by a staff member's internal note inherits staff-tier trust; the agent gains access to internal tools and richer context. A wake started by an operator running the platform CLI inherits admin trust.
This filtering happens at the catalogue level. The agent literally does not see tools or verbs it isn't trusted to use in the current context. It can't be talked into invoking them, because they aren't in its menu.
When the agent decides to update a customer field, refine a memory note, send an outbound message, or queue a follow-up, the change is not applied directly. It enters a structured pipeline. The platform classifies the change by sensitivity, and the combination of confidence × sensitivity decides whether it auto-applies, queues for staff review, or is dropped as too low-confidence to be worth proposing.
Every applied change is recorded with a before-snapshot, an after-snapshot, a rationale, the decider, and a timestamp. Revert is a one-write operation. That's how we make the "what did the agent do?" question answerable in seconds.
A wake is one bounded execution of an agent. A single turn or set of turns, with a start, an end, a turn cap, and a cost ceiling. The agent is not a long-lived process consuming tokens between user messages. When the conversation ends, the wake ends. The agent stops. There is no always-on process to monitor for runaway behaviour, because there is no always-on process to begin with.
For your finance team, that also means LLM cost is predictable per interaction, not per hour. We can tell you what an average agent costs to run. We can also tell you the maximum cost of a single wake, because we set it.
Channels like WhatsApp have a quirk most teams discover the hard way. When a staff member replies from the WhatsApp Business app, the message echoes back to the platform as if it were a fresh inbound. A naive agent answers it. The customer ends up in a two-way conversation between the agent and the staffer, both confused.
Our channel adapters surface this behaviour to the agent as an explicit rule in its instructions: when the message has a staff role and an echo-source tag, stay silent. The agent does not need to be smart enough to figure that out on its own. The architecture tells it.
The platform's coordination primitive is the @-mention. When the agent flags a teammate inside an internal note, the platform wakes that teammate (human or agent) and ends the current turn cleanly. We hard-filter self-mentions, so an agent cannot mention itself into a recursive wake. The same filter applies to notes without any mention; they wake nobody.
Architecture is easier to evaluate when it's concrete. Here are three scenarios that run on Voltade's platform every day. Each one is one bounded wake, with a clean start, work, and exit.
A customer messages on WhatsApp asking for a refund. The platform receives the webhook, resolves the contact, inserts the message into the conversation, and wakes a conversation-lane agent at contact trust.
The agent's first move is to read the refund playbook from its skills folder and the brand policies from its drive. Then it pulls up the order. The refund is inside the policy window and below the auto-approval ceiling, so the agent drafts a confirmation card with two buttons (Confirm and Talk to a human) and submits it for staff approval.
The wake ends. A staff member sees the proposed card, taps approve, and the platform fires an approval_resumed trigger that wakes the same agent again with the conversation context. The agent dispatches the card, the customer taps confirm, and the agent writes a single line to that customer's memory: "Prefers WhatsApp for support." That note is now available to every future wake on that contact.
The agent didn't ship the refund itself. It staged the refund, paused for review, resumed once reviewed, and recorded what it learned for next time. The team got a draft they could ship in one tap. The customer got an answer in minutes.
A senior staff member picks up a conversation she didn't open. She drops an internal note: "@triage-agent, can you summarise what this customer asked about last quarter? I'm taking this over."
The mention fans out as a staff_note trigger. The agent wakes at staff trust, higher than the contact trust it would have had on an inbound message, which means a different set of internal tools and verbs is available. It greps the conversation history, scans the contact's memory, and posts a clean three-line summary as a follow-up note. No customer-visible message goes out. The wake ends.
The agent behaves as a teammate the staff can talk to inside the system, on the same trust scaling everyone else uses. It knows where to look because everything it knows about that contact lives in files at known paths.
At 6pm local time, a recurring schedule fires a heartbeat trigger on the agent. It wakes in standalone mode, with no customer on the line, at staff trust.
The agent's first call is summarize_inbox, a read-only scan that the agent's instructions explicitly mark as the cheap first move. It surveys the active conversations, finds three that have been stale for more than 48 hours, and drafts a follow-up email to staff review for each. Nothing goes out yet. The agent writes one line to its own memory ("3 stale conversations flagged on 2026-05-11") and ends the wake.
Agents do self-paced work without being always-on. The schedule is the trigger, the wake is the work, the cost is bounded, and nothing customer-visible ships without staff sign-off.
Voltade's answer to each is in italics.
Show me the full list of actions the agent can take. Where does it live in your codebase?
One folder per module under modules/*/tools/. The catalogue is the code.
Can the agent take an action that isn't in that list? No. Tool execution routes through a typed registry; anything unregistered cannot be called.
What stops the system prompt from drifting mid-conversation? We compute it once per wake and hash it. Any drift would change the hash, and we test for this in CI.
How does the agent's access scale with where the input came from? Three trust tiers, derived from the trigger, applied to the catalogue before the agent ever sees it.
When the agent updates customer-affecting state, who reviews it? Every such change is routed through a propose-review-apply pipeline. Sensitivity × confidence decides auto-apply vs. queue.
How do I see what the agent did to a specific record last Tuesday?
One query against change_history. Before-state, after-state, rationale, decider, timestamp.
What's your story for an agent that runs forever in the background? We don't have one. Agents don't run between user messages. Wakes are bounded, with a turn cap and a hard cost ceiling.
What happens when a human is also typing on the same channel?
The agent recognises the echo as a staff role and goes silent. The rule lives in the channel adapter.
If we want to change the agent's behaviour for a recurring scenario, what do we edit?
A markdown file under /agents/<id>/skills/<name>/SKILL.md. No retraining. The next wake picks it up.
If you change LLM providers, how much of our system breaks? None of it. The LLM is a single seam in the codebase. We treat the provider as a configuration choice.
We are a custom AI agent development company based in Singapore, AI-native from the first commit. We've delivered 1000+ projects across F&B, manufacturing, healthcare, education, and retail. Voltade's platform is what every one of those projects is built on.
The engagement model is short. We listen, we scope, we build, we deploy, and we support. Most projects go from first call to a working agent in weeks, not months. Singapore SMEs can claim up to 50% PSG support on eligible projects, and we handle the AIxDL claim on your behalf where it applies.
We build the agent your business actually needs, connected to the tools you already use, trained on your SOPs, deployed on the platform described in the appendix that follows, and supported by the same engineers who built it. Generic chatbot subscriptions aren't what we sell.
Tell us what you need. [email protected]
What follows is the architecture deep-dive an engineering team would cite during diligence. Every file path is real. Every invariant is enforced in code. Internally we refer to the platform as Vobase; on the outside it's the engine behind Voltade's products and custom builds.
Voltade's agentic platform is a TypeScript-first monorepo organised by module. Each module owns one concern (messaging, contacts, team, drive, agents, schedules, channels, changes, system) and exposes a small, typed surface for the AI agent: tools, virtual files, CLI verbs, and AGENTS.md fragments. There is no central orchestration layer; the agent's capabilities are the union of what each module declares.
The single thesis behind every decision: AI agents need codebases they understand. One folder per feature, one pattern copy, one seam change. The same constraint makes the codebase legible to humans and to the AI. We optimise for both readers, in that order.
A wake is one bounded execution of an agent. It has a single entry point, a typed WakeContext, a turn cap, a cost ceiling, and a defined exit.
Four entry handlers cover the trigger surface:
| File | Trigger | Lane |
|---|---|---|
wake/inbound.ts | Customer message arrived | conversation |
wake/staff-note.ts | Staff @-mentioned an agent | conversation |
wake/operator-thread.ts | Staff opened an operator DM with the agent | standalone |
wake/heartbeat.ts | Cron tick from a registered schedule | standalone |
Each handler resolves the agent definition, builds a typed WakeContext, calls the lane-appropriate config builder (conversationWakeConfig or standaloneWakeConfig), and hands off to createHarness<WakeTrigger>(). Inside the harness, the turn loop emits a strict event sequence: agent_start → turn_start → llm_call → message_* → tool_execution_* → turn_end → agent_end. Observers attach at well-defined points; nothing important happens between events.
(contactId, channelInstanceId, conversationId). The agent has access to customer messages, internal notes, the contact profile, and conversation-scoped tools (reply, send_card, send_file, book_slot).Tool results are size-bounded to keep prompts predictable. 4 KB inline fits in the next turn's side-load directly. 100 KB spill overflows the result to /tmp/tool-<callId>.txt for on-demand re-read. 200 KB turn ceiling is the hard cap per turn, with re-reads of spills exempt.
The system prompt is computed once at agent_start and held byte-identical across every turn of the wake. A systemHash (SHA-256 over the rendered prompt) is recorded on the AgentStartEvent. Mid-wake file writes do not change the system prompt; they appear in the next turn's side-load, not the system block.
Three reasons it matters:
Enforcement: trigger renderers are pure functions (no DB reads, no clock, no RNG, no environment access); session context is resolved once at wake start; the workspace-sync observer flushes file changes only on agent_end. The static instruction block carries the rule explicitly so the agent itself reasons about it: "files in your frozen prompt were snapshotted at the start of this wake. Mid-wake writes persist, but only show up in the NEXT turn's side-load, not in the system prompt."
AudienceTier is a three-rung monotonic trust scale: 'contact' | 'staff' | 'admin' (least → most trusted). Every wake is assigned a tier at config-build time:
(lane, triggerKind) | audienceTier | Why |
|---|---|---|
conversation + inbound_message | contact | Customer drove this wake; treat input as untrusted. |
conversation + staff_note / approval_resumed / scheduled_followup / manual | staff | A staff action initiated it. |
standalone + operator_thread / heartbeat | staff | No customer; internal context. |
| CLI binary with admin API key | admin | Operator-driven, outside the harness. |
Every CLI verb declares its own audience tier. The visibility rule is verb.audience ≤ wake.audienceTier. The same filter applies to tools by lane. The agent never sees a tool or verb that would be rejected at runtime, so it cannot be cajoled into calling something it can't see.
Filtering happens in two places: the AGENTS.md ## Commands block (which lists the verbs the agent knows about) and the in-bash vobase --help output. Identical predicate, two surfaces.
The agent operates inside a bash sandbox with a virtual filesystem materialised at wake start. It runs cat, ls, grep, echo >>, and vobase CLI verbs. No SQL, no HTTP, no internal IDs to memorise, no opaque APIs to learn.
Top-level layout:
/drive/ # org-wide knowledge base (read-only)
BUSINESS.md # brand, policies, FAQ
... # uploaded docs
/contacts/<contactId>/
PROFILE.md # RO; identity, frontmatter
MEMORY.md # writable; per-customer facts
<channelInstanceId>/
MESSAGES.md # RO transcript
INTERNAL-NOTES.md # RO staff notes
drive/ # per-contact files
/staff/<staffId>/
PROFILE.md # RO; name, title, expertise
MEMORY.md # writable; per-(agent, staff) memory
/agents/<agentId>/
AGENTS.md # RO; the system prompt itself
MEMORY.md # writable; agent's own working memory
skills/<skillName>/
SKILL.md # playbook for a recurring scenario
/INDEX.md # top-level navigator
/tmp/ # scratch; cleared per wake
Each module declares a list of WorkspaceMaterializerFactory<WakeContext> functions on its agent.ts. At wake start the harness invokes every factory with the live WakeContext and collects the resulting WorkspaceMaterializer[]. Each materialiser declares a path, a phase (frozen = rendered once, dynamic = re-rendered per turn), and an async materialize() returning the file body.
Some paths are not files in storage. /contacts/<id>/MEMORY.md, for instance, is backed by the memory column on contacts.contacts. The drive subsystem exposes a provider interface (registerDriveOverlay); each module registers a provider that synthesises virtual rows for listFolder and resolves bodies for read and write. Providers always scope by organizationId. Every overlay read or write is type-safe and audit-logged. The file is the agent-facing projection of a service call.
The agent has three durable memory scopes. All three are written by direct file appends inside the wake (echo "- ..." >> /…/MEMORY.md); a workspace-sync observer flushes the diffs to backing columns at agent_end.
| Scope | Virtual path | Backing column | Meaning |
|---|---|---|---|
| agent | /agents/<id>/MEMORY.md | agent_definitions.working_memory | Self-knowledge. "Always confirm refund window before quoting an amount." |
| contact | /contacts/<id>/MEMORY.md | contacts.contacts.memory | Per-customer facts. "Prefers SMS over email. Account on Pro tier since 2025-03." |
| staff | /staff/<staffId>/MEMORY.md | agent_staff_memory.memory | Per-(agent, staff) memory. "@billing-lead handles refund overrides above $100." |
A budget header is prepended at materialisation time (<!-- memory-budget scope=agent ... -->) showing soft cap usage; it's stripped before storage so re-renders don't stack headers. Default soft cap: 8000 UTF-16 code units per scope.
Capture heuristics, surfaced in AGENTS.md, decide which scope a memory write lands in. A line that contains a contact name routes to the contact's memory file. A line that starts with always, never, or from now on routes to the agent's working memory. A line that names a specific staff member's pattern routes to staff memory. Anything else stays in the agent's own working memory by default.
Staff memory has no /drive/** mirror; outside a wake, the only way to read or edit it is via Drizzle Studio. That's intentional. Staff memory is internal context for the agent, separate from customer-visible data.
AGENTS.md is the agent's read-only view of its own job description. It is the bulk of the system prompt. It's rebuilt for every wake, lane-aware, tier-filtered, and assembled from contributions across modules.
Nine sections, in order:
/agents/<id>/MEMORY.md: agent's lesson capture./agents/<id>/AGENTS.md body: instructions, tools table, CLI verbs table, module-contributed fragments./drive/BUSINESS.md: org policies, brand, FAQ./agents/<id>/skills/ with descriptions.The rendered string is SHA-256'd into systemHash and held constant for the wake.
Modules contribute fragments via their agent.ts (the agentsMd slot). Each fragment is an IndexContributor with a priority and an optional gating predicate over (lane, triggerKind). A fragment whose predicate doesn't match the current wake simply isn't emitted, so the agent never reads a section that doesn't apply.
Representative fragments:
agents.self-state (priority 20): describes MEMORY.md, the skills folder, the /tmp scratch space.agents.memory-capture-triggers (priority 25): the always / never / from now on keyword list.drive.organization-knowledge (priority 30): /drive/* as the read-only knowledge base.contacts.contact-context (priority 40): PROFILE.md, MEMORY.md, per-contact /drive/.messaging.conversation-surface (priority 50): conversation-lane tools and vobase conv reassign.messaging.staff-note (priority 60, gated to conversation + staff_note): three-step playbook for staff @-mentions.messaging.standalone-no-customer (priority 60, gated to standalone): "No customer is on the line."channels.whatsapp-echoes (priority 55, gated to conversation): coexistence rules for WhatsApp Business App echoes.team.staff-roster (priority 60): staff PROFILE/MEMORY conventions.Every tool is a typed function with a Zod input schema, a declared lane, and a single service call.
modules/messaging/tools/)| Tool | Lane | Effect |
|---|---|---|
reply | conversation | Append text message; dispatch via channel adapter. |
send_card | conversation | Append rich card (text/image/divider/actions/fields/link children). Approval-gated if agent.cardApprovalRequired. |
send_file | conversation | Send drive file; scope-checks file against conversation contact. |
book_slot | conversation | Stub for calendar integration. Approval-gated. |
add_note | both | Append internal note. Each @-mention enqueues a staff-note wake. |
summarize_inbox | standalone | Read-only scan of conversations, safe to call repeatedly. |
draft_email_to_review | standalone | Queue email draft for staff review; nothing ships until approved. |
modules/contacts/tools/)| Tool | Lane | Effect |
|---|---|---|
update_contact | standalone | Mutate contact (displayName, phone, email, segments). |
propose_outreach | standalone | Queue outbound message for staff review. |
modules/agents/tools/)| Tool | Lane | Effect |
|---|---|---|
remember | both | Commit a lesson to durable memory through the change-proposals pipeline; sensitivity × confidence routes the change to auto_written / pending / dropped. |
dismiss_candidate | both | Mark a learning candidate as dismissed. |
modules/schedules/tools/)| Tool | Lane | Effect |
|---|---|---|
create_schedule | standalone | Insert recurring heartbeat. |
pause_schedule | standalone | Disable a schedule. |
modules/drive/tools/)| Tool | Lane | Effect |
|---|---|---|
request_caption | conversation | Annotate a file with extracted-text caption. |
Per-tool prompts carry strong opinions. reply is reserved for pure acknowledgements, free-form questions, single-sentence facts with no CTA, and short clarifying asks. send_card is the preferred reply format whenever the customer has options to choose, confirm, compare, or act on. summarize_inbox is marked as the cheap first move when triaging: read-only, safe to call repeatedly within a wake.
Inside a wake the agent runs vobase ... commands as if it were a staff member at a terminal. Each verb registers in a shared CliVerbRegistry; the same body runs both in-process during a wake and over HTTP-RPC when the actual vobase binary is invoked by an operator. Verbs declare audience so the in-bash --help filters by wake tier.
Canonical set:
| Verb | Module | Audience | Purpose |
|---|---|---|---|
agents list | agents | admin | Inventory agent definitions. |
agents show <id> | agents | staff | Full definition. |
agents inspect <id> | agents | admin | Dump instructions + memory tail + allowed tools + model. |
team list | team | contact | Staff roster. |
team get <id> | team | contact | Staff profile. |
drive propose --path --body --rationale? | drive | contact | Raise a change proposal against a drive file. |
drive upload | drive | contact | Upload file to drive. |
drive search <query> | drive | contact | Keyword search. |
| `conv reassign --to=user:<id> | agent:<id> | unassigned --reason?` | messaging |
channels list | channels | contact | Channel instances. |
messaging close | messaging | staff | Close a conversation. |
messaging show | messaging | staff | Show conversation detail. |
install | system | admin | Tenant bootstrap. |
Argv flags coerce to JSON-Schema types before validation, so verb schemas use strict z.number() / z.boolean(). No z.coerce.* allowed.
Skills are markdown files materialised under /agents/<id>/skills/<name>/SKILL.md. Each has YAML frontmatter (name, description) and a body containing the playbook. They're discovered at wake start and listed by name in the AGENTS.md ## Skills section, so the agent knows when to cat them.
Default skills ship under modules/<m>/skills/. Two representative examples:
refund-flow: a five-step playbook. Confirm order id via vobase contacts show. Check /drive/BUSINESS.md#Policies for eligibility window. Within window and amount ≤ $100, draft a confirmation card. Over $100 or outside window, mark requires_approval=true and mention @billing-lead. Never confirm verbally before the card is acknowledged.template-selection: when to use send_card vs reply. "When in doubt, send a card. Cards are tap-to-reply; prose forces the customer to type."Skills can be edited by staff (through change proposals) or added at install time. They are the primary way operators encode local policy without rewriting the agent's instructions. Change the .md, and the next wake picks it up.
Every non-trivial mutation an agent makes against shared state flows through modules/changes/. This includes memory writes above a confidence threshold, edits to learned skills, structured updates to contact fields, and outbound message proposals.
insertProposal({ resourceModule, resourceType, resourceId, payload, confidence, rationale, expectedOutcome, conversationId }). Routes by effectiveSensitivity(resource, payload) × confidence:
auto_written (applies immediately).pending (staff review queue).dropped.pending proposals at /api/changes/proposals/{id}/decide. Decisions are recorded with the deciding user, timestamp, and any free-text comment.change_history records before-snapshot, after-snapshot, decider, timestamp, applied proposal id. Queryable per resource.Each resource module registers a materialiser at boot:
{
resourceModule, resourceType,
sensitivity, // 'HIGH' | 'MEDIUM' | 'LOW'
sensitivityForFields?, // per-field overrides
promptHint, // short description used in triage
materialize(proposal, tx) // applies the change
}
Resources opting in (canonical example: contacts):
contacts.contact_memory: LOW; agent prose to customer memory.agents.agent_memory: HIGH; large agent self-edits.agents.learned_skill: MEDIUM; skill body changes.team.staff_memory: MEDIUM.drive.doc: MEDIUM.The pipeline makes every customer-affecting state change reviewable. It either auto-applies with a recorded rationale or queues for staff with a diff that shows exactly what would change. It makes the outcome replayable. A change_decided trigger can wake the original agent to follow up with the customer ("Approved; here's your refund timeline."). And it makes the change reversible. History stores the before-state, so revert is a write of the prior payload.
Channels are pluggable adapters under modules/channels/adapters/<name>/. Each adapter knows how to receive inbound messages from its medium and dispatch outbound ones. The agent doesn't talk to channels directly. It calls reply / send_card / send_file, and the messaging service routes to the right adapter.
Message arrives on adapter (web socket, WhatsApp webhook, ...)
→ contact resolved or created (upsertByExternalKey)
→ row inserted into conversation_events
→ messaging fan-out fires inbound_message trigger
→ wake/inbound.ts builds conversation-lane wake
→ agent reads MESSAGES.md, calls tools
→ outbound tools route to adapter
→ adapter translates and dispatches
send_card renders as buttons or list pickers. The adapter also contributes a coexistence rule: "When you see role='staff' with metadata.echoSource='business_app' (human staffer answering from the WhatsApp Business app): stay silent. Do not reply, send card, drop a note, or reassign. End turn cleanly."@-mentionsadd_note accepts a mentions array. Each mentioned staff member receives a notification. Each mentioned agent is woken (staff_note trigger). This produces a clean two-way channel:
add_note(body: "...", mentions: ["@billing-lead"]) and ends its turn.staff_note wake on the original agent with the staff's answer in context.Two guard rails: an agent's own internal notes never fan out to itself (hard filter in notes.ts), and notes without any @-mention wake nobody.
vobase conv reassign --to=user:<staffId> --reason='customer asked for human'. Convention: acknowledge the customer first ("Connecting you with a teammate now..."), drop an add_note with context for the receiving staff member, then reassign. The conversation status flips and the next message routes to the human inbox.
An agent can call create_schedule(slug, cron, timezone?) to install a recurring heartbeat. At each tick, wake/heartbeat.ts fires a heartbeat trigger with the schedule context. Use cases include nightly inbox sweeps, weekly summary email drafts, periodic memory consolidation, and recurring data-quality checks. Harness errors on a heartbeat are swallowed and logged so one broken schedule doesn't starve siblings.
Tools tagged for approval (send_card when agent.cardApprovalRequired, send_file, book_slot, draft_email_to_review, propose_outreach) insert into pending_approvals instead of dispatching. When a staff member decides, an approval_resumed wake fires on the original agent so it can finish the turn, whether that's confirming to the customer, logging to memory, correcting course, or escalating to a teammate.
| Invariant | Mechanism |
|---|---|
| System prompt is byte-stable across a wake. | Pure trigger renderers, frozen session context, observer flushes deferred to agent_end. |
| Agent cannot see tools above its trust tier. | lane filter + audience ≤ wake.audienceTier filter applied to both AGENTS.md and the tool catalogue. |
| Every mutation has one write path. | check:shape script (CI) restricts writes to messages, conversation_events, change_proposals, change_history to specific service files. |
| No cross-tenant data leak through overlays. | Drive overlay providers must scope by organizationId; any provider returning cross-org data is a Sev-1. |
| Customer-visible writes are auditable. | Approval-gated tools insert into pending_approvals; all state-changing proposals route through modules/changes/. |
| Agent cannot talk over a human on the same channel. | Channel-specific echo rules surface as AGENTS.md fragments (e.g., WhatsApp Business App echo silence). |
| Agent cannot recursively wake itself. | add_note fan-out hard-filters self-mentions in notes.ts. |
| LLM provider lock-in is contained. | Single seam at wake/llm.ts: Bifrost gateway when BIFROST_* env vars are set, direct OpenAI / Anthropic / Google otherwise. |
A short index of properties that fall out of the design. Each one is a consequence of how the system is built, with no feature flag toggled on:
modules/*/tools/ enumerates.modules/messaging/agent.ts and read every conversation-lane tool, every AGENTS.md fragment, every file it can read, in two screens of source.@-mentions wake either humans or agents; a triage agent can hand to billing, which can hand to @billing-lead, which can hand back.vobase drive propose ... and an agent running vobase drive propose ... inside its sandbox execute the same code path with the same authz; only the audience tier differs.conversation (bound to a customer) or standalone (no customer present).inbound_message, staff_note, heartbeat, etc.). Mapped to a lane and a wake-reason cue.AudienceTier: 'contact' | 'staff' | 'admin'. Derived from (lane, triggerKind). Filters verbs and tools.WakeContext: per-wake fact bag handed to every materialiser factory. Identity, handles, lane-filtered slices.AgentContributions<WakeContext>: boot-time aggregate of all modules' agent slots (tools, materialisers, agentsMd fragments, roHints, listeners, sideLoad)./agents/<id>/skills/<name>/SKILL.md.systemHash: SHA-256 of the rendered system prompt. Held constant across a wake. Powers prefix-cache reuse.tool_execution_end. Staff notes and approval-resumed events hard-abort and re-wake instead.This describes the architecture you can verify against the platform — file paths, contracts, invariants. The platform code lives at github.com/vobase/vobase.
Custom AI agents, deployed in weeks. Singapore SMEs claim up to 50% PSG support; we handle the AIxDL claim on your behalf where it applies.
Free scoping. No commitment.