How It Works

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

The Flow

When a user asks a question, Pillar:

Actions

Actions 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 actions in your code with descriptions the co-pilot can understand:

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

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

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

export default actions;

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

Action Types

Pillar supports different action types for different use cases:

Handlers

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

invite_member: {
  description: 'Invite a team member',
  type: 'trigger_action',
  handler: (data) => {
    // This runs when the user triggers the action
    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.

Plans

When users ask for help with complex tasks, Pillar's co-pilot automatically chains your actions together into a Plan—a guided checklist that walks them through the process.

You don't define these workflows. You define small, focused actions. The co-pilot figures out how to combine them.

This is a key power of Pillar: define simple actions once, and the co-pilot composes them into complex workflows on the fly. No need to anticipate every multi-step task your users might need—just build the building blocks.

Context

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

• Smarter responses based on the current page or feature
• Action filtering based on user role or permissions
• Error-aware help 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 help.

Architecture Overview

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

What Lives Where

Your Frontend

• PillarProvider — Initializes the SDK with your project credentials
• defineActions — Registers actions 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 help content
• Action Registry — Synced definitions of available actions
• AI / RAG — Processes queries, retrieves relevant content, generates responses

Your Backend

• Your APIs and data, called by your action handlers when users trigger actions

Data Flow

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

2. Actions → Your Backend: When a user triggers an action, 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 action. 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 actions 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 Actions — Define actions for your app
• Plans — Learn about multi-step workflows
• Adding Context — Provide user context for smarter responses