How It Works

Pillar connects a co-pilot chat interface to your application's functionality through Tools.

The Flow

When a user asks a question, Pillar:

Tools

Tools are the core integration point between Pillar's co-pilot and your application. They represent things users can do—like navigating to a page, opening a modal, or triggering a workflow.

You define tools in your code with descriptions the co-pilot can understand:

// lib/pillar/tools/index.ts
import type { SyncToolDefinitions } from '@pillar-ai/sdk';

export const tools = {
  invite_member: {
    description: 'Open the invite team member modal',
    examples: ['invite someone', 'add a user', 'how do I add teammates?'],
    type: 'trigger_tool' as const,
  },

  view_settings: {
    description: 'Navigate to the settings page',
    type: 'navigate' as const,
    path: '/settings',
    autoRun: true,
  },
} as const satisfies SyncToolDefinitions;

export default tools;

When the co-pilot suggests a tool, users can click to execute it—or for simple navigations, it can run automatically.

Tool Types

Pillar supports different tool types for different use cases:

Handlers

Each tool has a handler—your code that runs when the tool is triggered:

invite_member: {
  description: 'Invite a team member',
  type: 'trigger_tool',
  handler: (data) => {
    // This runs when the user triggers the tool
    openInviteModal({ email: data.email });
  },
}

Handlers can do anything: call your APIs, update state, navigate, open modals. The co-pilot extracts relevant data from the conversation and passes it to your handler.

Context

Context tells Pillar what the user is currently doing, enabling:

• Smarter responses based on the current page or feature
• Tool filtering based on user role or permissions
• Error-aware responses when the user is facing an issue

pillar.setContext({
  currentPage: '/settings/billing',
  currentFeature: 'Billing Settings',
  userRole: 'admin',
  errorState: { code: 'PAYMENT_FAILED', message: 'Card declined' },
});

With this context, the co-pilot knows the user is on the billing page and can provide relevant assistance.

Architecture Overview

The Pillar SDK lives entirely in your frontend. It connects to Pillar's backend for AI capabilities, while your tool handlers connect to your own backend.

What Lives Where

Your Frontend

• PillarProvider — Initializes the SDK with your project credentials
• defineTools — Registers tools with descriptions the co-pilot understands
• setContext — Sends current page/user state for smarter responses
• PillarPanel — The chat UI component users interact with

Pillar Backend

• Knowledge Base — Your indexed documentation and content
• Tool Registry — Synced definitions of available tools
• AI / RAG — Processes queries, retrieves relevant content, generates responses

Your Backend

• Your APIs and data, called by your tool handlers when users trigger tools

Data Flow

1. SDK → Pillar: The SDK syncs your tool definitions and context to Pillar's backend. When users ask questions, the panel sends queries to Pillar for co-pilot responses.

2. Tools → Your Backend: When a user triggers a tool, the handler you defined runs in your frontend. That handler can call your own APIs, navigate pages, open modals—whatever you wrote it to do.

Key Concepts

What Happens When

When Pillar Doesn't Know

Sometimes users ask questions that Pillar can't fully answer—maybe there's no relevant documentation, or the request doesn't match any defined tool. Here's how Pillar handles these cases and how you can improve over time.

How the Agent Responds

When Pillar encounters a query it can't confidently handle, it will:

1. Acknowledge the limitation — Rather than making something up, Pillar tells the user it's unsure or doesn't have information on that topic
2. Offer alternatives — It may suggest related tools or point to general resources that might help
3. Invite escalation — Depending on your configuration, it can offer to escalate to human support. You can add a "Talk to Human" tab in the sidebar that triggers your existing support tools (Intercom, Zendesk, etc.) with the conversation history pre-filled. See the Human Escalation guide for implementation details.

Reviewing Failed Queries

The Pillar dashboard provides tools to identify and fix these gaps:

1. Conversations page — Review all user conversations with filtering by:

   • Negative feedback (thumbs down)
   • Abandoned conversations
   • Escalated requests

2. Query clustering — Pillar automatically groups similar queries, helping you spot patterns like "lots of users asking about X but we have no docs for it"

3. Reasoning traces — See exactly how Pillar processed each query: what it searched for, what sources it found (or didn't find), and why it responded the way it did

Creating Corrections

When you find a response that missed the mark, you can create a correction directly from the conversation view:

1. Open the conversation detail drawer
2. Select the relevant quotes from the conversation or reasoning trace
3. Write a correction explaining what the right answer should be

Pillar processes your correction and uses it to improve future responses to similar queries.

Next Steps

• React Quickstart — Get started with React
• Setting Up Tools — Define tools for your app
• Adding Context — Provide user context for smarter responses