content-agent 0.7.5 → 0.8.0

package/README.md

@@ -10,81 +10,59 @@ npm install content-agent ai
 
 ## Usage
 
-Create a provider instance with your organization ID and token, then use `.agent(threadId)` to get a model for a conversation thread:
+`ContentAgent` extends the AI SDK's [`ToolLoopAgent`](https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent) — 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.
 
 ```typescript
 import { createContentAgent } from "content-agent";
-import { generateText } from "ai";
+import { ContentAgent } from "content-agent/agent";
 
-const contentAgent = createContentAgent({
+const provider = createContentAgent({
   organizationId: "your-org-id",
   token: "your-sanity-token",
 });
 
-const model = contentAgent.agent("my-thread");
+const agent = new ContentAgent({
+  provider,
+  threadId: "my-thread",
+});
 
-const { text } = await generateText({
-  model,
+const { text } = await agent.generate({
   prompt: "What blog posts do I have?",
 });
 ```
 
-## Streaming
+`provider` is reusable — create it once per organization and instantiate as many `ContentAgent`s as you need.
 
-Use `streamText` from the AI SDK for streaming responses:
+> **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."](https://ai-sdk.dev/blog/ai-sdk-6) `ContentAgent` is that implementation for the Sanity Content Agent — it preconfigures `stopWhen`, `prepareStep`, and `toolChoice` for the agent's tool-response mode so you don't have to.
 
-```typescript
-import { streamText } from "ai";
+> **Migrating from `streamText({ model: provider.agent(threadId) })`?** Nothing breaks — the lower-level API is still supported and works exactly as before. But if you're using tool-response mode (`config.responseMode: 'tool'`) you'll want to 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 [Tool-response mode](#tool-response-mode) below.
+
+## Streaming
 
-const { textStream } = streamText({
-  model: contentAgent.agent("my-thread"),
+```typescript
+const result = await agent.stream({
   prompt: "Summarize my latest content",
 });
 
-for await (const text of textStream) {
+for await (const text of result.textStream) {
   process.stdout.write(text);
 }
 ```
 
-## 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:
-
-```typescript
-const apps = await contentAgent.applications();
-const app = apps.find((app) => app.title === "My Studio");
-
-const model = contentAgent.agent("my-thread", {
-  application: { key: app.key },
-});
-```
-
-You can also set a default application on the provider so every `.agent()` and `.prompt()` call inherits it:
-
-```typescript
-const contentAgent = createContentAgent({
-  organizationId: "your-org-id",
-  token: "your-token",
-  application: resolvedApp,
-});
-
-// No need to pass application per-call
-const model = contentAgent.agent("my-thread");
-```
-
 ## Tools
 
-Pass AI SDK tools to `streamText` or `generateText` — tool schemas are forwarded to the agent, and execution happens locally on the client:
+Pass AI SDK tools to the constructor — schemas are forwarded to the agent, and execution happens locally on the client:
 
 ```typescript
-import { streamText, tool } from "ai";
+import { ContentAgent } from "content-agent/agent";
+import { tool } from "ai";
 import { z } from "zod";
 
-const result = streamText({
-  model: contentAgent.agent("my-thread"),
-  prompt: "Find all draft blog posts and submit them for review.",
+const agent = new ContentAgent({
+  provider,
+  threadId: "my-thread",
   tools: {
     submit_for_review: tool({
       description: "Submit a document for editorial review.",
@@ -103,14 +81,70 @@ const result = streamText({
     }),
   },
 });
+
+const result = await agent.stream({
+  prompt: "Find all draft blog posts and submit them for review.",
+});
+```
+
+## Tool-response mode
+
+Set `config.responseMode: 'tool'` to deliver responses through a server-side `final_answer` tool. This is what the Linear, Slack, and MS Teams integrations use — the agent suppresses raw model text on the wire and emits all output via `final_answer.message`, with structured suggestions and a guaranteed delivery contract.
+
+```typescript
+const agent = new ContentAgent({
+  provider,
+  threadId: "my-thread",
+  tools: { update_issue_status, get_settings },
+  config: {
+    responseMode: "tool",
+    enableReplySuggestions: true,
+  },
+});
+```
+
+In this mode `ContentAgent` adjusts the [loop control](https://ai-sdk.dev/docs/agents/loop-control) primitives to make the agent safe by default:
+
+1. **[`stopWhen`](https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent#stopwhen)** defaults to "stop only when the last step's tool calls are exclusively `final_answer`," plus a [`stepCountIs(20)`](https://ai-sdk.dev/docs/reference/ai-sdk-core/step-count-is) safety cap. A `final_answer` accompanied by other tool calls in the same step is treated as a preamble (the model is signalling more work to do) and the loop continues; a `final_answer` alone ends it.
+2. **[`prepareStep`](https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent#preparestep)** is composed with a safety net that, on the cap step, forces [`toolChoice`](https://ai-sdk.dev/docs/agents/building-agents#tool-choice) `{ type: 'tool', toolName: 'final_answer' }` if the model has been calling tools without ever converging on `final_answer`. This guarantees text on the wire even in pathological cases where the model would otherwise burn its step budget on client tool calls.
+
+If you pass your own `stopWhen` or `prepareStep`, they take precedence — `ContentAgent` doesn't reach into them. Outside tool-response mode the agent is a plain `ToolLoopAgent` with no overrides.
+
+## 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:
+
+```typescript
+const apps = await provider.applications();
+const app = apps.find((app) => app.title === "My Studio");
+
+const agent = new ContentAgent({
+  provider,
+  threadId: "my-thread",
+  application: { key: app.key },
+});
+```
+
+You can also set a default application on the provider so every agent and `.prompt()` call inherits it:
+
+```typescript
+const provider = createContentAgent({
+  organizationId: "your-org-id",
+  token: "your-token",
+  application: resolvedApp,
+});
 ```
 
 ## Configuration
 
-Pass a `config` object to `.agent()` to control behavior:
+Pass a `config` object to control agent behavior:
 
 ```typescript
-const model = contentAgent.agent("my-thread", {
+const agent = new ContentAgent({
+  provider,
+  threadId: "my-thread",
   config: {
     instruction: "You are a helpful content assistant for our marketing team.",
     userMessageContext: {
@@ -131,13 +165,15 @@ const model = contentAgent.agent("my-thread", {
 
 ### Config fields
 
-| Field                | Type                     | Description                                                      |
-| -------------------- | ------------------------ | ---------------------------------------------------------------- |
-| `instruction`        | `string`                 | Custom instruction included in the system prompt                 |
-| `userMessageContext` | `Record<string, string>` | 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                |
+| Field                    | Type                     | Description                                                             |
+| ------------------------ | ------------------------ | ----------------------------------------------------------------------- |
+| `instruction`            | `string`                 | Custom instruction included in the system prompt                        |
+| `userMessageContext`     | `Record<string, string>` | 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                       |
+| `responseMode`           | `'stream' \| 'tool'`     | Set to `'tool'` to deliver responses through the `final_answer` tool    |
+| `enableReplySuggestions` | `boolean`                | When `responseMode: 'tool'`, include reply-suggestion buttons on output |
 
 ### Capabilities
 
@@ -151,6 +187,21 @@ config: { capabilities: { read: true, write: false } }
 config: { capabilities: { read: true, write: { preset: "minimal" } } }
 ```
 
+## One-shot prompts
+
+For stateless single-turn requests, use the provider's `.prompt()` method directly — no thread, no agent class:
+
+```typescript
+const { text } = await provider.prompt(
+  {
+    application: { key: "projectId.datasetName" },
+    config: { capabilities: { read: true, write: false } },
+    instructions: "Be concise",
+  },
+  { message: "List my 5 most recent posts" },
+);
+```
+
 ## 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:
@@ -158,35 +209,42 @@ config: { capabilities: { read: true, write: { preset: "minimal" } } }
 ```typescript
 import { useMemo } from "react";
 import { createStudioAgent } from "content-agent";
+import { ContentAgent } from "content-agent/agent";
 import { useClient, useWorkspace } from "sanity";
 
 function MyComponent() {
   const client = useClient({ apiVersion: "2024-01-01" });
   const { name: workspace } = useWorkspace();
 
-  const contentAgent = useMemo(
+  const provider = useMemo(
     () => createStudioAgent(client, workspace),
     [client, workspace],
   );
 
-  // Use contentAgent.agent(threadId) with useChat, generateText, etc.
+  const agent = useMemo(
+    () => new ContentAgent({ provider, threadId: "my-thread" }),
+    [provider],
+  );
+
+  // Use agent.stream() / agent.generate() with useChat, etc.
 }
 ```
 
-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 keeps a stable identity across renders.
+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` from the AI SDK:
+For a streaming chat UI, pair with [`DirectChatTransport`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/direct-chat-transport) and [`useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) from the AI SDK:
 
 ```tsx
 import { useMemo, useState } from "react";
 import { useClient, useWorkspace } from "sanity";
 import { useChat } from "@ai-sdk/react";
-import { DirectChatTransport, ToolLoopAgent } from "ai";
+import { DirectChatTransport } from "ai";
 import { createStudioAgent } from "content-agent";
+import { ContentAgent } from "content-agent/agent";
 
 function ChatTool() {
   const client = useClient({ apiVersion: "2024-01-01" });
@@ -194,10 +252,9 @@ function ChatTool() {
   const [threadId] = useState(() => `thread-${crypto.randomUUID()}`);
 
   const transport = useMemo(() => {
-    const contentAgent = createStudioAgent(client, workspace);
-    return new DirectChatTransport({
-      agent: new ToolLoopAgent({ model: contentAgent.agent(threadId) }),
-    });
+    const provider = createStudioAgent(client, workspace);
+    const agent = new ContentAgent({ provider, threadId });
+    return new DirectChatTransport({ agent });
   }, [client, workspace, threadId]);
 
   const { messages, sendMessage, status } = useChat({ transport });
@@ -208,10 +265,11 @@ function ChatTool() {
 
 ### Lower-level helpers
 
-If you already know the organization ID and need more control:
+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`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text)/[`generateText`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text)/[`ToolLoopAgent`](https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent) directly
 - `fromClient(client, workspace)` — derives `baseURL` and `application` from a Sanity client
-- `contentAgent.resolveApplication(client, workspace)` — fetches applications and matches by resource ID + workspace name
+- `provider.resolveApplication(client, workspace)` — fetches applications and matches by resource ID + workspace name
 
 ## License