How Objx Works

Create agents from the app: go to New Agent and choose a blank agent, a template (e.g. SimpleLoop, OB1 Clone, Customer Service), or import from JSON. Each agent has a name and optional description. After creation, open the agent to configure flows, knowledge bases, and options.

On the agent settings page:

• Chat UI tab — Main Features (Realtime Voice, audio transcription, file uploads, user model selection, image generation) and Display Settings (voting, costs, model name, profile icon, flow selector in input, input prompt size, image-only mode, task drawer). A live preview updates as you change options. See ObjxChat for layout and input size details.
• Models tab — Available models and default model (when user selection is allowed)
• General tab — Twilio Voice (SIP): enable incoming phone calls via OpenAI SIP; requires Realtime Voice to be enabled on the Chat UI tab. Configure webhook URL and secret in platform.openai.com.

Agent context (system context), welcome message, suggestions, and visibility (public, shared, published) are set on the General tab. Save changes with the header Save button.

From the agent's General tab, open Flows and create or edit a flow. The Flow Board is a canvas where you add nodes and connect them. Execution starts at the Start node. Use the inspector panel when a node is selected to edit its content and options.

Flow node types

• Start — Entry point (auto-created)
• Message — Output text/markdown to the user; supports variables like ${lastInput}, ${lastResponse}
• Image — Display an image in chat
• Prompt — Wait for user input; stores response in a variable (e.g. lastInput)
• Model — Call an LLM with system message, temperature, model; optional tools (e.g. KB search, route thread, update capture fields)
• Knowledgebase (Database) — Vector search over a knowledge base; query can use variables
• Directory Category Listing — Shows categories with document counts; clicking a category adds a document listing widget
• Directory Document Listing — Shows a paginated list of documents from a selected category
• Intent Database — Search intent phrases across flows for routing
• Goto Flow — Jump to another flow by name
• Switch — Branch by regex, cosine similarity, or LLM
• Phrase — Branch destination with optional flow navigation
• Branch — Tool-based branch destination
• Agent Memory — GET/PUT/APPEND agent memory by key
• Avatar — Control avatar (toyHead) behavior
• Button Switch / Button Branch — Interactive buttons and destinations
• Redirect — Redirect browser to a URL
• Realtime Voice — Speech-to-speech with OpenAI Realtime API
• Update Capture With Schema — Update thread capture fields with a JSON schema
• Update Captured Relationships — Append document relationships to capture fields (e.g. after KB search)

Define flow variables in the flow header (Variables button). Use ${variableName} in node content. Test with the Play button to open a chat sidebar and run the flow.

Knowledge bases hold documents that are chunked and embedded for semantic search. You can use agent-specific knowledge bases (from the agent's Knowledge Bases card) or shared knowledge bases from the app Knowledge Bases page.

Add content as FAQ (Q&A pairs), PDF uploads, URL (web page), or Object (a generic type for things like products or objects of interest; you can set an optional subtype to specify the kind of object). The site processes and indexes the content so your flows can search it. In a flow, add a Knowledgebase (Database) node, select the knowledge base, and set the search query (e.g. ${lastInput}). The node outputs relevant chunks for use in later nodes (e.g. passed into a Model node as context). You can also attach a KB Tool to a Model node so the LLM can search the knowledge base via a tool call.

When you add a KB Tool node and open its inspector, you can set Return type: Documents (Description) returns only document-level records (title, description, LLM instructions, and other document fields) up to the return limit, with no per-chunk content—useful when the model should work from document summaries. Document Chunks returns the usual chunk-level results (chunk text, order, similarity) plus document info, so the model can cite or quote specific passages. The same setting applies when the KB tool is used from a Realtime Voice node (e.g. in-call or Twilio).

Document description, summary, and LLM instructions

Each knowledge base document has a description (overview or full text), an optional summary (a short one-sentence summary of the description), and optional LLM instructions. The description and summary are shown on the document card and detail page and are included in the text used for search embeddings when you save from the ingestion board. LLM instructions are instructions for the AI when it uses this document (e.g. "Prefer citing the source URL" or "Summarize in one sentence"). LLM instructions are not included in the embedded summary used for search—they are only returned with the document when the KB search tool or Show Document tool returns it, so the model can follow them when answering. You can set or edit these fields in the document edit modal (ingestion workboard or document card) and on the document detail page. For documents of type Object, you can also set an optional subtype (e.g. product, object of interest) to further classify the document.

Show Document tool

The Show Document tool lets the LLM display a knowledge base document in the chat as a card. The card shows the document title, a truncated description, a thumbnail (if the document has a blob), contact details (phones with optional labels such as Phone, Cell, Fax, or custom, email, website, social links) and hours (when set) as badges or text, and its relationships to other documents. Clicking the thumbnail opens it in a lightbox; clicking the card opens a focus view; clicking a relationship opens the linked document in a lightbox. Enable it in the flow: select a Model node, open Configure Tools, and turn on Show Document. You can also enable or disable it from the agent's Tools card (Settings).

Document categories

Each knowledge base has a Categories tab where you can define hierarchical document categories (e.g. to organize or filter documents). Click Manage categories to open a large modal with a tree list: you can add root or child categories, edit names, and delete. You can Export all categories to a JSON file (with IDs, parent–child links, and properties) and Import from a JSON file. Import never overwrites existing categories by ID; it only creates new categories for IDs that are not already in the knowledge base. Parent–child relationships are preserved when the parent exists in the KB or is created in the same import.

When editing a document (document detail page), you assign categories via a row of badges (each with a close control to remove) and an Add button next to the Categories label. Clicking Add opens the same category select modal (large, with search and a hierarchical tree). Select one or more categories with checkboxes, then OK to apply or Cancel to close without saving.

Document type schema

Each knowledge base has a Schema tab where you configure which document types agents can use and what fields each type supports. Document types are listed on the left: built-in types (FAQ, PDF, URL, Business, Event, Location, and others) have enable/disable switches; custom types you add appear in the same list with a delete control. Use Add type at the bottom of the list to define a new custom type with your own JSON Schema.

Select a type to open its inspector on the right. The inspector shows the merged JSON Schema for that type (what the KB Tool schema tool exposes to the agent) and an Additional fields editor where you extend the type with extra properties. JSON is edited with the same structured tree editor used elsewhere in Objx (tree view or raw JSON). Enable the schema tool on a KB Tool node (toolcall edge to the model) so the agent can discover allowed types and fields before creating or updating documents.

For a work memory knowledge base, a common setup is to enable only Object, Person, and URL. The agent saves most information as object documents with a freeform subtype label (for example note for general facts, or project, snippet, and others). Subtypes are chosen by the agent at capture time—they are not configured on the Schema tab. Use person for people and URL for links (with the URL field set).

In the main header of a knowledge base page (when on the Documents tab), the List / Card / Graph view switcher controls how documents are displayed. This applies uniformly to both the full document list and search results: when you search, the selected view persists and the same table, card grid, or graph is used to show the search results. List shows a table (with a Similarity column when showing search results); Card shows a grid of document cards; Graph shows an interactive force-directed graph of documents and their relationships. On the Documents tab, the graph view shows only this force-directed layout (there is no separate layout switcher inside the graph).

Ingestion modal

When you open a knowledge base from an agent, the header shows a green Ingestion button. Clicking it opens a full-screen ingestion modal with three columns: the agent’s ingestion flow chat (left), the thread’s captured fields JSON (center), and the workboard (right). The ingestion flow is configured in the agent’s Settings (Ingestion flow). The flow can capture documents and document relationships into the thread’s capture fields.

Ingestion Engine (queue)

On the agent knowledge base page, the Ingestion tab can show a Queue column (toggle with the Queue button in the header). When the queue is on, submissions are queued and processed in order. The left column becomes the Ingestion Engine: a title, a status label (Ready, Processing thread, Waiting for items, or Updating status), a Start/Stop button, an input to add items (text or URL), and a table of threads in the queue. Each row shows a status icon (waiting, processing, review, saved, ready, rejected) and a truncated preview of the first message.

Processing does not start automatically. Click Start to begin processing the queue; the engine will pick the oldest waiting thread, run the ingestion flow, and continue with the next when the stream completes. Click Stop to stop after the current item (or immediately if the engine is idle with no thread being processed). While the engine is running, the status label updates through each phase (e.g. Processing thread, Updating status). The thread list cannot be clicked to view other threads while the engine is running—only the processor chat for the current thread is shown. When the engine is stopped, you can click any row to view that thread’s history and captured fields in read-only mode.

When the engine is processing a thread, the middle column shows the live queue processor chat with streaming responses. When processing finishes, the thread’s status becomes ready. You can then use Save to persist documents to the knowledge base (Save is disabled while a thread is waiting or processing, or after it is already saved). The blue Review button sets the thread’s status to review; the red Reject button sets it to rejected. After saving, the engine continues with the next item if it is still running.

The workboard shows a graph of document cards with relationship lines and labels (e.g. references, related_to, parent_of) between them based on document_relationships in the captured fields. Use the layout selector to choose Force (animated force-directed layout) or Masonry (static grid). In Force mode, cards are arranged with a force-directed layout that animates into place over a short period. The largest card (by content size) stays in the center; others arrange around it. Cards repel each other while connected documents attract, balancing into a stable layout. A red border marks the board boundary; cards stay inside it.

Cards are draggable—use the grip handle in the top-right corner of a card to reposition it; positions are kept for the current session. Click a card to edit its content (title, description, URL, type, etc.). Saving an edit updates the captured fields and persists them to the thread.

When the ingestion flow marks a document as an update to an existing record (new version), the modal header shows a flashing warning icon and the card displays a diff of the current workboard version against the version already stored in the knowledge base: additions are highlighted in green, deletions in red (with strikethrough), and any field that changed is visually highlighted. This lets you review changes before saving.

Use the header Save button to persist all documents and document relationships from the workboard into the knowledge base. Existing documents (by ID) are updated; new documents are created. Relationships are written to the knowledge base’s document links. After a successful save, for each new document, a chunk is created from the title and description, and embeddings are generated in the background. The thread’s capture fields are updated with the real document IDs. A popup in the bottom-right corner shows chunking progress (e.g. 2/5 documents). When complete, the modal closes and the documents table refreshes. Document cards can include address (street, city, province, postal code), contact (phones with optional labels such as Phone, Cell, Fax, or custom, email, website), social media (Facebook, Instagram, X, LinkedIn), and hours (one line per day of the week, e.g. "9:00 AM – 5:00 PM" or "Closed", plus optional notes for holidays or exceptions). These fields are editable in the card edit dialog and appear in the card view and document detail page. The searchkb tool returns these fields when querying the knowledge base.

Captured documents can include category IDs (UUIDs of this knowledge base’s document categories). When present, those categories are shown as badges on each document card on the workboard and in the edit document modal. When you save to the knowledge base, document–category relationships are created or updated so the document appears under those categories in the Documents tab.

Prompts are stored content (text, image, sound, video) that users can load into the chat input and send. Create and manage them from the Prompts page. Each prompt has a name, description, content type, and prompt content; you can attach an image and files. When a user loads a prompt in ObjxChat, its content and files are sent as the next message. Prompts can be shared and published for use across the tenant.

You can embed your agent’s chat on your own site so visitors can talk to the agent without leaving the page. Make the agent public in its settings, then use the embed or popup option provided by Objx (e.g. a link or script you add to your site). On WordPress, use the Objx plugin’s shortcode to place the chat widget on any page and optionally set a starting prompt and title. Visitors get a working chat that runs your flows and knowledge bases.

Control how the embedded chat looks (logo, colors, etc.) in the agent’s Popup tab under popup settings.

Attach a KB Tool node to a Model node via a toolcall edge. The agent gets tools to search, list, load, update, updateRelationships, new, save, and schema documents in that knowledge base's memory bucket. Enable Load and Save on the KB Tool for full read/write workflows. Use Preloaded documents on the KB Tool to pin specific documents into context when the model runs. The inspector shows only documents you have already chosen; click the database icon next to Preloaded documents to open a search dialog (text search by title, or semantic search by meaning) and select documents from the knowledge base.

On the Model node, enable Include Memory Context to inject scalar captured fields and per-KB document summaries into the system prompt. View loaded documents on the flowboard objx-board (ingestion panel) grouped by knowledge base, or use the compact context tray for a line list. In chat, open the Thread Memory drawer (when a flow is active) for scalar fields and a document tray.

On public embed bots, documents and fields marked private (including internal KB documents) are hidden from anonymous visitors; agent owners see the full context.

Each agent can have thread channels (ObjxThreadChannel): named groups (with optional icon and description) used to route and view threads. On the agent's Threads tab (Tickets board), create and edit channels in the first column. Threads can be assigned to at most one channel. In a flow, enable the Route Thread tool on a Model node; the LLM can then call routeThread(toChannel) with a channel ID to move the current thread into that channel. Use Update Capture Fields on the Model node so the LLM can call updateCaptureFields(keysAndValues) to store scalar lead data on the thread. For document-shaped memory, use KB Tool nodes (update, updateRelationships, save) instead of the removed Update Capture Document toggle. Enable Include Memory Context to append thread memory to the system prompt. Finish Capture signals scalar capture completion. Channels are listed in the Threads tab so you can filter and manage leads by channel.

Open the agent and go to the Threads page to manage conversations by customer and channel. Use the search bar, status filters, type filter, and the eval filter to focus on exactly the threads you want. You can also change sorting (date, user, eval score, cost, or message volume) and switch to Group by user to review every customer conversation together. The channels panel can be collapsed when you want more space for the list and inspector.

The Threads page also shows an eval summary strip for the currently visible list, including evaluated count, average score, pass rate, and not-evaluated volume. Click any thread to inspect messages, fields, notes, costs, and full eval history in one place.

For agent-wide quality reporting, open Evaluations in the agent sidebar. This report includes score distribution, category averages, common critical failures, top improvement priorities, and trend over time.

From the agent sidebar, open Grid Activity to see a dense grid that fills the viewport: each row is a thread (user icon in the first cell), and each subsequent cell is an icon for that thread's messages (user text, image, assistant response, tool call, etc.). The grid paginates to fit the visible area—no scroll bars. Use the header controls to change cell size (Sm 16×16, Md 32×32, Lg 64×64), refresh rate (30s, 60s, 120s), and manually refresh. New threads and new messages animate in and play distinct sounds per type. The view updates on a timer; a countdown shows seconds until the next refresh.