Control Over Subagent Model Selection in Cloud Agent API

Support Help
, ,
1

Hi Cursor Team,

We are using the Cursor Cloud Agent API to trigger agents programmatically rather than using the Cursor IDE.

We have a specific requirement around model selection. When we create an agent through the Cloud Agent API, we want to explicitly select a model and have that same model consistently used by the subagents spawned by the agent.

Currently, we are seeing that subagents can automatically select their own models, and we don’t have control over that selection. This makes it difficult for us to guarantee consistent model usage across our workflows, especially when we need predictable behavior, performance, and cost.

We understand that the Cursor IDE has model-selection settings, but since we are triggering agents directly through the API, we are not relying on the IDE settings.

Our desired behavior is:

  1. We specify a model when creating the Cloud Agent through the API.

  2. The main agent uses that selected model.

  3. Any subagents spawned by that agent should also use the same model, rather than automatically selecting a different model.

  4. Ideally, there should be an API-level option to enforce/inherit the parent agent’s model for all subagents, including built-in subagents such as Explore, Bash, Browser, etc.

For example, if we create an agent with model.id = <selected-model>, we would like all subagent execution to inherit that exact model.

Could you please let us know:

  • Is there currently a supported way to enforce the selected model for all subagents when using the Cloud Agent API?

  • If not, is there an API parameter, configuration, or workaround that can provide this behavior?

  • Is there a plan to expose a setting such as inherit / forceModel for built-in subagents in the Cloud Agent API?

This is important for our use case because we need deterministic model selection when triggering Cursor agents programmatically.

Thanks!

7

Hey @E64_Genesis, thanks for the detailed report.

What you’re seeing is how the Cloud Agent API behaves today. The model you pass at agent creation sets the model for the main agent only. Some built-in helper subagents (for example, Explore and Browser) currently select their own models server-side, while others (like the general-purpose and shell helpers) do follow the parent’s model. There is no API option yet to force every built-in subagent to use the parent’s model.

Two things that can help in the meantime:

  1. If you define your own subagents via the customSubagents field on the create-agent request, you can set "model": "inherit" (or an exact model id) on each one. Those subagents will run on the parent’s model unless the agent explicitly requests another one.

  2. You can add an instruction to your prompt (or the repo’s AGENTS.md) telling the agent to always pass your chosen model explicitly when it spawns subagents. The model has to be one of the slugs available to subagents, and a couple of helpers (such as computer use) will still use their own model, so this reduces drift rather than guaranteeing consistency.

Making subagent model usage predictable and controllable, including for API-created agents, is something we’re actively tracking, and I’ve added your request for an API-level inherit/enforce option to that work. I can’t share a timeline yet, but I’ll post here when there’s an update.