Configure your LLM provider¶
An agent can't chat until Hadron has an LLM API key to call a model with. You add the key as an AI configuration: a named bundle of provider, model and key. This page walks through adding one in the portal, testing it and saving it.
You need to be an Owner or Admin of the organization. Other members see "Only organization admins can manage AI service configurations."
For the broader manual-test checklist that exercises the chat end to end, see Portal chat testing.
Prerequisites¶
- An organization you are an Owner or Admin of.
- An agent in that organization. If you don't have one yet, see Building an agent.
- An API key from one of the supported providers. See Supported providers below.
Where a configuration lives¶
You can add a configuration in three places:
- The App — the App's Settings tab. Applies to that App's chats only.
- The agent — the agent's AI Providers tab. Applies wherever the agent runs.
- The organization — the organization's Integrations tab. Applies to every agent and App in it.
Configurations are looked up by name. A chat asks for one name — default,
unless someone picks another in the chat's AI config picker — and uses the
enabled configuration with that name from the first place that has one: the
App, then the agent, then the organization, then the Hadron server itself (if
its operator has set one up). A name that isn't found anywhere falls back to
default.
So each name is resolved on its own: an App-level fast doesn't replace an
agent-level default for a chat that asks for default. Most people start
with one configuration on the agent, named default.
A keyless configuration still wins its name
The lookup takes the first enabled configuration with the name,
whether or not it has a key. An enabled default on the App with no key
hides a working default on the agent: the App's agent chat reads
"Connect an LLM provider to enable agent chat" even though the agent's
configuration works. Give the App's configuration a key, turn off
Enabled, or delete it.
Supported providers¶
The Provider list has four options:
| Provider | Value | What you need |
|---|---|---|
| Anthropic (Claude) | anthropic |
An Anthropic API key. |
| OpenAI | openai |
An OpenAI API key. |
| GLM (z.ai) | glm |
A z.ai API key. |
| AWS Bedrock | bedrock |
An IAM access key + secret + region (see Bedrock specifics). |
The model is a free-text field — you type the exact model
identifier (e.g. claude-sonnet-4-20250514, gpt-4o,
anthropic.claude-sonnet-4-20250514-v1:0). The placeholder updates
to a sensible suggestion as you switch provider, but the platform
does not pin a list — pick whichever model your account has access
to.
Step 1: Add a configuration¶
- Open the agent and switch to its AI Providers tab (or open one of the other two places above).
- If there's nothing there yet, it reads "No AI configurations yet." Click Add configuration.
- Name it
default. Names are 1–64 characters of lower-case letters, digits,-and_.fastandfrontierare suggested too, for setups that use more than one model.
Step 2: Pick a provider and model¶
- Select a Provider.
- Enter the model identifier in Model. The placeholder shows a suggestion for the provider you picked.
Step 3: Enter the API key¶
For Anthropic, OpenAI and GLM, paste the key into API key. For Bedrock, see Bedrock specifics — there are three credential fields instead of one.
The key is encrypted at rest with the Hadron server's master key, and the portal never shows it back. A configuration without a key shows No key.
When you edit an existing configuration, leave the key blank to keep the current key — the field says so. To remove the key without deleting the configuration, tick Remove the stored key.
Parameters (JSON) is optional: provider settings such as
{"maxTokens": 1024}. Enabled is on by default.
Step 4: Test¶
Click Test. It sends a short prompt through the provider using the values in the form, so you can test before saving.
- ✓ Works — shows the provider, model and the model's reply.
- × followed by the provider's error message (
401 Unauthorized,model not found,rate limit exceeded, and so on). Fix the cause and test again.
On a configuration you've already saved, on the agent or the App, Test works without re-entering the key: the server uses the stored one. Anywhere else, enter the key to test — otherwise you'll see "Enter a key to test this configuration."
Two results on a saved configuration¶
Testing a configuration you've saved shows two separately labeled rows, Run and Chat. They answer different questions, and neither stands for the other:
- Run is the result above: whether Hadron could call the provider with this configuration. On a saved configuration its × line is a fixed explanation (for example "The provider call failed. Check the configuration and try again."), not the provider's own message.
- Chat is whether the model can answer the way agent chat needs it to: it
must reply with exactly one call to its response tool, and that call must carry
the two required fields: a text
messageand a booleanonTrack. An emptymessagestill passes; a missing or wrongly typed field does not. A working Run says nothing about Chat, and the other way round.
The Chat row shows one of these results, always in fixed wording and never the provider's own text:
| What the row says | What it means |
|---|---|
| Passed: the model returned one valid response. | Exactly one response-tool call with a text message (which may be empty) and a boolean onTrack. |
| Failed: the model answered in text instead of using its response tool. | No tool call. |
| Failed: the model called a different tool. | The wrong tool. |
| Failed: the model called more than one tool. | More than one call. |
| Failed: the model returned an invalid response. | The call was malformed: its arguments were not an object, or message or onTrack was missing or the wrong type. |
| The chat test could not complete. Check the provider settings and try again. | The check could not finish; the row does not say why. |
| Chat testing is not supported by this provider. | Hadron has no chat check for this provider. |
Hadron's server decides how the model is asked to use its response tool, from the provider and the model, and the Chat row tests the same choice real chat uses. That decision is current behaviour, not a guarantee. The Chat check is a second call to the provider and is metered separately from Run.
If the Chat row is missing and only Run shows, the server you're connected to doesn't report a chat result yet. The Test you run before saving shows a single result and no Chat row.
Step 5: Save¶
Click Save. The configuration appears in the list with its provider and model, and the agent can now call the model.
To chat with the agent, open an App it's installed in, go to Chats, and pick Agent chat — see Chatting with an agent. The App needs to have been created with App type: Chatbot.
Updating or deleting¶
To change the provider or model, or rotate the key, click Edit on the configuration and overwrite the fields. Leave the key blank to keep the existing one.
Renaming default, fast or frontier warns you first: anything that
looks the configuration up by name stops finding it.
To delete a configuration, click Delete and confirm — "Delete the “default” configuration? This cannot be undone." If it was the only usable configuration, the App's agent chat then shows "Connect an LLM provider to enable agent chat".
Bedrock specifics¶
When you pick AWS Bedrock, the form shows three credential fields plus a region selector:
| Field | What it is |
|---|---|
| AWS Access Key ID | The IAM access key (AKIA… or temporary). |
| AWS Secret Access Key | The IAM secret. |
| AWS Region | Pick from us-east-1, us-west-2, eu-west-1, or ap-northeast-1. |
Hadron stores the three values together (encrypted) and uses them
to sign Bedrock InvokeModel calls. The model field takes the
Bedrock model ID, not a friendly name — for example
anthropic.claude-sonnet-4-20250514-v1:0, not claude-sonnet-4.
The IAM principal whose key you paste needs bedrock:InvokeModel
on the model ARN in the chosen region. If it doesn't, Test
returns a 403 AccessDenied from Bedrock.
Troubleshooting¶
| Symptom | What to check |
|---|---|
| "Only organization admins can manage AI service configurations." | You're not an Owner or Admin of the organization. Ask one to add the configuration, or to change your role. |
Test returns 401 Unauthorized / invalid api key |
The key is wrong or revoked. Generate a fresh key in the provider's console and paste it again. |
Test returns model not found / 404 |
The model identifier doesn't exist or your account lacks access. Verify the exact model string in the provider's console. Bedrock uses full model IDs (anthropic.claude-sonnet-4-20250514-v1:0), not short names. |
Test returns a Bedrock 403 AccessDenied |
The IAM principal lacks bedrock:InvokeModel on that model ARN, or the region is wrong. |
| The App's chat still says "Connect an LLM provider to enable agent chat" | No configuration with a key resolves for that App. Check that one exists on the App, its agent or the organization, has a key, and is enabled. |
| The App's chat says "Connect an LLM provider…", although the agent's configuration tests fine | A configuration with the same name at a higher level wins, even without a key — typically an enabled, keyless default on the App. Give it a key, turn off Enabled, or delete it. See Where a configuration lives. |
| The App's Agent chat is missing or blank | Missing: no agent is linked to the App. Blank: the App wasn't created with App type: Chatbot, and changing the type afterwards doesn't fix it (hadron-portal#922). See Chatting with an agent. |
| The chat starts but the agent doesn't follow a conversation | A key alone isn't enough: the agent also needs a chatbot system memory with at least one conversation. See Building a chatbot agent. |
| Test reply text is gibberish or wrong | The configured model returned something unexpected. Try a different model from the same provider, or check the provider's status page. |
| Saved a key, can't see it anywhere | Intentional — the portal does not display saved keys. To replace it, Edit and paste a new value. |
Related¶
- Chatting with an agent — where the chat is, once a configuration resolves.
- Portal chat testing — full manual checklist for agent chat once AI is configured.
- Building an agent — agent setup this page assumes is already done.
- Building a chatbot agent — the conversations the agent needs before it can hold a useful chat.
- hadron CLI: AI service configs — list the masked configs resolvable in an app's chat context from the CLI.