Sign in
routing

Recommend Model For Agent

Changed on

Recommend the model a subagent about to start should run on.

The harness sends the facts it holds at spawn time: its own ids for the session and the spawning tool call, the subagent type, the task, the parent's model and the model the caller asked for, if any. The recommender this build binds picks one of the candidate models and the answer names it. A standalone deployment asks the decision model agent_recommender_model names to choose among agent_recommender_candidates for Claude Code and among the request's own candidates for pi; a hosted build may bind a recommender of its own, which the caller never configures. Where the recommender reports them, the answer also carries a one-line reason and its probability for each candidate.

Authentication modes:

  • Master key: the user field is required and names who the decision is billed to.
  • API key: the decision is billed to the key's own user.
post/api/v1/routing/recommend

Request

  • The document declares no server URL.
  • Auth: one of:
    • API key in header Otari-Key
    • API key in header x-api-key

Request body

agent_typestring required

The subagent type: a built-in such as Explore or Plan, or a custom agent's name.

candidatesobject nullable

The models the subagent may be sent to, as Otari model ids (<provider>:<model>), each with what it is for (or null when the name says enough). Required for pi, refused for claude-code.

descriptionstring

The caller's short description of the task.

harness'claude-code' | 'pi' required

The agent harness asking. It decides the candidates: agent_recommender_candidates, Claude Code's own aliases, for claude-code, and the request's own candidates for pi.

parent_modelstring required

The model the parent conversation runs on, as the harness names it.

promptstring required

The task the subagent is given.

requested_modelstring nullable

The model the caller asked for, if any. Sent as a fact; the recommendation is the gateway's.

session_idstring required

The harness's own id for the session the spawn happens in.

tool_use_idstring required

The harness's own id for the tool call that spawns the subagent.

userstring nullable

User ID the decision is billed to when asking with the master key; not sent upstream.

Example request

{
  "agent_type": "Explore",
  "description": "Find the budget reservation code",
  "harness": "claude-code",
  "parent_model": "claude-opus-5",
  "prompt": "Find where budgets are reserved before dispatch and report the call chain.",
  "session_id": "bf05abe2-5ff2-4eb0-8459-ab578d5c9468",
  "tool_use_id": "toolu_01Ab3dEfGh"
}

Response

Successful Response

modelstring required

A model alias or id the harness can start the subagent on.

probabilitiesobject nullable

The decision model's probability for each candidate, when it reports them.

reasonstring nullable

Why, in one short sentence the harness may show.

Example response

{
  "model": "sonnet",
  "probabilities": {
    "haiku": 0.21,
    "opus": 0.07,
    "sonnet": 0.72
  },
  "reason": "jev-1.13.0 chose sonnet with 72%"
}

Changes

  • 78d85d97f9a2Revision changes
    • breaking

      request property was restricted to a list of enum values

    • info

      added the new optional request property

    • info

      added the new claude-code enum value to the request property

    • info

      added the new pi enum value to the request property

    • info

      the request property's minLength was decreased from 1 to 0

  • fbee488d4d9fRevision changes
    • info

      added the optional property to the response with the status