DOCSEARCHbyAlgolia
Submit Docs

Chainlit Documentation

website·Indexed Apr 14, 2026

https://docs.chainlit.io/

Chainlit is an open-source Python framework for building conversational AI applications and LLM-powered interfaces. Documentation covers getting started guides, deployment, core concepts including LangChain integration, and advanced features like authentication, data persistence, backend customization, streaming, multi-modality, and MCP integration. Includes comprehensive API references for actions, chat profiles, elements (audio, file, image, PDF, Plotly, Pyplot, Dataframe), and custom data layers.

Tokens
37.4K
Snippets
113
Records
361
Agent score
50%

What's inside Chainlit

  1. Message concept in Chainlit

    A Message is a piece of information sent from the user to an assistant and vice versa. Messages are the building blocks of a chat, coupled with lifecycle hooks. Each message has content, a timestamp, and cannot be nested.

  2. Chainlit Chat Lifecycle Overview

    A chat session in Chainlit goes through a lifecycle of events: start, message, stop, end, and resume. You can respond to each stage by defining hooks using decorators like @cl.on_chat_start, @cl.on_message, @cl.on_stop, @cl.on_chat_end, and @cl.on_chat_resume. Chat resume requires authentication and data persistence to be enabled.

  3. Step Decorator Overview

    The @cl.step decorator logs steps based on the decorated function. By default, function arguments become the step input and the return value becomes the step output. Internally it uses the cl.Step class. Steps can be nested, have their input/output overridden, and support real-time output streaming.

  4. Multi-modality support in Chainlit

    Chainlit supports multi-modality beyond text, including images, videos, audio, and files. This enables building chatbots that can process and generate multiple content types. Voice assistants are created using the @cl.on_audio_chunk decorator to access the user's microphone audio stream in real-time.

  5. Step concept in Chainlit

    Steps represent individual units of work or tasks within a conversation flow. Unlike Messages, Steps have a type, input/output, and start/end timestamps. Steps provide visibility into application execution by displaying the chain of thought. The visibility of steps is controlled by the config.ui.cot setting, which can show the full chain, hide it, or show only tool calls.

  6. Chainlit v2.0.0 migration overview

    Chainlit v2.0.0 rewrites the UI (including the copilot) with Shadcn/Tailwind. Benefits include a simpler codebase, new custom element feature, and more powerful theme customization. To upgrade, run pip install --upgrade chainlit.

  7. Enable authentication in Chainlit applications

    Chainlit applications are public by default. To enable authentication and make your app private: (1) Define a CHAINLIT_AUTH_SECRET environment variable using chainlit create-secret to generate a secret string for signing authentication tokens. Changing this secret logs out all users. (2) Add one or more authentication callbacks to your app. Each callback takes different input and optionally returns a cl.User object. If the callback returns None, authentication fails. Ensure each user has a unique identifier to prevent data sharing.

  8. Human feedback benefits for LLM apps

    Human feedback provides four key benefits: (1) Dataset Creation - feedback interactions generate training data to improve agent responses over time; (2) Accuracy Measurement - feedback scores enable objective comparison of different agent versions; (3) User-Centric Development - direct feedback ensures the model evolves to meet user needs; (4) Training and Fine-Tuning - human feedback supports direct model training based on specific interactions.

  9. Command concept and attributes

    Commands capture user intent in a deterministic way. They have the following attributes:

    • id (str): Identifier for the command, used in the UI
    • icon (str): Lucide icon name (see lucide.dev/icons/)
    • description (str): Human-readable description of the command
    • button (boolean): Whether to display the command as a button in the message composer
    • persistent (boolean): Whether to keep the command active after the user sends the message

  10. User session overview and purpose

    The user session persists data in memory through the lifecycle of a chat session. Each user session is unique to a user and a given chat session. Use cl.user_session.set(key, value) to store data and cl.user_session.get(key) to retrieve it. This avoids the problem of shared global state where multiple concurrent users would overwrite each other's data.

  11. Ask User feature overview

    The Ask User feature in Chainlit prompts users for input during conversations. Depending on the API used, user input can be a string, file, action selection, or form data. Both the UI and your code are blocked until the user provides input.

  12. Chainlit Cookbook Repository Overview

    The Chainlit Cookbook is a GitHub repository (https://github.com/Chainlit/cookbook) containing example projects that demonstrate Chainlit's capabilities for building LLM applications. Each example resides in its own folder and showcases integrations with OpenAI, Anthropic, LangChain, LlamaIndex, ChromaDB, Pinecone, and other tools. Use these examples as tutorials or starting points for building your own conversational AI applications.