Skip to content

The model call

A realm that declares capabilities: ["model"] may put a question to the owner’s model from any handler. The owner grants the model on its own at admission, and may not; a realm should keep working without it.

const reply = ctx.call("ai_complete", {
prompt,
role: "best",
skills: ["chess-plans"],
maxOutputTokens: 1200,
});
// reply is { text: string, truncated: boolean }
  • prompt is not blank. role is "cheap", "workhorse" or "best", or left out for the owner’s default. The realm names a role and never a model: the host chooses the model behind each role and holds its credential.
  • skills names up to eight skills, each 1 to 64 characters: this realm’s own, bare or as <realm>-<skill>, or one the owner’s World has. The host supplies the skill’s text; the realm never sends it.
  • maxOutputTokens is a positive whole number. The host cuts a longer reply and says so in truncated.
  • Any other field is refused, and the SDK’s inferred types make it a compile error.
  • A refusal is thrown as an error whose code is MODEL_NOT_GRANTED, MODEL_SKILL_UNKNOWN, MODEL_CALL_BUDGET, MODEL_DAILY_BUDGET or MODEL_PROMPT_TOO_LARGE. A request the host cannot read is refused with no code.
  • The call is budgeted per dispatch (calls, prompt bytes and output tokens), per day, and by the dispatch’s own deadline; the reference values are in the model call.

A captured handler has no gateway.ai; that surface belongs to the conventional code-mode sandbox. ctx.call with any other tool name is refused.