AI SDK Agent Rules

A TypeScript toolkit for building AI applications across model providers and UI frameworks.

Overview

The root guide covers provider architecture, security rules, and the checks to run before finishing. Larger design decisions and contributor workflows live in separate documents.

Hard prohibitions Router files Verification by change type

Documents

├── 
├──  · symlink → AGENTS.md
├── architecture
│   └── 
├── contributing
│   ├── decisions
│   │   ├──  — Accepted decisions relevant to the change
│   │   └── 
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   └── 
└── packages
    └── ai
        └──

Techniques in this file

Give requests and responses different schema policies

User-facing options should be restrictive and optional unless null has meaning. Provider responses instead use nullish fields and minimal schemas so upstream API changes can be tolerated.

226**Provider Options Schemas** (user-facing):227 228- Use `.optional()` unless `null` is meaningful229- Be as restrictive as possible for future flexibility230 231**Response Schemas** (API responses):232 233- Use `.nullish()` instead of `.optional()`234- Keep minimal - only include properties you need235- Allow flexibility for provider API changes

02 / Hard prohibitions

Make URL validation explicit at each fetch

Every getFromApi call must specify validateUrl, with different values for provider-returned URLs and configured base URLs. The rule also names credentialedOrigin to prevent credentials following an off-origin response.

239- Every `getFromApi` call in this repository must set `validateUrl` explicitly240  (the option is optional for backwards compatibility with external callers, but241  omitting it skips validation — never rely on that; the242  `ai-sdk/require-validate-url` oxlint rule fails `pnpm check` otherwise). Use243  `true` when the URL comes from a provider response body (image/audio/video244  download or a polling URL); use `false` only for URLs built from a configured245  `baseURL`.246- Pass `credentialedOrigin` when a response URL may legitimately carry the API247  key on its first hop, so credentials are withheld off-origin.248- See [contributing/secure-url-handling.md](contributing/secure-url-handling.md).

03 / Router files

Consult accepted decisions before changing architecture

The guide routes new dependencies, API design, patterns, and infrastructure through the ADR index. Contradicting an accepted decision triggers discussion before implementation.

198This repo uses ADRs in `contributing/decisions/` to capture important architecture decisions. Before making changes that touch architecture (new dependencies, new patterns, API design, infrastructure), check existing ADRs:199 2001. Read `contributing/decisions/README.md` for the index of decisions.2012. Read any accepted ADRs relevant to your area of work. Follow the decisions and implementation patterns they specify.2023. If you encounter a pattern in the code and wonder "why is it done this way?", check whether an ADR explains it.2034. If your work would contradict an existing accepted ADR, stop and discuss with the human before proceeding.

04 / Hard prohibitions

Use approved JSON parsing utilities

Production code must use parseJSON or safeParseJSON from provider-utils instead of JSON.parse directly. The prohibition identifies the shared replacement and gives security as its rationale.

152Never use `JSON.parse` directly in production code to prevent security risks.153Instead use `parseJSON` or `safeParseJSON` from `@ai-sdk/provider-utils`.

05 / Verification by change type

Define completion artifacts by task type

Bug fixes call for a reproduction, regression tests, implementation, manual verification, and a changeset. New features and internal refactors have separate lists, with explicit room to adjust for scope and visibility.

280A complete bug fix typically includes:281 2821. **Reproduction example**: Create/update an example in `examples/` that demonstrates the bug before fixing2832. **Unit tests**: Add tests that would fail without the fix (regression tests)2843. **Implementation**: Fix the bug2854. **Manual verification**: Run the reproduction example to confirm the fix2865. **Changeset**: Describe what was broken and how it's fixed

Ideas for your repo

Separate user-input schema policy from upstream-response tolerance.
Make URL validation and credential forwarding explicit at each network boundary.
Check recorded architecture decisions before introducing new patterns.
Define completion artifacts by task type and visibility.