Getting started with Hadron¶
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:
- Sign in to the portal and pick, create or join an organization (or, to start without one, see Start without an organization).
- Create a chatbot agent with the Create Chatbot Agent wizard.
- Give the agent an LLM API key on its AI Providers tab.
- Install the agent as a Chatbot App — that's where you chat with it.
- Open the App's Chats tab and have a real conversation.
- 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/newif 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¶
- After sign-in, click into your organization from the dashboard.
- 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
setupconversation with one stage (onboard) whose prompt asks the user for their name. - Creates a
fallbackconversation 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¶
- Switch to AI Providers.
- Click Add configuration.
- Name it
default— the chat uses the configuration with that name. - Pick your Provider (Anthropic or OpenAI).
- Type a Model identifier — for example
claude-sonnet-4-20250514for Anthropic orgpt-4ofor OpenAI. The placeholder suggests one for the provider you picked. - Paste your key into API key.
- 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.
- Go to your organization's Agents page.
- On your agent's row, click Install.
- 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.
- Leave the suggested name and click Install.
You land on the new App, on its Chats tab.
Step 5: Have a conversation¶
- In the row of chats at the top of the Chats tab, pick Agent chat.
- 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¶
- Reload the page. Your chat is still in the sidebar of Agent chat.
- Click into it. The history is intact.
- 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.
- 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/agentsdirectly: that is the list of agents you own outside any organization.) - 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. - 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:
- Building a chatbot agent — add real conversations, custom stages, prompts, and extraction specs. Required reading before you replace the wizard's scaffold.
- Conversation routing — the model: topics, conversations, stages, edges, goal stack, routing.
- Edge conditions — when to reach for deterministic edge conditions vs. letting the LLM decide.
- Build a conditional conversation flow — worked walk-through of an edge that skips a stage when its data is already on file.
- Test personas — automate regression testing on conversations.