Model Selection Guide

Choose a model for the job it must perform, then test it with the same prompts and tools you will use in production. A model name in SyntheticBrew is a saved configuration record; it points to a provider model or deployment and can be reused by agents or knowledge bases.

Choose the model kind first

• Chat models generate agent responses and, when supported by the provider model, call tools.
• Embedding models convert Knowledge documents and queries into vectors. They require the provider’s exact vector dimension.

Kind cannot be changed after the model is created. Create a separate record when you need both uses.

Decide what the agent needs

For a chat model, evaluate:

Requirement	What to test
Tool calling	Can it select the right platform or MCP tool and produce arguments that match the schema?
Instruction following	Does it respect the agent system prompt, tool boundaries, and required output format?
Context capacity	Does the provider’s context window fit the system prompt, conversation, tool results, and retrieved knowledge? Set the agent’s context limit no higher than the provider supports.
Latency and cost	Does the complete workflow meet your response-time and budget target, including delegated agents and retries?
Structured input/output	Can it handle the forms, JSON, or domain records used by your product?

Agents that do not use tools can use a model without tool-calling support. Supervisors, Knowledge-enabled agents, and MCP-connected specialists need reliable tool calling. The Model Registry is a starting point based on SyntheticBrew’s built-in catalog, not a substitute for testing your workflow.

For an embedding model, confirm the provider model ID, vector dimension, language coverage, and input limits before uploading documents. Changing the embedding model later requires deleting and uploading the affected documents again.

Choose a supported provider type

SyntheticBrew accepts the following stored provider types:

Service	type value	Configuration
Anthropic	anthropic	Provider model name and API key; an optional compatible base URL may be supplied.
Azure OpenAI	azure_openai	Azure resource base URL, deployment name in model_name, API key, and API version.
OpenRouter	openrouter	Creation shortcut that is saved as openai_compatible with the OpenRouter base URL.
Ollama	ollama	Ollama URL and installed model name. SyntheticBrew normalizes a root URL or /api URL to the compatible /v1 path.
OpenAI and compatible services	openai_compatible	Provider model name, compatible base URL, and API key. Use this type for OpenAI, Google Gemini’s OpenAI-compatible endpoint, DeepSeek, Mistral, xAI, Z.ai, vLLM, LiteLLM, and similar gateways.

Do not use catalog provider IDs such as google, deepseek, mistral, xai, or zai as stored model types. Catalog entries group models for discovery; the table above describes the configuration accepted by model creation.

Cloud rejects custom endpoints that resolve to private or internal network addresses. Use a publicly reachable approved endpoint with Cloud. An Enterprise deployment can reach Ollama or another private model gateway when its network and egress policy allow it.

Use the deployment default or add a model

Check the health response when you are unsure whether the deployment already supplies a default:

curl "$SYNTHETICBREW_URL/api/v1/health"

"platform_default_model": true means an agent without its own model can use the deployment default. An agent-specific model takes precedence. With no default, assign a verified Chat model before testing the agent.

To add a model in Admin:

1. Open Models and choose Add Model.
2. Select Chat or Embedding.
3. Choose a supported provider type and enter a URL-safe configuration name.
4. Enter the provider model or deployment name, endpoint, credential, and any provider-specific fields.
5. For an embedding model, enter the exact vector dimension returned by that model.
6. Save the model, open its detail panel, and choose Verify. Saving alone does not test the endpoint.
7. Assign a Chat model to an agent, or select an Embedding model when creating a Knowledge base.

The expected result is a verified model visible only in selectors for its kind. Credentials are write-only and are never included in configuration exports.

Create a model through REST

This example creates a Chat model through an OpenAI-compatible endpoint. Replace the endpoint and provider model ID with values supplied by your provider:

curl -X POST "$SYNTHETICBREW_URL/api/v1/models" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"primary-chat",
    "type":"openai_compatible",
    "kind":"chat",
    "base_url":"https://provider.example/v1",
    "model_name":"provider-model-id",
    "api_key":"YOUR_PROVIDER_KEY"
  }'

Ordinary model create, update, and delete operations refresh the active model configuration automatically; a Config reload is not required. Config-import YAML does not persist credentials or model kind, so use Admin, REST, or a brewctl Model resource for complete model setup.

Evaluate the complete workflow

1. Create a test schema that uses the intended entry agent and delegation relations.
2. Ask representative questions, including missing-data and malformed-input cases.
3. Confirm every expected tool call in Tool Call Log and inspect failures.
4. Run several turns in one session to test context growth and compaction.
5. Measure latency and provider usage for the whole turn, including specialists.
6. Repeat after changing the model, prompt, tools, or context limits.

Use the strongest model only where your evaluation shows it improves the outcome. A focused specialist may work well with a faster model, while a supervisor that plans and combines several results often needs stronger instruction following.

Use BYOK for a request-specific override

When an administrator enables BYOK, an API caller can select an allowed provider and key for one chat request without storing that credential as a model record:

curl -N "$SYNTHETICBREW_URL/api/v1/schemas/support/chat" \
  -H "Authorization: Bearer bb_your_token" \
  -H "X-BYOK-Provider: anthropic" \
  -H "X-BYOK-API-Key: YOUR_PROVIDER_KEY" \
  -H "X-BYOK-Model: provider-model-id" \
  -H "Content-Type: application/json" \
  -d '{"message":"Test the support workflow."}'

See BYOK integration for provider allowlists, custom endpoints, and security boundaries.

Troubleshooting

• Verify fails: check the provider model name, endpoint, API key, and Enterprise egress/DNS access.
• Agent answers but never calls tools: confirm the provider model supports tools, the tools are assigned, and the system prompt says when to use them.
• Knowledge creation rejects the model: use an Embedding model with a positive, provider-matching vector dimension.
• Context errors appear on longer turns: lower the agent context limit or choose a provider model with a larger supported window.
• Ollama is unreachable from a container: use a hostname reachable from the SyntheticBrew container or pod; localhost refers to that container itself.

Next steps

• Model Registry
• Admin: Models
• Prompt caching
• Enterprise on-premises
• BYOK integration