> ## 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.

# SDK Overview

> Introduction to the ILLA SDK and its core building blocks

The ILLA SDK is the fastest way to add ILLA to your product. It wraps the Core API with chat session management, tool-result loops, context persistence, and polling helpers so you can focus on your product logic instead of request orchestration.

Use `IllaSDK` when you want one client that can:

* start and continue chats
* return `pendingTools` for your app to execute
* send tool outcomes back to ILLA
* poll long-running actions
* manage chat context for you

Use the lower-level SDK components only if you need custom transport, custom context storage, or tighter control over how requests are assembled.

## Install

```bash theme={null}
npm install @illalabs/sdk
```

## First request

Start with `IllaSDK`. It is the primary integration surface for most applications.

```ts theme={null}
import { IllaSDK } from '@illalabs/sdk'

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

const result = await sdk.sendMessage(
  'Swap 0.5 ETH to USDC',
  { userContext: { address: '0xYourAddress' } }
)

if (!result.response.isError) {
  console.log(result.response.data.text)
}
```

## What the SDK gives you

* `IllaSDK` for the full chat and tool loop
* `Chat` for lower-level request handling
* `CoreApiProvider` for HTTP transport and route overrides
* `ContextManager` for persisted chat state
* `Prompt` for structured user and tool messages
* `AsyncToolChecker` for long-running action polling

## Use lower-level components when needed

If you need custom transport, storage, or request construction, you can compose the building blocks directly:

```ts theme={null}
import {
  Chat,
  ContextManager,
  CoreApiProvider,
  InMemoryCache,
  Prompt,
} 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' },
})

const prompt = new Prompt({ text: 'Swap 0.5 ETH to USDC' })
const result = await chat.sendMessage(prompt)

if (!result.response.isError) {
  console.log(result.response.data.text)
}
```

## Next steps

* Read the [Authentication](/sdk/authentication) guide
* Follow the [SDK Quickstart](/sdk/quickstart)
* Learn the tool loop in [Handling tool execution](/sdk/guides/handling-tool-execution)