AgentKit Studio
Guides

Configure models and credentials

Add model profiles, set the default model, and configure cloud credentials.

Model configuration answers "which model can an agent call". This page sets up model profiles, API keys, reasoning effort, and cloud credentials so the Bind capabilities step can select a model.

Prerequisites

  • An OpenAI-compatible model endpoint, or an official Ksyun / OpenAI key.
  • Network access to that endpoint. For an enterprise gateway, confirm the Host machine can reach it directly.
  • The cloud credentials block is needed only for builds, deployments, and cloud resource access.

Steps

Open model and credential settings

Go to Settings → Models and credentials. The panel opens automatically on first launch; you can also open it later.

The page has two blocks: Models and providers on top and Cloud credentials below. For local conversations only, cloud credentials can stay empty.

Where to look

The whole model and credential panel — model list on the left, the four Connection / Credential / Model / Advanced sections on the right.

Add a model profile

Click + Add model in the top-right corner. A new profile starts with:

FieldInitial value
ProviderKsyun model service
API base URLThat provider's official default
Credential nameAGENTKIT_MODEL_API_KEY_<timestamp>, generated for you
EnabledYes

One profile is one combination of provider + base URL + model + credential. To use two providers at once, create two profiles.

Where to look

The Connection section of the detail pane after adding a model.

Fill in connection and credential

Connection

ProviderAPI base URLNotes
Ksyun model serviceRead-only, shows the official defaultNothing to type; switch to Custom to edit
OpenAIPrefilled with the official URLCan be replaced with a same-protocol proxy
Custom providerYou must fill it inAny OpenAI-compatible service

Validation: the URL must be HTTP(S) and must not carry user info, query parameters, or a fragment. Failing returns MODEL_ENDPOINT_INVALID with "the model service address must use HTTP(S) and must not contain credentials, query parameters, or a fragment". Trailing /chat/completions, /responses, and /models are trimmed automatically.

Credential

Enter the secret in API Key. For a profile that is already configured, the placeholder reads "configured; leave empty to keep" — an empty value means no change.

Where the key is stored

The API key is written only to the local Host credential store. It never enters agent configuration, browser form refill, or logs. The credential source is shown below the input: local file, global configuration, current workspace, environment variable, this session, or not configured. See Security and public boundary.

After filling in the key, click Read models. The browser never talks to the model service directly — the Host performs the read.

Choose a model name and reasoning effort

Model name: once you have clicked Read models, pick from the dropdown, or type a model name outside the catalog.

Reasoning effort: every dropdown entry reads "UI level → value actually sent", for example 最高 → high. Choose Not enabled to send no reasoning level at all.

ProviderLevels offeredDefault levelreasoning_effort actually sent
Ksyun model servicelow / high / maxhighlow / high / max
OpenAIlow / medium / highmediumlow / medium / high
Codexlow / high / maxhighlow / high / high (max degrades to high)
Custom providerlow / highhighlow / high

Switching provider falls back to the new provider's default level when the previous level is not in its enum, with a notice — rather than letting the upstream reject it later.

The Input capability row is read-only and shows the text / image capabilities the catalog reported. When discovery fails it explains why: no capability information, catalog temporarily unreadable, or model not found in the catalog.

Where to look

The Model section with the model name dropdown, reasoning level dropdown, and input capability chips.

Manage multiple profiles

ActionWhereBehavior
Set as defaultTop-right of the detail paneNew sessions use this model; other profiles lose the default flag
Disable / EnableTop-right of the detail paneA disabled profile disappears from an agent's selectable models
Revert changesTop-right of the detail paneDrops only this profile's in-memory draft back to the saved configuration
RemoveTop-right of the detail paneDeletes the profile; hidden when only one remains

Three hard constraints:

  • At least one enabled model must remain, otherwise "keep at least one enabled model".
  • Every profile needs a model name, otherwise "every model profile needs a model name".
  • The default profile needs a usable credential, otherwise "enter the model API key".

Edits go into an in-memory draft first and the profile card shows an Unsaved chip. Closing and reopening the panel keeps the draft; reloading the page or changing windows loses it.

Save the configuration

Click Save configuration in the bottom-right corner (in first-run onboarding it reads Save and continue or Save and finish, depending on how you got here).

Saving runs in order: write model profiles → sync credentials → apply profiles to DSH's provider routing → broadcast the model-changed event. The button shows Saving… meanwhile.

On success the footer shows:

已保存多个模型配置;标记为“默认”的模型用于新会话,Agent 可在创建或编辑时多选模型绑定。

Reload explicitly discards every draft and returns to the stored configuration; if drafts were discarded you also get "unsaved drafts discarded and saved configuration reloaded".

Optional: configure cloud credentials

Needed only for builds, deployments, and cloud resource access.

FieldRequiredNotes
Access KeyYes (first time)Shows "configured; leave empty to keep" once set
Secret KeyYes (first time)Same as above
Account IDNoOptional
RegionNoFor example cn-beijing-6
Control plane URLNoThe AgentEngine control plane address
Object storage bucketNoOptional

The last four live under Advanced cloud settings. On first configuration Access Key and Secret Key must be filled together, otherwise "enter Access Key and Secret Key, or skip cloud configuration". Success reads "cloud credentials saved".

Where to look

The Cloud credentials block and the expanded Advanced cloud settings section.

What success looks like

All four must hold:

  • The model card shows a green Configured, not Needs configuration.
  • A Default chip appears next to exactly one card's title.
  • The status strip in the top-right names the current default model.
  • In the agent creation form's Bind capabilities step, the Default model dropdown lists that model.

Common errors

Error codeCauseFix
MODEL_CREDENTIAL_MISSINGThe default profile has no API key yetFill in API Key for that profile and save
MODEL_PROFILE_INVALIDModel ID, model name, or credential reference is malformedModel ID must match ^[a-z][a-z0-9._-]{1,127}$; credential name must match ^[A-Za-z_][A-Za-z0-9_]*$
MODEL_PROFILE_EXISTSA model resource with this name already existsUse a different name, or edit the existing resource
MODEL_ENDPOINT_INVALIDThe base URL is not valid HTTP(S), or carries user info, query, or fragmentDrop ?, #, and the user:pass@ part
MODEL_CATALOG_FAILEDThe upstream returned non-2xx while listing modelsCheck key permissions and the endpoint; Test connection shows the status
MODEL_CATALOG_UNAVAILABLEThe whole catalog is unavailableOnly configured profiles are shown; verify network and credentials, then Reload
MODEL_CREDENTIAL_STATUS_FAILEDQuerying credential status failedReopen the panel; if it persists, check Host logs
MODEL_CREDENTIAL_SYNC_FAILEDSyncing credentials into DSH failedRetry saving; if it still fails, restart the Host and retry
请填写模型 API KeyThe default profile has no key and was never configuredEnter the key and save
What you want to knowWhere to go
The full reasoning-level to upstream-enum mappingsrc/model-reasoning.mjs
Base URL normalization rulessrc/model-endpoint.mjs
Model profile fields and runtime optionssrc/model-profile-contract.mjs, src/model-service.mjs
Model and credential panel sourcesrc/client/pages/model-settings.mjs
Credential-related environment variablesEnvironment variable reference
Create an agent from these profilesCreate and edit an agent

On this page