For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/modules/ai.md (or send Accept: text/markdown).
AI and background jobs
From an authorized request to a durable result.
Try fake AI, then choose a real provider
For your first result, follow the Web tutorial's /dashboard task: start the local flow, queue a prompt, run it and view the result. AI_PROVIDER=fake returns a repeatable demonstration response without sending data to an external model or using a paid API key.
For real generation, first configure persisted accounts, choose an AI provider and follow AI configuration below. Add a model and its price to the database catalog, choose the permitted models for each alias, and grant the workspace the required access. An alias such as fast is a friendly choice shown to the user; it is not itself an external provider's model ID.
A background AI task also needs the configured jobs service. If no model choices are shown, inspect the catalog and alias policy before retrying. If access is denied, inspect the active workspace's entitlement. Keep all provider API keys in the Web server's configuration, not the browser, mobile app or desktop window.
Follow the task lifecycle
The production task API validates the authenticated workspace and entitlement before persisting a task and dispatching the ai.generate Trigger.dev workflow. The router applies capability requirements and configured model policy.
POST /api/ai/tasks
→ authenticated workspace + entitlement
→ durable task record
→ Trigger.dev ai.generate
→ model routing + generation
→ usage record + result
→ transactional completion deliveryConfigure aliases and budgets
The user selects an enabled alias: cheap, fast, or smart. The server controls the underlying model IDs, provider credentials, workspace policy, and budget enforcement. Encrypted bring-your-own-key support must preserve the same server-only boundary.
Keep workflow semantics explicit
JobRunner promises enqueue, status, and cancel only. Trigger.dev workflow semantics are explicit, including durable execution behavior. Do not infer retries or scheduling guarantees from the generic contract.
The production submission path uses idempotency and saved task recovery to handle ambiguous dispatch. Completion of generation is separate from completion-email delivery.