Configuring Models with the CLI

To create and manage model configurations from the Solace Agent Mesh UI, and to understand what a model configuration is and how agents use it, see Configuring Models. This page covers authoring a model as version-controllable YAML, called declarative config: the YAML specific to the model kind. For the sam config plan, apply, and pull workflow that applies to every kind, see Managing Configuration as Code (Early Access).

The example on this page is an Anthropic model, the same kind of configuration the Agent Mesh UI page builds, so you can compare the two paths directly.

Before You Start

You need a running Agent Mesh instance to apply config to. For how to install or deploy one, see Install and Deploy.

The general and planning model aliases already exist in every deployment; this page adds another alongside them.

Write the Model

A model is one file under the models/ directory of a declarative-config repo, listed by name in the manifest:

# manifest.yaml
kind: manifest
name: models
description: Model configurations.
target:
  url: http://127.0.0.1:8800
resources:
  models:
    - analysis

The following file defines an Anthropic model. The alias is the top-level name; the provider, model, endpoint, and credentials live under spec:

# models/analysis.yaml
kind: model
name: analysis
description: General-purpose model for analysis tasks.
spec:
  provider: anthropic
  modelName: claude-sonnet-4-6
  apiBase: https://api.anthropic.com
  authConfig:
    type: apikey
    api_key: ${ANTHROPIC_API_KEY}
  maxInputTokens: 200000

The top-level name is the model's alias, the identity agents reference; use kebab-case for portability. The optional top-level description is the Description field in the Agent Mesh UI. The fields under spec map to the sections of the UI editor:

Field Description
provider The model provider: anthropic, openai, azure_openai, bedrock, google_ai_studio, vertex_ai, ollama, custom (any OpenAI-compatible endpoint), or typesafe (decision models only). The openai provider serves both chat models and decision models. This is the Model Provider picker in the UI.
modelType Optional. Either chat or decision (Early Access). The default is chat, the type every agent uses. Only workflow decision nodes and decision-model evaluators can call a decision model, which requires provider: typesafe or provider: openai. You cannot change the type, or a decision model's provider, after you create the model. For more information, see Define a Decision Model (Early Access).
modelName The provider's model identifier, such as claude-sonnet-4-6. This is the Model Name field.
apiBase The provider endpoint. This is the API Base URL field.
authConfig The credentials, keyed by a type discriminator: apikey takes an api_key; none takes no credentials; oauth2 takes client_id, client_secret, and token_url. This is the Authentication Type field and its credential inputs.
modelParams Optional model parameters such as temperature, max_tokens, stream_idle_timeout_seconds, and a prompt-caching strategy. These are the Advanced Settings in the UI. For more information about when to raise stream_idle_timeout_seconds, see Raising the Stream Idle Timeout in Configuring Models.
maxInputTokens Optional context-window limit, the Max Input Tokens field.

Enter stream_idle_timeout_seconds under modelParams as an unquoted number, such as stream_idle_timeout_seconds: 600. Agent Mesh saves a quoted value, such as "600", without an error but ignores it.

Never commit a real key. Reference it with ${ANTHROPIC_API_KEY}, and sam config apply substitutes the value from the environment. For the full secret-handling rules, see Managing Configuration as Code (Early Access).

To discover every field the model kind accepts, run sam config schema show model. To print a templated starting file, run sam config schema example model.

For a local or self-hosted, OpenAI-compatible endpoint such as Ollama, set authConfig to {type: none}; no key is required. Set provider to ollama, or to custom for any other OpenAI-compatible endpoint. This is the Authentication Type set to None in the UI.

Define a Decision Model (Early Access)

This feature is in the Early Access stage and under active development. Configuration schemas and behavior are subject to change. We recommend that you do not use this feature in production environments.

A decision model is the model that workflow decision nodes and decision-model evaluators call. For how decision nodes use it, see Routing with Decision Nodes (Early Access). For how evaluators use it, see Decision-Model Evaluators (Early Access). The following file defines a TypeSafe decision model with the alias ticket-router, which a workflow names in its decision.model_alias field and an evaluator names in its model field:

# ticket-router.yaml
kind: model
name: ticket-router
description: TypeSafe decision model for workflow decision nodes.
spec:
  modelType: decision
  provider: typesafe
  modelName: jev-1.13.0            # pin a version; the provider can move an alias such as jev-latest
  apiBase: https://api.typesafe.ai  # set it explicitly; if omitted, every plan reports a change
  authConfig:
    type: apikey
    api_key: ${TYPESAFE_API_KEY}

To reach TypeSafe through OpenRouter instead, set apiBase to https://openrouter.ai/api and modelName to typesafe/jev-1.13. With the same apiBase, you can set modelName to openai/gpt-6-luna-decisions instead. That model reads images as well as text, and so do the Jev models, whether apiBase is the TypeSafe API or OpenRouter. For more information, see Sending Images to the Decision Model.

The following file defines an OpenAI decision model with the alias ticket-router-openai.

# ticket-router-openai.yaml
kind: model
name: ticket-router-openai
description: OpenAI decision model for workflow decision nodes.
spec:
  modelType: decision                  # without it, an openai model is a chat model
  provider: openai
  modelName: gpt-6-luna
  apiBase: https://api.openai.com/v1   # set it explicitly; if omitted, every plan reports a change
  authConfig:
    type: apikey
    api_key: ${OPENAI_API_KEY}

A decision-model evaluator (Early Access) can also call a decision model. To limit the size of each call, the evaluator reads the max_state_bytes entry in modelParams, or maxInputTokens when max_state_bytes is not set. The Agent Mesh UI does not offer either setting for a decision model, so set them in this file. For more information, see Sizing Cases to the Decision Model.

Save each file under the models/ directory, and list its name, such as ticket-router, under resources.models in your manifest. Then apply it as described in Apply and Verify.

The following rules apply to a decision model:

  • Always set apiBase. Agent Mesh fills in an omitted value, so the sam config plan command reports a difference from your file on every run.

  • The api_key is required. The sam config plan command fails on a new decision model without one, and on an update that switches its authConfig to another type. An update that omits the key keeps the stored one.

  • The modelType cannot change after creation. The sam config plan command fails on a file that changes it, and on a provider: typesafe model that omits modelType: decision. A provider: openai model that omits modelType is a chat model.

  • A decision model's provider cannot change after creation. The sam config plan command fails on a file that changes it. To move to another provider, define a new decision model and point your workflows at it.

  • An agent cannot use a decision model.

  • While workflow decision nodes and decision-model evaluators are both disabled, the sam config plan command fails on a new decision model, and Agent Mesh rejects any request to create one. You can still edit existing decision models.

  • You cannot rename a decision model while a workflow's decision.model_alias names it, in either the workflow's saved version or its deployed version.

  • The sam config apply --prune command deletes models after it applies and redeploys workflows, so you can point a workflow at a new decision model and remove the old one in a single apply. The command never undeploys a workflow to delete a model. While any workflow still names the model, including a workflow that --no-deploy left deployed on that model, the deletion fails and the error names the workflow. A later apply skips any workflow whose file is unchanged, so before you apply again, redeploy that workflow on another decision model yourself.

A workflow decision node sends its input to a third party. That third party is the decision model's provider (TypeSafe or OpenAI), or a pass-through service such as OpenRouter that forwards the call. For a workflow that you save in the Agent Mesh UI or apply with sam config apply, registering a decision model is what allows that data to leave your deployment. Review the provider's data-processing terms before you register one. Decision nodes are enabled by default, but an administrator can disable them by setting the SAM_FEATURE_WORKFLOW_DECISION_NODE environment variable to false.

Apply and Verify

Preview the change with sam config plan -m manifest.yaml, then apply the manifest to create the model:

sam config apply -m manifest.yaml
Applied models:
  + analysis             created

To confirm the result, export the model back into YAML with sam config pull --only model --name analysis --url http://127.0.0.1:8800 -o ./pulled, or open the Agent Mesh UI and find analysis on the Models page. A model has no deploy phase; after it is applied, it is immediately available for agents to reference.

A manifest that lists only analysis shows the seeded general and planning as deletes in the plan, but apply leaves them in place. For how the plan and apply diff works, including the display-only delete entries and --prune, see Managing Configuration as Code (Early Access).

What Next?

You have a model defined as version-controllable YAML. Most readers next: