Quickstart

This guide shows how to use @ilana/sdk to send a governed query and inspect the response — including governance metadata. You can use this in any frontend: a chat interface, a search bar, a form assistant, or anything else.

Install the SDK

npm install @ilana/sdk

Create a Client

import { IlanaClient } from '@ilana/sdk';

const client = new IlanaClient({
  runtimeUrl: 'https://api.getilana.ai',
  token: 'your-embed-token',
});

You'll get your token from the admin portal after adding a partner domain to your agent.

Send a Query

const result = await client.query({
  botId: 'your-bot-id',
  input: 'What pricing plans are available?',
});

if (result.ok) {
  const { response, metadata } = result.data;

  // The AI response
  console.log(response);
  // "We offer three plans: Free, Starter, and Growth..."

  // Governance metadata — use this to build governance-aware UIs
  console.log(metadata.capabilityAllowed);  // true
  console.log(metadata.enforcementReason);  // null (no enforcement needed)
  console.log(metadata.schemaEnforced);     // true
} else {
  console.error(result.error.code, result.error.message);
}

The metadata object tells you how Ilana's governance engine handled the query — whether the capability was allowed, if any enforcement was applied, and whether the response conforms to the schema. This is what makes BYOFE powerful: you can build UIs that adapt based on governance state.

Multi-turn Conversations

Pass the conversationId from the first response to continue the conversation:

const first = await client.query({
  botId: 'your-bot-id',
  input: 'What pricing plans are available?',
});

if (first.ok) {
  const followUp = await client.query({
    botId: 'your-bot-id',
    input: 'Tell me more about the Growth plan',
    conversationId: first.data.conversationId,
  });
}

Choose Your Path

Building a custom UI? Continue to the SDK Reference or React SDK for the full BYOFE toolkit.
Just need a chat widget? Skip to the Embed Widget — add a <script> tag and you're done.
Want raw HTTP? See the API Reference for direct runtime API access.