Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.illa.io/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through creating a complete chat flow with the ILLA SDK. The simplest way to build a chat flow is with the IllaSDK class.

​
1) Initialize the SDK

import { IllaSDK } from '@illalabs/sdk'

const sdk = new IllaSDK({
  apiKey: process.env.ILLA_API_KEY!
})

​
2) Start a conversation

const result = await sdk.sendMessage(
  'What can I do on Base?',
  { userContext: { address: '0xYourAddress' } }
)

// Save the chatId to continue the conversation
const chatId = result.chatId

if (!result.response.isError) {
  console.log('Assistant:', result.response.data.text)
}

​
3) Continue the conversation

const followUp = await sdk.sendMessage(
  'Swap 0.1 ETH to USDC',
  { chatId }
)

if (!followUp.response.isError && followUp.response.data.pendingTools) {
  // Handle tool execution - see Handling Tool Execution guide
  console.log('Tools to execute:', followUp.response.data.pendingTools)
}

​
4) Retrieve message history

const messages = await sdk.getMessages(chatId)
console.log('Conversation history:', messages)

​
5) Multiple chats

// Track multiple conversations
const chatIds = sdk.chatIds
console.log('Active chats:', chatIds)

// Send messages to different chats
await sdk.sendMessage('Hello', { chatId: chatIds[0] })
await sdk.sendMessage('Hi there', { chatId: chatIds[1] })

​
Advanced: Using Chat class

For more control, you can use the lower-level Chat class directly.

​
1) Initialize the components

import {
  Chat,
  ContextManager,
  CoreApiProvider,
  InMemoryCache,
} from '@illalabs/sdk'

const provider = new CoreApiProvider({
  headers: { 'x-api-key': process.env.ILLA_API_KEY! },
})

const context = new ContextManager(new InMemoryCache())

const chat = new Chat({
  coreApiProvider: provider,
  contextManager: context,
  userContext: { address: '0xYourAddress' },
  // optional:
  // id: 'my-chat-id',
  // defaultRole: 'user',
})

​
2) Send messages

import { Prompt } from '@illalabs/sdk'

const first = await chat.sendMessage(
  new Prompt({ text: 'What can I do on Base?' })
)

// Inspect returned shape
if (!first.response.isError) {
  console.log('Assistant:', first.response.data.text)
}

// Follow-up
const second = await chat.sendMessage(
  new Prompt({ text: 'Swap 0.1 ETH to USDC' })
)

// Handle potential tool execution
if (!second.response.isError && second.response.data.pendingTools) {
  console.log('Tools to execute:', second.response.data.pendingTools)
}

​
3) Persisted context

The chat automatically persists message history using the ContextManager. You can snapshot or restore it as needed. 
const snapshot = await chat.getContext()
// ... store snapshot ...
await chat.setContext(snapshot)

​
4) Long‑running actions (optional)

If your prompts can trigger on-chain actions, add an AsyncToolChecker and use chat.awaitAction or subscribe for progress. See: Awaiting actions & polling