Skip to content
Nebulas Docs

How it works

Nebulas Kit is the part of Nebulas that lives on your own website. It lets a visitor chat with the assistants of one of your workspaces, or fill in a widget you built in Studio, without leaving your site.

The kit has two halves: React components that run in your visitor’s browser, and server handlers that run on your own backend (Next.js route handlers or an Express router).

 Visitor's browser                Your server                      Nebulas
┌────────────────────┐        ┌──────────────────────────┐      ┌────────────────────┐
│ <A2AChatFloating/> │──POST─▶│ /api/a2a                 │─────▶│ A2A agent          │
│                    │  GET  ▶│ /api/a2a/config          │      │ (orchestrator)     │
│                    │        │                          │      │                    │
│ <NebulasSurface/>  │──POST─▶│ /api/nebulas-surfaces/*  │─────▶│ Surfaces API       │
│                    │        │                          │      │ (widgets, forms)   │
└────────────────────┘        │ + adds credentials       │      └────────────────────┘
                              │   (API key, service      │
                              │    token or user token)  │
                              └──────────────────────────┘

Why the server in the middle?

Section titled “Why the server in the middle?”
  • Your credentials never reach the browser. The Nebulas API key and service account keys stay in your server’s environment. The handler adds them to each forwarded request.
  • Only a few endpoints are exposed. The surface handler forwards three routes (render, actions, theme) and returns 404 for everything else. Your public contact form can’t be used to reach the rest of the Nebulas API.
  • You choose who the caller is. The same components work for an anonymous visitor on a marketing site (the app calls Nebulas as itself) and for a signed-in user (the call carries that user’s identity). See Authentication.

Key concepts

Section titled “Key concepts”

Agent (A2A) : The AI assistant that answers chat messages. Nebulas hosts it and speaks the Agent-to-Agent (A2A) protocol. A2A_URL points at it, usually https://aisearch-api.nebulas.ai/v1/orchestrator/a2a.

Project : The Nebulas project that stores chat conversations. It is set with NEBULAS_PROJECT_ID.

Surface / Widget : A piece of UI built in Nebulas Studio: a form, a report, a list. Studio calls it a widget. The code and API call it a surface. Each one has a name (for example contact_sales) and an id. It also has a handler that runs server-side when it’s submitted.

Brand profile : A design system (colors and fonts) stored in Nebulas. The chat and surfaces can use it. See Branding.