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 (or create) 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.

What you'll need

  • A modern browser, signed in to hadronmemory.com.
  • An organization you are an Owner or Admin of — only they can add an LLM key. If you don't have one, the Create Organization flow on the dashboard is two fields and thirty seconds, and makes you its Owner.
  • 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.

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.

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.

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: