LLM Preferences / Model Policies

• LLM Preferences and Model Policies are two sides of the same conversation in Guild: what an agent asks for versus what the organization allows.
• An agent expresses preferences with llmPreferences — an ordered list of providers and models it wants to use. Preferences are hints.
• Model Policies live on the account and have final authority. A preferred model is used only if a policy allows it. Policies are enforced rules.
• Preferences are strict. If no listed preference is allowed by the account's keys or policies, the call fails with a named-preferences error rather than silently falling back to a default.

LLM Preferences are how an individual agent tells Guild what LLM providers and models it would prefer to run on. They are declared with llmPreferences, an ordered list of options ranked from most-preferred to least-preferred. An agent uses them per generateText call in coded agents or on the llmAgent definition for LLM agents.

Model Policies are how an organization tells Guild what LLM providers and models it will actually allow. They live on the account, above any single agent. Policies apply whether an agent has preferences or not, and they always override preferences.

The two concepts are complementary. Preferences describe intent. Policies describe permission. Every agent LLM call goes through both, and the outcome is the intersection: the highest-ranked preferred model that a policy actually allows.

Preferences are an ordered list

The llmPreferences array is walked from top to bottom. Guild tries each preference in order and uses the first one the account is authorized to run: for BYOK accounts, against the account's connected keys and model policies; for managed accounts, against server-side authorizations. This lets an agent say "I would like Claude Sonnet, but Claude Haiku is fine, and GPT-4o is my last resort," in a single declaration.

Preferences are strict — no silent fallback

If none of the declared preferences can be used — no key or policy allows any of them — the call fails. The error names the refused preferences so you can see exactly why nothing matched. Guild never silently substitutes the account's default model for a declared preference. This is a deliberate design choice: an agent that says "I need Claude Opus for this reasoning task" should fail loudly, not quietly downgrade to GPT-3.5.

Omit preferences to use the default

If an agent does not declare llmPreferences, Guild resolves the provider and model from the workspace owner's LLM settings. This is the right choice for most general-purpose agents: they benefit from the account's default configuration and do not need to reason about which model they run on.

Coded, LLM, and self-managed agents all support them

Coded and self-managed agents pass llmPreferences per call to task.llm.generateText. LLM agents declare llmPreferences on the agent definition itself, with the same semantics.

Policies live on the account and cover the org

Model policies are managed on the account (organization) level, not on any individual agent. An admin defines the allowed providers and models, and every agent under the account is subject to those rules on every call. This is where compliance, cost, and vendor decisions get enforced.

Policies always have final authority

An agent can prefer Claude Sonnet all it wants. If the account's policy does not allow Claude, the preference is refused. Policies exist to be the tie-breaker between what a developer wants their agent to do and what the organization is willing to authorize.

BYOK vs. managed accounts

For accounts that bring their own keys (BYOK), Guild resolves preferences against the connected keys and the model policies together — a model is available only if the account has a key for its provider and a policy allows it. For managed accounts, the same resolution happens against server-side authorizations.

Why policies exist

Every organization has real constraints around AI: which vendors are approved for their data, which models are allowed for sensitive use cases, which providers cost too much to leave on. Model policies are how those constraints get enforced at runtime, on every call, without anyone auditing prompts.

Declare preferences on a coded agent call

await task.llm.generateText({  llmPreferences: [    { provider: "anthropic", model: "claude-sonnet-4-5" },    { provider: "anthropic", model: "claude-haiku-4-5" },    { provider: "openai", model: "gpt-4o" },  ],  prompt: "..."})

Ordered from most to least preferred. If the account has no Claude keys but does have an OpenAI key and a policy that allows GPT-4o, the call uses GPT-4o. If nothing on the list is allowed, the call errors.

Declare preferences on an LLM agent

llmAgent definitions accept the same llmPreferences shape. Set them on the agent when a specific agent has a hard requirement for a particular provider or model.

Set model policies on the account

Model policies are configured under LLM settings on the account (Settings then LLM in the Guild app). This is where an admin picks which providers and models are allowed for the whole organization. See the LLM settings and model policies documentation for the full flow.

Interpret a refused-preferences error

When a call fails because no preference matches, Guild names the refused preferences in the error. That gives you two paths forward: either the agent's preferences need to be widened to include something the account allows, or the account's policies need to be updated to include what the agent needs.

Preferences describe intent — use them sparingly

Not every agent needs llmPreferences. If an agent works fine on the account's default, omit preferences entirely. Reserve them for agents that genuinely require a specific provider or model to do their job (reasoning-heavy tasks, structured-output specialists, cost-sensitive high-volume workloads).

Policies belong to the org, not to the developer

A developer can propose changes to model policies, but the org owns them. That is the point: policies enforce organizational decisions about which vendors are trusted, which models are approved, and which are off-limits. Do not treat policies as a per-agent setting.

Failing loudly is a feature, not a bug

Guild's decision to error rather than silently downgrade is deliberate. Silent substitution hides real problems — a reasoning agent quietly running on a smaller model, a compliance-scoped agent quietly running on an unapproved vendor. A loud failure is easier to debug and easier to trust.

Preferences and policies interact with cost

Both preferences and policies affect what your organization spends on AI. Preferences that keep an agent on a large model when a smaller one would do inflate cost. Policies that disallow cheaper models limit optimization. Tools like AI Spend Explorer make the impact visible so both sides can be tuned.

Guild is a control plane for AI agents, a place to build, deploy, and govern the agents your teams run in production. LLM preferences and model policies are how Guild reconciles agent-level intent with organization-level authority on every LLM call, without the two teams having to negotiate case by case.

• The LLM preferences guide covers the full shape of the llmPreferences declaration for coded and self-managed agents.
• The LLM agents guide covers how llmAgent definitions use the same preferences shape.
• AI Spend Explorer is the free tool for seeing where every AI dollar goes across providers.
• Explore the full Guild platform at guild.ai.