Quickstart

Get a server-side tool running in 5 minutes. By the end of this guide, Pillar Cloud will be able to call a tool on your backend and return results to the conversation.

1. Install

# TypeScript
npm install @pillar-ai/server

# With Zod schema support (recommended)
npm install @pillar-ai/server zod zod-to-json-schema

# Python
pip install pillar-ai-server

2. Get your secret

Go to your agent settings in the Pillar dashboard and copy your server secret. It starts with plr_.

Set it as an environment variable:

export PILLAR_SECRET=plr_your_secret_here

3. Define a tool

Create a file for your Pillar tools. This example defines a lookup_customer tool that queries a database:

import { Pillar, defineTool } from '@pillar-ai/server';
import { z } from 'zod';

const pillar = new Pillar({
  secret: process.env.PILLAR_SECRET!,
  endpointUrl: 'https://api.myapp.com/pillar',
});

const lookupCustomer = defineTool({
  name: 'lookup_customer',
  description: 'Look up a customer by email address',
  input: z.object({
    email: z.string().email().describe('Customer email address'),
  }),
  execute: async ({ email }, ctx) => {
    const customer = await db.findByEmail(email);
    return { name: customer.name, plan: customer.plan };
  },
});

await pillar.registerTools([lookupCustomer]);

The SDK auto-registers your tools with Pillar Cloud on the first incoming request, so there is no separate deploy step.

4. Mount the webhook endpoint

Pillar Cloud sends tool calls to your server via HTTP POST. Mount the handler in your framework:

import express from 'express';
import { pillar } from './pillar-tools';

const app = express();
app.use(express.json());

app.post('/pillar', pillar.expressHandler());

app.listen(3000, () => {
  console.log('Pillar webhook listening on port 3000');
});

See Framework Integration for all supported frameworks.

5. Set your endpoint URL

In the Pillar dashboard, go to your agent settings and set the Server endpoint URL to the URL where your webhook handler is running (e.g., https://api.myapp.com/pillar).

Alternatively, pass it in code:

// TypeScript
const pillar = new Pillar({
  secret: process.env.PILLAR_SECRET!,
  endpointUrl: 'https://api.myapp.com/pillar',
});

# Python
pillar = Pillar(
    secret="plr_...",
    endpoint_url="https://api.myapp.com/pillar",
)

6. Test it

Open your app's co-pilot panel and ask: "Look up sarah@acme.com". The co-pilot should match the intent to your lookup_customer tool, call your server, and display the result.

Next steps

• Defining Tools — Zod schemas, type hints, guidance, and timeouts
• Confirmation Flows — Ask users to confirm before destructive actions
• Testing — Write tests for your server tools