Configuring Models

A model configuration tells Solace Agent Mesh how to reach a large language model (LLM): which provider hosts it, which model to call, and the credentials to authenticate with. Each configuration has a short alias (for example, general) that agents reference in place of the underlying provider details. You create and manage these configurations from the Agent Mesh UI, with no YAML to write and no restart.

This page covers creating and managing model configurations from the Models page in the UI. For installation instructions, see Install and Deploy. To manage the same configurations as version-controllable YAML instead, see Managing Configuration as Code (Early Access).

How Agent Mesh Uses Models

Every agent reasons with a model, but an agent does not name a provider or hold an API key itself. Instead, each agent references a model configuration by its alias through the Model picker in the agent editor. This indirection lets you point many agents at one configuration and change the underlying provider or model in a single place.

A model configuration is composed of a few parts:

• Display name: the alias agents and teammates use to reference the model, such as general.

• Model provider: the service that hosts the model, such as Anthropic, OpenAI, or a Custom OpenAI-compatible endpoint.

• Model name: the specific model to call, such as claude-sonnet-4-6.

• Authentication: the credentials Agent Mesh uses to reach the provider, such as an API key.

• Parameters: optional settings that shape responses, such as temperature, maximum tokens, and prompt caching.

Every deployment starts with two built-in model aliases:

• general: the model new agents and built-in AI features use.

• planning: the model the Orchestrator agent uses to plan and delegate work.

You connect these aliases to an LLM provider yourself, either during first-run setup or later on this page. Until a default alias is connected to a provider, it is flagged as not configured and agents cannot use it. Both aliases always carry a Default badge and cannot be deleted, though you can edit them to point at a different provider or model.

Every model an agent uses is a chat model. A deployment can also register a decision model (Early Access), a structured model from TypeSafe or OpenAI that answers typed questions. Only workflow decision nodes and decision-model evaluators can call a decision model. Agents, LLM-as-a-Judge evaluators, and other features that use a model cannot. For more information, see Adding a Decision Model (Early Access) and Decision-Model Evaluators (Early Access).

Opening the Models Page

In the left navigation sidebar, expand Builder and select Models. The page lists every model configuration across three columns:

• Name: the configuration's alias.

• Model: the model name it calls.

• Model Provider: the provider that hosts it.

Select a column header to sort by that column. The built-in general and planning configurations carry a Default badge, and a default configuration that has not yet been connected to a provider is flagged so you can finish setting it up. Each row has an Actions menu, and Add Model creates a new configuration.

Adding a Model

The following steps add a model configuration for an Anthropic model and make it available to your agents.

1. On the Models page, click Add Model.

2. If the form shows Model Type, leave Chat (LLM) model selected. If it does not, go to the next step. The form shows Model Type only while workflow decision nodes or decision-model evaluators are enabled.

3. Enter a Display Name and a Description. The display name is the alias agents reference, so keep it short and descriptive, such as analysis. The description tells teammates what the model is suited for.

4. Select a Model Provider. The list includes Amazon Bedrock, Anthropic, Azure OpenAI, Google AI Studio, Google Vertex AI, Ollama, OpenAI, and Custom, which covers any provider that implements the OpenAI-compatible API protocol. Select Anthropic.

5. Enter the connection details the provider requires:

   • API Base URL: the provider's endpoint.

   • API Key: your provider API key. Select Show password to reveal what you entered.

6. Set Model Name. When the provider and key are valid, the list populates with the models available to your account. You can also type a model name directly.

7. (Optional) Set Max Input Tokens to the model's context-window limit, and expand Advanced Settings to set Temperature, Max Tokens, a Prompt Caching Strategy, or provider-specific Custom Parameters.

8. Click Test Connection to confirm Agent Mesh can reach the model. A failed test shows the provider's error message inline.

9. Click Add to save the configuration. It appears on the Models page, ready for agents to reference.

Some providers, such as Custom and Ollama, add an Authentication Type field with API Key, OAuth2, and None options. For a local or self-hosted, OpenAI-compatible endpoint, select Custom or Ollama, set Authentication Type to None, and provide only the API Base URL; no API key is required.

If Test Connection fails but the details are correct, you can still save the configuration: select Add, then Save Anyway in the Connection Test Failed dialog. This is useful when the provider is not reachable from where you are working.

Adding 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 to answer typed questions. A decision node classifies its input and routes on the answer, and a decision-model evaluator scores an agent's response. For more information about decision nodes, see Routing with Decision Nodes (Early Access). For more information about decision-model evaluators, see Decision-Model Evaluators (Early Access).

Before you begin, complete these prerequisites:

• Get an API key from your decision model's provider: TypeSafe, OpenAI, or a pass-through service that serves the TypeSafe API, such as OpenRouter.

• Confirm that workflow decision nodes or decision-model evaluators are enabled. The Add Model form offers decision models while either feature is enabled.

  • Workflow decision nodes are enabled by default. An administrator can disable them by setting the SAM_FEATURE_WORKFLOW_DECISION_NODE environment variable to false.

  • Decision-model evaluators are enabled by default. An administrator can disable them by setting the SAM_FEATURE_EVAL_DECISION_EVALUATOR environment variable to false.

A workflow decision node or a decision-model evaluator sends data 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. The same is true for an evaluator that names the decision model. Review the provider's data-processing terms before you register one.

To add a decision model, perform these steps:

1. On the Models page, click Add Model.

2. Under Model Type, select Decision model, which carries an Early Access badge. The form hides Max Input Tokens and Advanced Settings, which do not apply to a decision model.

3. Enter a Display Name and a Description. The display name is the alias that a workflow's decision.model_alias field or an evaluator's model field names, such as ticket-router.

4. Select a Model Provider, either TypeSafe or OpenAI. Both carry the Early Access badge of decision models.

5. Enter the connection details:

   • API Base URL — For TypeSafe, leave the field blank to use the TypeSafe API at https://api.typesafe.ai, or enter a pass-through that serves the same API, such as https://openrouter.ai/api. For OpenAI, leave the field blank to use the OpenAI API at https://api.openai.com/v1, or enter another base URL that serves the OpenAI Decisions API, such as a regional OpenAI API endpoint.

   • API Key — Enter the API key from your provider or pass-through service. A decision model always authenticates with an API key.

6. Enter or select the Model Name:

   • For TypeSafe, enter a version such as jev-1.13.0, or typesafe/jev-1.13 through OpenRouter. Use a pinned version rather than an alias such as jev-latest, which the provider can move to a newer version and change how deployed workflows route.

   • For a TypeSafe model that reads images, enter a Jev version, such as jev-1.14.0, with the TypeSafe API base URL. With the OpenRouter API base URL, enter typesafe/jev-1.14 or openai/gpt-6-luna-decisions. For more information, see Sending Images to the Decision Model.

   • For OpenAI, select gpt-6-luna from the list.

7. Click Test Connection to confirm that Agent Mesh can reach the model. For a decision model, the test asks the model one yes-or-no question.

8. Click Add to save the configuration. The model appears on the Models page with a Decision badge, and Open Details shows its Model Type as Decision model.

Managing Models

Select a configuration's Actions menu to reach its lifecycle actions:

• Open Details: view the configuration's provider, model, and audit information.

• Edit: reopen the editor to change the provider, model, credentials, or parameters. Stored credentials are masked; enter a new value only to replace one.

• Delete: remove the configuration.

The Delete Model dialog lists the agents and workflows that use the configuration. Deleting the configuration undeploys the ones that are deployed, and the dialog marks each of them Will be undeployed. Agents and workflows that are saved but not deployed still reference the deleted configuration's alias, so update them to use another configuration before you deploy them. To confirm the deletion, type the configuration's alias. The built-in general and planning configurations are required, so you cannot delete them; selecting Delete on either one opens an Unable to Delete dialog instead.

Raising the Stream Idle Timeout

By default, Agent Mesh abandons a streamed model response when the provider sends no data for 300 seconds, and the request fails with a stream idle timeout error. Some providers send a tool call only after the model finishes generating it, so a large tool-call argument, such as a complete HTML page, can leave the stream silent for several minutes. If an agent's requests fail with this error, raise the timeout on the model that the agent references.

To raise the stream idle timeout, perform these steps:

1. On the Models page, open the model's Actions menu and select Edit.

2. Expand Advanced Settings.

3. Under Custom Parameters, click New Pair, enter stream_idle_timeout_seconds as the key, and enter the number of seconds to wait, such as 600, as the value.

4. Click Save.

You can set the same parameter when you add a model. If the form warns that some custom parameters may not be supported by the selected model, you can ignore the warning: Agent Mesh still applies the setting. A value of 0 or less uses the 300-second default. To set the same value in a declarative model resource, see Configuring Models with the CLI.

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

Two other timeouts can end the request before a silent stream reaches the stream idle timeout:

• When an agent delegates to a peer agent, the delegating agent receives no progress while the peer's stream is silent. Set the delegating agent's spec.additionalConfigurations.interAgentCommunication.requestTimeoutSeconds to a value greater than the stream idle timeout of the peer agent's model. The default is 120 seconds. For more information about the additionalConfigurations block, see Configure Settings Not Yet Modeled as Fields in Creating Agents with the CLI.

• For an agent node in a workflow, the node timeout counts from when the node starts, so it must cover the agent's whole run, including a silent stream. In the workflow resource, set timeout on the node, or set spec.appConfig.default_node_timeout for nodes that set none. Both take a duration, such as 10m, and the default is 5m. For more information about workflow files, see Creating Workflows with the CLI (Early Access).

Setting requestTimeoutSeconds also changes the defaults of workflowRequestTimeoutSeconds and subTaskTimeoutSeconds. Both default to 600 seconds, but after you set requestTimeoutSeconds, they default to your value or 300 seconds, whichever is larger. To keep them at 600 seconds, set them explicitly.

Using a Model in an Agent

Agents choose a model in the agent editor. When you create or edit an agent, the Model picker lists every configuration from the Models page by its alias, and the agent uses whichever one you select for its reasoning. A new agent uses the general configuration by default. For the full agent workflow, see Creating Agents.

Define Models as Code Instead

The Agent Mesh UI is one way to manage model configurations; the sam CLI is the other. With declarative config you describe a model as YAML and reconcile it into Agent Mesh with sam config apply, the version-controllable path that suits GitOps and automation. To create the same model from the command line, see Configuring Models with the CLI.

Next Steps

You have model configurations that your agents can use. Most readers next want to put them to work:

• To create an agent that uses one of these models, see Creating Agents.

• To manage model configurations as version-controlled YAML, see Managing Configuration as Code (Early Access).