AI Slots and Tools

Three opaque slots

Every workflow AI call chooses one of three platform-owned slots:

• utility for supporting decisions such as next-speaker selection;
• game for primary simulation and narrative work;
• advisor for advisor-family calls.

The slot is not a model ID. The platform resolves the model, provider, thinking policy, output budget, credentials, and billing resource for every accepted call. applyPlayerOverride: true is available only with advisor and exactly one beneficiary.

A normalized call

callAIResult makes failure handling explicit and returns the normalized completion identity, semantic status, assistant message, and model-tool outcomes:

var call = yield {
  type: "callAIResult",
  params: {
    prompt: "Choose one region to inspect.",
    slot: "game",
    purpose: "world_simulation",
    beneficiaryUserIds: ctx.beneficiaryUserIds,
    tools: [
      {
        name: "inspect_region",
        description: "Select a region by its stable ID.",
        inputSchema: {
          type: "object",
          properties: { regionId: { type: "string" } },
          required: ["regionId"],
          additionalProperties: false
        },
        strict: true
      }
    ],
    toolChoice: "required"
  }
};

On success, call.value is a WorkflowAICompletion with attemptId, callId, semanticStatus, text, and toolOutcomes. A tool outcome is tool.ready, tool.invalid, or tool.cancelled. Only tool.ready has canonical schema-valid arguments. Tool calls are data: the platform never turns a model tool directly into a workflow command or gameplay side effect.

Use either schema or tools, not both. allowedTools, a named toolChoice, and parallelToolCalls further constrain offered tools.

Streaming

callAIStream opens an ephemeral handle and readAIStreamEvent pulls ordered normalized v2 events. Text and tool-argument deltas are provisional display data. Wait for a canonical tool.ready outcome before applying a side effect. Stream handles do not survive isolate release; durable workflow state owns recovery.

The buffered and streaming paths share the same accepted-call identity and terminal contract.

Other request controls

Workflows may provide schema, parseJson, temperature, purpose, and fidelity: "bestEffort" | "strict". They cannot name a provider, model, payer, billing share, credential, or private normalization axis.

See beneficiaries and payers before choosing an audience, and failures and retries before adding retry logic.

The exact request and result types live in the workflow engine contract.