content-agent weekly downloads statistics

content-agent

Vercel AI SDK provider for Sanity Content Agent API.

Installation

Usage

ContentAgent extends the AI SDK's ToolLoopAgent — it inherits .generate(), .stream(), telemetry, and every other capability of the AI SDK's first-class agent abstraction. Construction is the only thing that differs: pass a provider and threadId instead of a model, and ContentAgent resolves the model for you.

provider is reusable — create it once per organization and instantiate as many ContentAgents as you need.

Why a class instead of streamText({ model, ... })?

The AI SDK 6 explicitly invites SDK authors to ship their own Agent implementations: "The Agent is now an interface instead of a class, which allows developers to implement their own agent abstractions for specific needs." ContentAgent is that implementation for the Sanity Content Agent — it preconfigures stopWhen, prepareStep, and toolChoice for the final_answer reply pipeline so you don't have to.

Migrating from streamText({ model: provider.agent(threadId) })? Nothing breaks — the lower-level API is still supported and works exactly as before. Switch to ContentAgent to pick up the safe defaults that prevent empty responses when the model burns its step budget on client tool calls. See How replies work below.

Streaming

Tools

Pass AI SDK tools to the constructor — schemas are forwarded to the agent, and execution happens locally on the client:

How replies work

Every reply is delivered through a server-side final_answer tool call. The agent streams final_answer.message to the wire as text-delta chunks (parsed incrementally from the tool-call args) and includes structured suggestions for clients that render reply buttons. There's no separate "streaming mode" — every conversation, every client follows the same path.

ContentAgent adjusts the loop control primitives to make this safe by default:

1. stopWhen defaults to "stop on the first step that contains a final_answer tool call," plus a stepCountIs(20) safety cap. A final_answer accompanied by other tool calls in the same step is the canonical act-and-answer pattern — the loop terminates without an extra round-trip. 2. prepareStep is composed with a safety net that, on the cap step, forces toolChoice { type: 'tool', toolName: 'final_answer' } if the model has been calling tools without ever converging on final_answer. This guarantees a reply on the wire even in pathological cases where the model would otherwise burn its step budget on client-tool round-trips. 3. Server-side recovery (SAGE-248) — if the model fails to call final_answer naturally on any single turn, the agent runner retries that turn with forced tool_choice. Anthropic's API enforces forced tool choice strictly; the recovery is guaranteed to produce a final_answer chunk.

If you pass your own stopWhen or prepareStep, they take precedence — ContentAgent doesn't reach into them.

Applications

Each application key uniquely identifies a deployed Sanity Studio workspace. Since multiple studios can share the same project ID and dataset, the application key disambiguates which one to target.

List available applications for your organization, then target one by its key:

You can also set a default application on the provider so every agent and .prompt() call inherits it:

Configuration

Pass a config object to control agent behavior:

Config fields

| Field | Type | Description |

| instruction | string | Custom instruction included in the system prompt | | userMessageContext | Record | Key-value pairs appended to each user message as XML tags | | capabilities | object | Controls what operations the agent can perform (read, write) | | filter | object | GROQ boolean expressions for document access control | | perspectives | object | Perspective locking for read and write operations |

Capabilities

Each capability can be true, false, or a preset object:

One-shot prompts

For stateless single-turn requests, use the provider's .prompt() method directly — no thread, no agent class:

Studio usage

createStudioAgent makes the provider work inside Sanity Studio with no token or manual configuration. It derives the API host, organization ID, and application from the Studio context:

The factory call is synchronous — async setup (org ID fetch, application resolution) runs lazily on the first API call and is cached at the module level. Wrap in useMemo so the provider and agent keep stable identities across renders.

Since there is no token in a Studio context, credentials: 'include' is set on all fetch calls automatically so the browser sends session cookies. The base URL is derived from the client's project-scoped getUrl method.

Using with useChat

For a streaming chat UI, pair with DirectChatTransport and useChat from the AI SDK:

Lower-level helpers

If you need more control than ContentAgent provides, the underlying primitives are still exported:

• provider.agent(threadId, settings) — returns a raw LanguageModelV3 you can pass to streamText/generateText/ToolLoopAgent directly • fromClient(client, workspace) — derives baseURL and application from a Sanity client • provider.resolveApplication(client, workspace) — fetches applications and matches by resource ID + workspace name

License

MIT

Description from the npm listing.