Use case

Let Users Choose The Agent's Model

Offer a main model plus additional models on one agent and let the caller, or a chat UI model picker, choose which one answers.

• Stack Console + Agent Server + Chat UI
• Pattern Agents · Chat
• Read ~6 min

Overview

Some questions need a fast answer and others need deep reasoning. Instead of publishing one agent per model, give a single agent a main model plus up to ten additional models, and let the caller choose per request. Anyone who may run the agent may use any model on its list; there is no separate permission.

When to reach for this use case

Use it when the same agent, instructions, and tools should be available with a speed-versus-quality choice, either from code or from a model picker in your chat UI.

Run the example

Runnable code for this pattern is public on GitHub:

• console-examples / 03-agent-additional-models: Letting the caller choose which of an agent's models answers, per request and per session.
• console-examples / 04-agent-server-chat-ui: A Next.js chat UI with a model picker, served by an agent server in front of a Console agent.
• chat-ui / examples/nextjs-model-picker.tsx: The Chat component showing a model picker when the agent advertises two or more models, and sending the choice with each message.

Architecture

Console stores config.additionalModels on the agent ([{ modelKey, label?, description? }], unique, never the main model) and exposes the list as agent.models on GET /agents/{agentKey}. The field is absent when the agent offers fewer than two models.

The caller sends the choice as agent_model in the request body or in the X-Cognipeer-Agent-Model header (the body wins). The answering model is reported in cognipeer.agent_model.

Agent Server and Chat UI can sit in front: the server advertises the models and forwards the pick, and the chat UI shows a model picker when an agent offers two or more models.

1. Add Models To The Agent

In the agent editor, set the main model, add other models from the same project as additional models with an optional label and a short "when to choose it" description, then publish the agent. The client API runs the published version.

2. Pick A Model Per Request

const res = await fetch(`${base}/api/client/v1/agents/responses`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: agentKey, // the agent key; agent_model picks the model
    input: "Explain this contract clause.",
    agent_model: "deep-model",
  }),
});
const data = await res.json();
console.log(data.cognipeer?.agent_model);

On the OpenAI-compatible surface, use model: "agent:<key>" and pass agent_model as an extra body field or the header. A model that is neither the main model nor on the list is refused with 400 model_not_allowed.

3. Remember The Choice Per Session

A session remembers the last chosen model. The order is: the model requested now, then the session's last model, then the main model. If a model is later removed from the agent's list, the remembered choice falls back to the main model.

4. Show A Model Picker

The example app serves a host agent through @cognipeer/agent-server and renders @cognipeer/chat-ui. The host agent reads the models from the Console agent, the UI shows the picker, and the picked model is forwarded to Console as agent_model. The chat UI can also show an "Answered with" footer so users see which model replied.

Result

One agent, several models, and a choice that is explicit, validated by Console, and visible in the response.

Related use cases

Chat · Support

Customer Support Bot

Deploy conversational AI with streaming responses, human-in-the-loop escalation, guardrails, and tool transparency.

Apps · Platform

AI-Powered Applications

Integrate AI capabilities into existing applications with OpenAI-compatible APIs, provider routing, and type-safe SDKs.

Platform · Routing

Dynamic LLM Routing By Request And Caller

Give applications one stable model key and let Console pick the concrete model per request.

See every pattern on the use case index, or browse all Cognipeer libraries.