ai.chat.v1
Platform-owned AI slots with normalized model-tool output and explicit retry lineage.
Ownership
ai.chat.v1 is the bundle's supported AI service. The bundle supplies an opaque slot, prompt,
purpose, exact beneficiaries, output controls, and a deterministic idempotency key. The platform
resolves provider, model, credentials, thinking policy, price, and payer obligations.
The public slots are utility, game, and advisor. A personal advisor override requires the
advisor slot, one beneficiary, and trusted host authorization; creator workflow code cannot mint
that authorization.
Request
const invoke = await gameCtx.apiInvoke(
"ai.chat.v1",
{
slot: "game",
purpose: "world_simulation",
workflowRunId,
prompt,
round,
stream: false,
responseProtocol: "normalized.v3",
fidelity: "strict",
beneficiaryUserIds,
tools: [
{
name: "select_region",
inputSchema: {
type: "object",
properties: { regionId: { type: "string" } },
required: ["regionId"],
additionalProperties: false
},
strict: true
}
],
toolChoice: "required"
},
{ idempotencyKey: callId }
);
if (!invoke.ok) throw new Error(`ai.chat.v1 transport failed: ${invoke.error}`);
const result = requireAiChatResult(invoke.result);beneficiaryUserIds must be sorted, unique, non-empty for a new call, and contain at most 64
current non-spectator humans. Use either jsonSchema or tools. Tool choice and allowed-tool
fields must reference the offered definitions.
responseProtocol is required and must be "normalized.v3". Older or omitted protocol values are
rejected rather than negotiated.
Normalized results
A successful normalized completion includes text, attemptId, callId, semanticStatus, and
canonical tool outcomes. Incremental streams emit ordered normalized v2 events. Tool starts and
argument fragments are provisional; only tool.ready contains executable schema-valid arguments.
tool.invalid and tool.cancelled remain visible outcomes so workflow policy can decide what to
do next.
The bundle must still pass the terminal business envelope through requireAiChatResult. Gateway
success is not business success.
Failure is an opaque business result containing platform presentation data rather than provider, billing, or credential diagnostics. Do not infer private failure taxonomy or retry by swapping providers.
Identity and retries
The idempotency key names one accepted generation and is bound to the exact request fingerprint. Redelivery of the same key and request reattaches or replays without another dispatch. Reusing it with changed prompt, beneficiaries, tools, or fidelity fails.
A deliberate new generation uses a new key plus retryOfAttemptId and retryReason. It is
independently accepted, metered, and billed. The platform does not hide a second billable
generation behind malformed output or an ambiguous provider dispatch.
See workflow AI slots and tools and beneficiaries and payers.