Search documentation

Search documentation

Core SDK@pillar-ai/sdk

Other

API items not yet assigned to a domain. These need to be categorized.

typescript
import Pillar from '@pillar-ai/sdk'

Methods

Pillar.getTools()

Get all registered tools for debugging. Returns tools from all sources: defineTool(), registerTool(), and onTask() handlers. Only available when debug mode is enabled.

typescript
getTools(): ToolInfo[]

Returns

ToolInfo[]

Pillar.executeToolForDebug()

Execute a tool by name for debugging purposes. Only available when debug mode is enabled.

typescript
executeToolForDebug(toolName: string, input: Record<string, unknown>): Promise<{ success: boolean; result?: unknown; error?: string }>

Parameters

toolName
requiredstring
- Name of the tool to execute
input
requiredRecord<string, unknown>
- Input parameters to pass to the tool

Returns

Promise<{ success: boolean; result?: unknown; error?: string }>

Pillar.defineTool()

Define a tool with co-located metadata and handler. This is the recommended way to register tools. The metadata (name, description, inputSchema) is discoverable by the CLI scanner (`npx pillar-sync --scan ./src`) and the handler runs client-side. If `execute` returns a value, it is automatically sent back to the agent — no explicit `returns: true` flag needed.

typescript
defineTool(schema: ToolSchema<TInput>): () => void

Parameters

schema
requiredToolSchema<TInput>
- Tool schema with metadata and execute handler

Returns

() => void

Pillar.registerTool()

Register a tool definition at runtime.

typescript
registerTool(tool: { name: string } & Record<string, unknown>): void

Parameters

tool
required{ name: string } & Record<string, unknown>
- Tool definition with name and properties

Pillar.getRegisteredTool()

Get a registered tool definition by name.

typescript
getRegisteredTool(name: string): Record<string, unknown> | undefined

Parameters

name
requiredstring
- Tool name

Returns

Record<string, unknown> | undefined

Pillar.completeTool()

Signal that a tool has completed. For simple tools, this emits the completion event. For wizard tools (modals, multi-step flows), call this when the user finishes the flow.

typescript
completeTool(toolName: string, success?: boolean, data?: Record<string, unknown>): Promise<void>

Parameters

toolName
requiredstring
- The tool identifier
success
boolean
- Whether the tool completed successfully (default: true)
data
Record<string, unknown>
- Optional result data

Returns

Promise<void>

Pillar.sendToolResult()

Send tool result back to the agent. Called automatically for tools with `returns: true` after their handler completes. The result is sent to the agent for further reasoning.

typescript
sendToolResult(toolName: string, result: unknown, toolCallId?: string): Promise<void>

Parameters

toolName
requiredstring
- The name of the tool that was executed
result
requiredunknown
- The result data to send back to the agent
toolCallId
string
- Unique ID for this specific tool invocation (for result correlation)

Returns

Promise<void>

Pillar.executeQueryTool()

Execute a query tool and send the result back to the agent. This is called when the agent sends a `query_request` event. Query tools are expected to return data that the agent can use for further reasoning.

typescript
executeQueryTool(toolName: string, args?: Record<string, unknown>, schema?: { properties?: Record<string, unknown>; required?: string[] }): Promise<void>

Parameters

toolName
requiredstring
- The name of the tool to execute
args
Record<string, unknown>
- Arguments for the tool
schema
{ properties?: Record<string, unknown>; required?: string[] }
- Optional schema for parameter validation

Returns

Promise<void>