Skip to content

Getting started with Hadron

Portal onlyBeginner~20 min

By the end of this tutorial you'll have a chatbot agent that greets you, asks your name, and remembers it across sessions — running entirely in the Hadron portal, no integration code required. Plan on about twenty minutes, most of it waiting on you to fetch an LLM API key.

You will:

  1. Sign in to the portal and pick, create or join an organization (or, to start without one, see Start without an organization).
  2. Create a chatbot agent with the Create Chatbot Agent wizard.
  3. Give the agent an LLM API key on its AI Providers tab.
  4. Install the agent as a Chatbot App — that's where you chat with it.
  5. Open the App's Chats tab and have a real conversation.
  6. Reload the page and confirm the chat persists.

When you're done, Building a chatbot agent is the natural next read — it covers conversation design in depth.

Pick your starting point

You can start in either of two places. This tutorial's walkthrough (Steps 1 to 6) is written for the first one.

  • Inside an organization. Create one, or join one you are invited to. This is the path the rest of the tutorial follows, and the only one it has been checked end to end.
  • On your own, with no organization. Create a personal agent that belongs to your account. See Start without an organization.

Two things get confused here. Which organization an agent lives in (or none) is set by where you create it. Visibility is a separate choice on the agent, with the values Personal, Organization and Public; the wizard's default is Personal. An Agent is the definition; an App is an installed copy of it that people chat in.

What you'll need

  • A modern browser, signed in to hadronmemory.com. If you sign in by email link, you finish with a passkey; see Sign in with email and a passkey.
  • An organization you are an Owner or Admin of — only they can add an LLM key. If you don't have one, either create one or ask an Owner to invite you; both are covered next. (No organization at all? See Start without an organization.)
  • An API key from one supported LLM provider: Anthropic, OpenAI, GLM (z.ai), or AWS Bedrock. Anthropic and OpenAI are the fastest paths; GLM and Bedrock have extra setup we'll skip.

That's it. No CLI, no MCP host, no code editor.

Get an organization

Skip this if you already belong to one.

  • Create one. Open Account, then the Organization tab, and click Create organization. Give it a name and a URN. You become its Owner. The page lives at /app/orgs/new if you prefer to go straight to it.
  • Join one. An Owner or Admin creates an invite link for you on the organization's Members page (Create invite link) and sends it to you. Open the link; the page says You're invited! and accepting adds you as a member. A member who is not an Owner or Admin can follow the tutorial but cannot add an LLM key in Step 3, so ask for an Admin role or have an Owner add the key.

Step 1: Open the Create Chatbot Agent wizard

  1. After sign-in, click into your organization from the dashboard.
  2. Open its Agents page and click New Chatbot, next to New Agent. (If the organization has no agents yet, the page also offers Create a chatbot →.)

You're now on the Create Chatbot Agent wizard. It scaffolds the moving parts a chatbot needs (an agent, a system memory, a welcome conversation, a fallback conversation) in a single submit.

Step 2: Fill in the wizard

The wizard has four short steps — Agent, System Prompt, Memories, Review — with Next and Back to move between them:

Step Field What to enter
Agent Agent Name My first chatbot (or anything you'll recognise)
Agent URN Auto-fills as a slug from the name. Leave it.
Agent Description Optional. "My first Hadron chatbot." is fine.
Agent Visibility Personal is the default and is correct here.
System Prompt the prompt Optional. "You are friendly and brief. One short paragraph max per reply." gives the LLM a personality without over-scripting.
Memories system memory URN Auto-fills (<agent-slug>-system). Leave it.
Memories knowledge memory Include Untick it for this tutorial.

The Include box is ticked by default. Ticked, the wizard also creates a second, separate knowledge memory and attaches it to the agent as read-only. It is the place for reference material the chatbot answers from, and it starts empty. It is not the system memory, which holds the bot's conversation designs and is created either way. You untick it here only to keep your first bot simple: unticked, the wizard creates no knowledge memory. When you build a chatbot for real, Building a chatbot agent says when to tick it.

On Review, click Create Chatbot Agent. The wizard:

  • Creates the system memory that holds your bot's conversation designs and prompts.
  • Creates a setup conversation with one stage (onboard) whose prompt asks the user for their name.
  • Creates a fallback conversation that gracefully handles questions the bot can't answer.
  • Creates the agent itself, wired up to the system memory.

You land on the agent's page. Its tabs are Profile, Memories, Apps, Nodes, Chatbot Control, AI Providers and Settings.

Step 3: Give the agent an LLM key

  1. Switch to AI Providers.
  2. Click Add configuration.
  3. Name it default — the chat uses the configuration with that name.
  4. Pick your Provider (Anthropic or OpenAI).
  5. Type a Model identifier — for example claude-sonnet-4-20250514 for Anthropic or gpt-4o for OpenAI. The placeholder suggests one for the provider you picked.
  6. Paste your key into API key.
  7. Click Test.

✓ Works with a one-sentence reply means the key is valid. Click Save.

The configuration now appears in the list with your provider and model. The key is encrypted at rest with the server's master key; the portal won't display it back. If Test fails, see Configure your LLM provider.

Step 4: Install the agent as an App

You chat with an agent inside an App: an installed copy of the agent that people use.

  1. Go to your organization's Agents page.
  2. On your agent's row, click Install.
  3. Set App type to Chatbot. It defaults to Workstation, whose agent chat stays blank. This matters: changing the type afterwards doesn't fix it (hadron-portal#922), so if you miss it, install the agent again with Chatbot chosen. That creates a second, separate App; the first one stays as it is.
  4. Leave the suggested name and click Install.

You land on the new App, on its Chats tab.

Step 5: Have a conversation

  1. In the row of chats at the top of the Chats tab, pick Agent chat.
  2. The sidebar reads "No chats yet. Start a new one above." Leave the scope on Private and click + New chat.

The bot greets you and asks for your name — that's the setup:onboard stage running. Something like:

Bot: Hi! I'm My first chatbot. What should I call you?

Reply with a name. The bot acknowledges it. You didn't write that prompt: the wizard did.

If the bot opens with an apology instead

With only the wizard's setup and fallback conversations, which of the two a new chat opens in isn't fixed, so you may get the fallback conversation's apology rather than a question about your name. Everything else in this tutorial still works, except that the bot won't know your name in Step 6. Adding a conversation of your own settles it; see Building a chatbot agent.

While the chat runs:

  • Stage toasts flash above the input when the conversation transitions stages.
  • The sidebar lists every chat, each with a Private badge. A private chat belongs to you alone (see Chatting with an agent and Memory access).
  • Behind the scenes, every message is going through Hadron's Chat API; your portal session is acting as the integration.

Step 6: Confirm persistence

  1. Reload the page. Your chat is still in the sidebar of Agent chat.
  2. Click into it. The history is intact.
  3. Send another message. The bot still knows your name — the whole conversation, including your answer to its first question, is part of the chat.

If you wanted to drive the same bot from your own application instead of the portal, the integration is three GraphQL calls (startChat, sendChatMessage and processChatResponse), with your app calling the LLM. Building a chatbot agent covers the full design loop and shows the calls in context.

Start without an organization

You don't need an organization to have an agent. A personal agent is owned by your account, and nobody else is a member of it.

  1. Sign in and open Agents in the left menu, then click New agent. On the dashboard, the Agent Stats card has a Create new button that goes to the same form. (If your left menu shows an organization's agents instead, open /app/agents directly: that is the list of agents you own outside any organization.)
  2. Fill in Name (for example My research assistant) and Address (slug), which fills itself in from the name. The slug is how the agent is addressed, and can use letters, digits, hyphens and underscores. Description is optional.
  3. Click Create agent. You land on the agent's page. Its tabs include Profile, Memories, Apps, Nodes, AI Providers and Settings.

To use the agent in an App you own, open Apps, click New app, pick the agent you just made, and click Create app. The App is owned by your account. Your account needs a handle first; if the page says so, set one in your profile and come back.

What this path does not cover yet

The Create Chatbot Agent wizard in Step 2 is offered from an organization's Agents page. This tutorial has not checked that a personal agent gets the same scaffold, the same AI Providers flow or the same chat behaviour, so Steps 2 to 6 are not promised for it. If you want the chatbot walkthrough exactly as written, create an organization and follow it there. If you try the personal path and find a step that doesn't work, report it on the docs issue tracker.

What just happened

You created an agent. The wizard wrote a small program for it in your system memory — conversation and prompt nodes. You gave it an LLM key and installed it as an App. The App's agent chat acts as the integration, calling Hadron's Chat API on every turn: startChat, then a welcome turn through processChatResponse, then sendChatMessage → processChatResponse for each of your messages. Hadron compiles the prompt, manages stage transitions, extracts data into memory, and remembers everything across reloads.

Nothing about this is a toy. The same Chat API powers production bots with multi-stage flows, conditional routing, goal stacks, and per-user memory isolation. You skipped the integration step by using the App's agent chat — you'll write the same calls when you ship it inside your own product.

Where to go next

A handful of next reads, depending on what you're doing: