Skip to content

Configure your LLM provider

Portal onlyBeginner~10 min

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:

  1. The App — the App's Settings tab. Applies to that App's chats only.
  2. The agent — the agent's AI Providers tab. Applies wherever the agent runs.
  3. 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

  1. Open the agent and switch to its AI Providers tab (or open one of the other two places above).
  2. If there's nothing there yet, it reads "No AI configurations yet." Click Add configuration.
  3. Name it default. Names are 1–64 characters of lower-case letters, digits, - and _. fast and frontier are suggested too, for setups that use more than one model.

Step 2: Pick a provider and model

  1. Select a Provider.
  2. 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."

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.