AI SDK Rules

Rule

Scope: Projects using Vercel AI SDK 6+ (ai package).

Deprecated APIs (NEVER use)

  • NEVERmaxTokens — renamed to maxOutputTokens.
  • NEVERparameters in tool definitions — renamed to inputSchema.
  • NEVERgenerateObject() — removed. Use generateText() with Output.object({ schema }).
  • NEVERmaxSteps — removed. Use stopWhen: stepCountIs(n) (import stepCountIs from ai).
  • NEVERtoDataStreamResponse() — renamed to toUIMessageStreamResponse() when using useChat.
  • NEVERtool-invocation as a part type — use typed tool-{toolName} parts.
  • NEVERpart.args / part.result — renamed to part.input / part.output.
  • NEVERaddToolResult() — renamed to addToolOutput() (with output not result).
  • NEVERmessages in createAgentUIStreamResponse() — renamed to uiMessages.

useChat (v6 Breaking Changes)

  • MUSTManage input state yourself with useState. useChat no longer provides input, handleInputChange, or handleSubmit.
  • MUSTUse transport: new DefaultChatTransport({ api: '/api/chat' }) instead of api prop.
  • MUSTUse sendMessage({ text }) instead of handleSubmit.

Structured Output

  • MUSTAlways use structured output when you need typed data back. Never parse JSON from result.text manually.
  • MUSTUse Output.object({ schema }), Output.array({ element }), or Output.choice({ options }) with generateText.
  • MUSTAccess results via result.output, not result.text.
  • SHOULDUse Output.choice({ options }) for classification tasks instead of asking the model to return a string and comparing it.

Providers

  • SHOULDUse OpenRouter as the default provider via @openrouter/ai-sdk-provider. Model IDs use provider/model format (e.g., openrouter('anthropic/claude-sonnet-4.5')).
  • MUSTSet OPENROUTER_API_KEY in .env.local. The provider reads it automatically.
  • SHOULDUse createOpenRouter() when you need custom config (headers, extraBody, prompt caching). Use the default openrouter import for simple cases.
  • MUSTWhen requests hang silently, check prompt size first. OpenRouter has provider-specific context limits that may be smaller than the model's advertised limit.

Agents

  • SHOULDUse ToolLoopAgent for agents with tool loops.
  • SHOULDUse InferAgentUIMessage<typeof agent> for type-safe tool rendering in useChat.

Prompt Engineering

  • MUSTKeep prompts under 100K tokens. Large payloads cause requests to hang silently on OpenRouter and other providers. If the input is large, chunk it or use tool calling to let the model request what it needs.
  • SHOULDPrefer tool calling over prompt stuffing. Instead of pasting an entire codebase/document into the prompt, give the model a tool to search/retrieve relevant sections. This is cheaper, faster, and more reliable.
  • SHOULDSet maxOutputTokens explicitly when you know the expected output size. Prevents runaway generation and reduces cost.

Verification

  • MUSTWhen unsure about an API, check node_modules/ai/docs/ and node_modules/ai/src/ before using it. Do not trust memorized APIs.

Further Reading

For complete migration patterns and code examples, reference the use-ai-sdk skill or invoke /arc:ai.