Configure Agent BYOK¶

BYOK lets the Agent use your own model services. Enter the service URL, API Key, models, and reasoning levels in provider.json, then save the file contents to etcd.

You need two sets of credentials: an etcd account to save and read the model configuration, and a model API Key to call the model service.

BYOK Workflow¶

sequenceDiagram
    autonumber
    participant Beak
    participant Agent as Agent (including installation)
    participant Etcd as etcd
    participant LLM as Model service

    Note over Beak,Agent: Enter etcd settings and install the Agent
    Agent->>Beak: Read saved etcd settings
    Agent->>Etcd: Read Provider and model configuration
    Agent->>Beak: Sync selectable models

    Note over Beak: Select a model and start a task
    Beak->>Agent: Send task
    Agent->>LLM: Call selected model
    LLM-->>Agent: Return response
    Agent-->>Beak: Return result

    Note over Etcd: Update the complete provider.json
    Etcd-->>Agent: Notify configuration change
    Agent->>Etcd: Fetch latest configuration
    Agent->>Beak: Sync updated models
    Note over Beak,Agent: New tasks use the new configuration. Running tasks are unaffected

    Note over Beak,Agent: Reinstall after changing etcd connection settings<br/>Normal upgrades retain current BYOK settings

Prepare Connection Information¶

Before you start, prepare:

• The etcd address and the Key used to store the model configuration. This guide uses obs-agent/byok/providers.
• A dedicated etcd account named obs-agent, used to write the model configuration and let the Agent read it.
• The model service API base URL, API Key, and the model IDs, capabilities, and reasoning levels provided by the supplier.

Create a dedicated obs-agent account with a strong, unique password rather than reusing an existing account or password. Grant read and write access only to the specified Key.

The commands below require etcdctl. Ask an etcd administrator to run them, replacing the address and administrator username:

For custom certificates, first set ETCDCTL_CACERT. If client certificates are required, also set ETCDCTL_CERT and ETCDCTL_KEY. Each value is a certificate or private key file path.

export ETCDCTL_ENDPOINTS='https://<ETCD-HOST>:2379'
etcdctl --user='<ETCD-ADMIN-USER>' user add obs-agent
etcdctl --user='<ETCD-ADMIN-USER>' role add obs-agent-byok
etcdctl --user='<ETCD-ADMIN-USER>' role grant-permission obs-agent-byok readwrite 'obs-agent/byok/providers'
etcdctl --user='<ETCD-ADMIN-USER>' user grant-role obs-agent obs-agent-byok

Enter the administrator password when prompted. user add also prompts you to set a new password for obs-agent.

Write the Model Configuration¶

Create provider.json using the example below as a starting point. Replace the service URL, API Key, and model ID, and enter the context window size and reasoning levels supported by your supplier.

{
  "schema_version": 1,
  "default_model": {
    "provider_id": "provider-a",
    "model_id": "<MODEL-ID>"
  },
  "providers": [
    {
      "id": "provider-a",
      "name": "My provider",
      "protocol": "openai_chat_completions",
      "base_url": "https://<PROVIDER-HOST>/v1",
      "api_key": "<PROVIDER-API-KEY>",
      "models": [
        {
          "id": "<MODEL-ID>",
          "name": "My model",
          "context_tokens": 524288,
          "input_modalities": ["text"],
          "output_modalities": ["text"],
          "supports_tools": true,
          "supports_json_schema": true,
          "reasoning": {
            "supports_enable": false,
            "supports_disable": false,
            "effort": {
              "status": "available",
              "request_path": ["reasoning_effort"],
              "levels": ["minimal", "balanced", "deep"],
              "default_level": "balanced"
            }
          }
        }
      ]
    }
  ]
}

The reasoning fields and levels in this example illustrate the format; use the values documented by your model supplier. To add a service, add an entry to providers. To add a model, add an entry to the corresponding service's models.

Set the Service and Default Model¶

Service and model id values are case-sensitive. Keep the existing id when changing a display name so existing tasks can still identify the model.

Set Model Capabilities¶

Use valid JSON without unsupported comments or duplicate fields. You can add notes in fields such as comment or owner; the Agent ignores unknown fields.

Configure Reasoning Levels¶

Configure reasoning fields and levels separately for each model. Preserve the supplier's exact field names, level values, and capitalization. The menu displays the levels you configure.

For example, if the supplier uses reasoning.effort and supports Quick and Careful, enter:

{
  "supports_enable": false,
  "supports_disable": false,
  "effort": {
    "status": "available",
    "request_path": ["reasoning", "effort"],
    "levels": ["Quick", "Careful"],
    "default_level": "Careful"
  }
}

Use this object for the model's reasoning. Selecting Quick makes the Agent use Quick; without a selection, it uses Careful. When you switch models, the selected model uses its own levels.

If the model has no selectable levels and reasoning cannot be independently enabled or disabled, enter:

{
  "supports_enable": false,
  "supports_disable": false,
  "effort": {
    "status": "unavailable",
    "levels": [],
    "default_level": null
  }
}

Save the Model Configuration to etcd¶

Open Bash in the directory containing provider.json, replace the etcd address, and run the commands below. Enter the password you just created for obs-agent:

export ETCDCTL_ENDPOINTS='https://<ETCD-HOST>:2379'
read -r -s -p 'obs-agent password: ' ETCDCTL_PASSWORD
printf '\n'
export ETCDCTL_PASSWORD
ETCDCTL_USER='obs-agent' etcdctl put 'obs-agent/byok/providers' < provider.json
unset ETCDCTL_PASSWORD

An OK response means the write succeeded. The first write creates the Key, and later writes replace its entire contents. Keep all other services and models in each update. If you connect with certificates, keep the certificate settings from the preceding section.

Prepare the Agent Connection Configuration¶

Enter the Connection JSON¶

When installing or reinstalling the Agent, use the following connection information with the same etcd account, obs-agent:

Enter and save these settings on the Web Agent creation page or the Runtime and Deployment page, then copy the installation command and run it on the target machine. Installation reads the saved settings automatically; you do not need to append BYOK settings to the command. Reinstalling the same Agent also reuses these settings.

{
  "schema_version": 1,
  "endpoints": ["https://<ETCD-HOST>:2379"],
  "user": "obs-agent",
  "password": "<OBS-AGENT-ETCD-PASSWORD>",
  "key": "obs-agent/byok/providers",
  "request_timeout": "10s"
}

Replace all angle-bracket placeholders. key must exactly match the Key used for authorization and writes. List multiple etcd addresses individually in endpoints. Do not substitute a model API Key for the connection username and password.

request_timeout defaults to 10s. Change it if needed, for example to 15s.

For a custom CA, add tls.ca_pem to the connection configuration and provide the complete certificate. For mutual TLS, also provide both tls.cert_pem and tls.client_key_pem. These fields contain PEM content; represent line breaks with JSON \n, for example:

{
  "tls": {
    "ca_pem": "-----BEGIN CERTIFICATE-----\n<CA-CONTENT>\n-----END CERTIFICATE-----\n"
  }
}

Add the required tls fields to the complete connection configuration. Omit them if the system already trusts the etcd certificate.

Find the Saved Connection Configuration¶

The Agent saves the connection configuration at .beak/private/byok.etcd.json under its working directory. The standard Linux installation path is:

/var/lib/obs-agent/work/.beak/private/byok.etcd.json

For a custom working directory, look for .beak/private/byok.etcd.json under that directory.

Select and Update Models¶

In an obscli Task, enter /model to select a service, model, and reasoning level. The menu displays configured service and model names and uses provider ID/model ID to distinguish models with identical names. You can also enter /model provider-a/model-a <effort> directly. See Model selection in obscli.

After changing models, API Keys, or reasoning levels, write the complete provider.json to the same etcd Key again. The Agent watches that Key and reads and validates the new contents when notified of a change. Once validation succeeds, new tasks use the new configuration, while running tasks continue with the previous configuration. When rotating an API Key, allow time for existing tasks to finish.

To remove a model, delete it from the corresponding models list. If it is the default model, also select a new default. When a model selected by an existing task is removed, subsequent execution uses the default model.

To change the etcd address, account, password, Key, or certificates, update and save the settings on the Agent's Runtime and Deployment page, then run the installation command again. Until reinstallation, the running Agent keeps the previous configuration; normal upgrades do not apply these changes either.

Switch Back to AIHub Models¶

To switch back to AIHub models, select Official Models on the Agent's Runtime and Deployment page, save the installation configuration, then copy the new installation command and reinstall the Agent. This command clears the saved BYOK settings.

Clearing startup arguments, deleting the model configuration from etcd, or stopping etcd does not switch the Agent back to AIHub models.

Troubleshoot Configuration Problems¶

Both the model and connection configurations contain credentials. Store them securely. When reporting a problem, include the error message and remove passwords and API Keys.