TaskRequest

TaskRequest = object

The request payload for a run() or stream() execution. The common envelope (schemaVersion, requestId, task, modelProfile, constraints, preferences, telemetry, authContextRef) is task-agnostic; each task kind owns its payload (ADR 016). text_to_text: at least one of prompt (single-turn) or messages (multi-turn) must be present — both may be present together, though callers should typically supply just one — and speech/delivery are forbidden. text_to_speech: speech and delivery are required and prompt, messages and generation are forbidden. constraints/preferences steer routing but never select a provider directly.

Indexable

[property: string]: unknown

Properties

authContextRef?

optional authContextRef?: string

A unique identifier used to retrieve credentials from a secure local storage. Raw sensitive keys (API keys, etc.) should NEVER be placed directly in the request payload.

---

constraints?

optional constraints?: Constraints

Request-level routing constraints used by the planner.

---

delivery?

optional delivery?: OutputDeliveryRequest

How the result of a non-text task must reach the application (ADR 016). Required for non-text tasks and forbidden for text_to_text, whose output is implicitly inline. A provider never substitutes playback for an artifact or the reverse.

---

generation?

optional generation?: Generation

Optional configuration for fine-tuning how the AI model generates its response.

---

messages?

optional messages?: [Message, ...Message[]]

A list of interaction messages for multi-turn conversation or chat-style execution.

---

modelProfile?

optional modelProfile?: string

Name of the model profile to route within, as configured on the engine. Absent or ‘auto’ means every registered target, ranked by constraints and preferences alone. A profile is an application-defined, ordered allow-list of targets (provider instances bound to one model each); raw model or provider identifiers are never accepted here. An unknown profile name fails request validation.

---

preferences?

optional preferences?: Preferences

Soft routing preferences used for deterministic provider ordering.

---

prompt?

optional prompt?: string

A simple, single-turn text prompt used to trigger a response from the AI model.

---

requestId?

optional requestId?: string

Optional identifier for tracking or correlating this specific execution attempt.

---

schemaVersion

schemaVersion: "1.0"

Contract schema version used to interpret the request payload.

---

speech?

optional speech?: SpeechInput

The text_to_speech payload. Required for text_to_speech and forbidden for every other kind.

---

task

task: Task

A descriptor specifying the type of work to be performed. The kind selects which payload the request must carry.

---

telemetry?

optional telemetry?: Telemetry

Execution preferences for tracking usage and performance metrics.