Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Models and Demos

Chatbots with ChatInterface

Build a chat UI with gr.ChatInterface: the fn(message, history) signature, messages format, streaming replies, system prompts, extra inputs and a runnable chat-loop stand-in.

A chatbot needs more than one box in and one box out: it needs a scrolling conversation, a message input, a send button, a way to retry and clear, and a history your function can read. gr.ChatInterface provides all of this around a single function, so a working chat demo can be about ten lines long.

The real Gradio cannot run on this site, so the Gradio snippets are read-only. The runnable blocks implement the history and streaming logic in plain Python with a rule-based bot, labelled as a stand-in for a language model.

The smallest chatbot

Python
import gradio as gr

def respond(message, history):
    return f"You said: {message}"

demo = gr.ChatInterface(fn=respond, type="messages")
demo.launch()

Opening the page shows an empty chat area and a text box at the bottom. Typing "hi" and pressing Enter adds a user bubble and a bot bubble reading You said: hi. The bot bubble has copy, retry and undo buttons, and a clear button resets the conversation.

The function gets two arguments:

  • message: the newest user message (a string; a dict if multimodal).
  • history: everything said before, in the format set by type=. With type="messages" it is a list of dictionaries such as {"role": "user", "content": "hi"} and {"role": "assistant", "content": "..."}, the same shape as chat APIs. Newer Gradio versions use this format by default; the older "tuples" format ([[user, bot], ...]) is deprecated, so set type="messages" explicitly to be sure.

The history does not include the new message, and it is sent by the browser on every request. The server does not remember the conversation, which is why chat works the same for many visitors at once.

Calling a language model

For a hosted model, convert the history into the API's message list and return the reply. The OpenAI-compatible pattern looks like this:

Python
from openai import OpenAI
client = OpenAI()      # reads OPENAI_API_KEY from the environment

def respond(message, history, system_prompt):
    messages = [{"role": "system", "content": system_prompt}]
    messages += history                       # already role/content dicts
    messages.append({"role": "user", "content": message})
    reply = client.chat.completions.create(model="gpt-4o-mini", messages=messages)
    return reply.choices[0].message.content

demo = gr.ChatInterface(
    respond,
    type="messages",
    additional_inputs=[gr.Textbox("You are a helpful tutor.", label="System prompt")],
    title="Tutor bot",
    examples=[["Explain recursion", "You are a helpful tutor."]],
)

additional_inputs adds controls (shown in a collapsible "Additional Inputs" section under the chat) whose values are passed to respond after message and history. Because history already uses role and content keys with type="messages", no conversion is needed. Keep the API key in an environment variable, never in the file.

Streaming replies

Language models are slow, so show words as they are produced. Make the function a generator that yields the growing reply:

Python
def respond(message, history):
    partial = ""
    for chunk in stream_from_model(message, history):
        partial += chunk
        yield partial

Gradio replaces the bot bubble with each yielded value, so the text appears to type itself. Yield the full text so far, not just the new piece.

Python History and streaming, without a model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

After two exchanges the history holds four dictionaries. The first reply says message number 1, and the second one answers the name question. This loop is what the Gradio front end does for you: call the function, collect the last yielded value, and append both messages to the history.

Trimming long histories

Every request carries the whole history, and models have a limited context window. Keep the most recent turns, and always keep the system prompt:

Python Keep the last N turns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Only questions 4 and 5 and their answers remain. Smarter versions count tokens instead of turns, or summarize old turns into one message.

Multimodal and customization

  • multimodal=True turns the input into a box that accepts files; message becomes a dict with "text" and "files" keys.
  • chatbot=gr.Chatbot(height=500, placeholder="Ask me anything") customizes the conversation area.
  • textbox=gr.Textbox(placeholder="Type here", container=False, scale=7) changes the input.
  • fill_height=True makes the chat use the whole window.
  • For full control (side panels, several chats), build the same thing yourself with gr.Chatbot inside Blocks. That uses events and state, and the final project in this chapter, the chat assistant, does exactly that.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What are the first two arguments of a ChatInterface function?

    fn(message, history, *additional_inputs) is the signature.
  2. 2. With type="messages", what is one history item?

    Each item looks like {"role": "user", "content": "hi"}.
  3. 3. To stream a reply, the function should:

    Each yielded value replaces the bot bubble, so yield the full text so far.
  4. 4. Where do additional_inputs values arrive?

    Extra input values are passed after message and history.

Summary

  • gr.ChatInterface(fn, type="messages") gives a complete chat UI for fn(message, history).
  • History is sent by the browser each time and uses role/content dicts.
  • Yield partial text to stream; trim history to respect context limits.
  • Use additional_inputs for system prompts and sliders; use Blocks and gr.Chatbot for custom layouts.

Next: Streaming and Progress