perfox

Design Principles ​

Before you invest time building an agent, it helps to know the handful of decisions Perfox made upfront — decisions that are baked in, so everything you build inherits the same guarantees for safety and consistency.

This page is for architects, technical leads, and curious builders who want to understand why Perfox works the way it does, not just how to click through the Studio. No prerequisites; you can read it as an orientation before diving into any other section.

Configuration-as-behaviour: three layers ​

There is no code to write. An agent in Perfox is a graph of nodes — triggers, AI Agent, Email / SMS / WhatsApp Sender, Condition (IF/ELSE), Human Handoff, Collect Info, Look up Data, HTTP Request, Track Event, and more — that you assemble on a canvas in the Studio (go to Build → Agents) and then activate. Behaviour comes entirely from how you configure those nodes.

The design splits into three layers, each with one clear job:

LayerOwnsNever owns
AgentOrchestration and conversation flowBusiness knowledge
AI Agent nodeThe conversation engine — persona, language, tool selectionDomain knowledge
Your MCP toolsALL business logic and state, invoked through the MCP gateway—

A Condition (IF/ELSE) node can branch on flow-level signals, but it deliberately cannot branch on a raw business value like an order amount or a policy status. That kind of decision lives in one of your MCP tools, which returns the answer for the flow to route on. This keeps business rules in one place instead of scattered across the canvas.

Worked example — Acme Diagnostics booking flow. Asha, a workflow builder at Acme Diagnostics, sets up an agent that lets patients book lab tests.

  • Setup: Asha adds an AI Agent node with a booking persona and connects her booking server on its Integration port; the server offers a tool called check_slot_availability. She adds a Condition (IF/ELSE) node that routes on the tool's available / unavailable result.
  • Action: Priya messages the widget asking to book a blood panel for Thursday. The AI Agent node calls check_slot_availability, which returns { available: true, slot: "Thu 10 AM" }. The Condition (IF/ELSE) node sees available and routes to a WhatsApp Sender that sends the confirmation.
  • Result: Priya gets a confirmation message. The Condition (IF/ELSE) node never saw the slot time — it only saw the decision.
  • What just happened: the business rule ("is Thursday 10 AM open?") stayed inside the MCP tool. The canvas stayed generic. When the clinic changes its scheduling rules next month, Asha updates the MCP tool — not the canvas.

See Agents and MCP for a full walkthrough.

One consistent agent across every channel ​

Every conversation runs on the same engine. Whether a message arrives in the live preview, through a channel like WhatsApp or email, or lands on an AI Agent node inside a larger flow, it is handled the same way — the persona, tool use, and guardrails behave identically everywhere.

The AI Agent calls your tools in a loop, using the results to decide its next step, up to a safe iteration limit so a runaway tool sequence can never loop forever. Because voice and text share this single path, an agent you tune for chat behaves the same way on a phone call — nothing drifts out of sync between channels.

Your data is private and secure ​

Your workspace has its own exclusive addresses — a Studio host and an API host — and only requests on those exact addresses reach it. There is no shared identifier to spoof and no field to pass in a request body that could redirect traffic, so an embed script or webhook can only ever act as the workspace it was configured for.

Your data stays private to your workspace, by design.

Type safety end-to-end: one source of truth for every shape ​

Perfox is built in strict TypeScript, and for every entity in the system there is exactly one definition of its shape. That single definition does three jobs at once:

  1. It validates the data your API calls send and receive.
  2. It validates the fields in the Studio forms you fill out.
  3. It validates every record before it is written to your database.

Because the same definition drives all three, a field you see in a Studio form, the value the API accepts, and the record stored in your database can never disagree. The Studio's API client is generated directly from the backend, so the two always share the same contract — a mismatch surfaces immediately rather than as a silent bug in production.

A direct, validated data layer ​

Perfox talks to your database directly rather than through a heavyweight mapping framework. Reads and writes go through a small, typed set of operations, and every write is validated against the one canonical shape for that entity before it lands. The result is a thin, predictable data layer with no hidden translation step between what you configure and what is stored.

Time-sortable IDs everywhere ​

Every identifier in Perfox — for a conversation, an agent, a file, anything — is a globally unique, time-sortable ID. Because these IDs sort in the order the records were created, timelines and histories stay in the right order naturally, and there is never a collision between two records.

Zero duplication across a layered codebase ​

Perfox is organised into clean layers that build on one another:

Every type, option, and constant is defined exactly once in the foundation and reused everywhere above it — so a concept like a channel or a status has one agreed definition. The layering is enforced automatically: the interfaces you use (the Studio and the embeddable widget) can never reach down into infrastructure internals, which keeps the surface you interact with clean and stable.

BYOP — Bring Your Own Provider ​

For the providers your agent talks through, you connect your own accounts and Perfox uses them on each request: Plivo for phone, SMS and WhatsApp, your email provider, your file storage and databases, and Google Sheets. You connect them on Admin → Connections. Perfox never falls back to a shared account. If a provider isn't connected, Perfox tells you exactly which one is missing rather than failing silently. Your keys are encrypted at rest.

The AI models your agents use are included and managed by Perfox, so there are no model keys to bring. Storage for uploads and recordings, semantic search and web voice are managed by Perfox too. See BYOP.

Identity is a decision, never an assumption ​

When you embed the widget, the identity details you pass in are all optional: a display name (shown to the user, but not treated as proof of who they are), a phone (E.164 preferred; looser formats are normalised for you), an email, an external_id (the stable anchor that ties a person to your own records, and the field a secure signature protects), and a free-form attributes map for anything else you want to carry.

Rather than assume a visitor is who they claim, Perfox assigns each conversation a trust level — anonymous, self-asserted, or verified — so your agent and your tools always know how much to rely on the identity. Whatever is known is attached to the conversation and forwarded to your MCP tools with each call, so your business logic always sees the current, trusted context. See User Context & Identity.

Memory that follows the customer, not a copy of your data ​

Every agent remembers the people it talks to: what they've shared, their preferences, and what earlier conversations covered. Because Perfox recognises one customer across every channel, that memory follows them from web chat to WhatsApp to a phone call. It's on by default, and you control each kind of memory per agent. See Agent Memory.

What memory deliberately does not do is copy your business records. Order status, balances, bookings and results stay in your own systems and reach the agent live through your MCP tools, so the agent never answers from a stale copy.

You now have the full picture ​

You can build agents knowing the channel, the data layer, the identity model, and the provider wiring all follow a consistent set of rules — configured by you, not hardcoded around you.