@coder/ai-sdk-agent weekly downloads statistics

@coder/ai-sdk-agent

A Vercel AI SDK agent backed by Coder Agents, Coder's server‑side agent runtime. new CoderAgent(...) implements the AI SDK's Agent interface (generate() / stream()): script it, stream from it, and attach your own tools exactly like the SDK's own ToolLoopAgent.

Coder Agents runs the complete agent loop server‑side: the multi‑step tool loop, built‑in tools, MCP, sub‑agents, multi‑provider model routing, and automatic context compaction. This package bridges it to the AI SDK's client‑side loop without re‑implementing the loop.

Status: targets Coder's stable chat API (/api/v2/chats), available since Coder 2.37.0 (September 1, 2026). This package remains pre‑1.0. See API compatibility for older deployments.

Contents

| Get started | Build | Reference | Run in production |

| Install | Custom tools | Auth | Timeouts & cancellation | | Quick start | Files | Configuration | Handling errors | | Examples | Structured output | API compatibility | Cleanup | | Agent vs. provider | Sessions | How it works | Usage & cost | | | Rehydrating chat history | Testing | Observability | | | Watching chats | Limitations | Workspaces & quota | | | Workspace previews | | Durable workflows | | | Sources | | |

Agent vs. provider — which package?

| | @coder/ai-sdk-agent (this package) | @coder/ai-sdk-provider |

| What runs | Coder's server‑side agent: tool loop, built‑in tools, MCP servers, workspace‑scoped file/shell tools, sub‑agents, and compaction, on the deployment | Plain model calls through Coder's AI Gateway. A normal AI SDK provider: generateText, streamText, generateObject | | Server state | Each CoderAgent is one server chat ("session"), bound to at most one workspace | No chat, no workspace; natively cancelable | | Structured output | Through a tool call (Structured output) | generateObject, schema‑constrained | | Reach for it when | You need server‑side tools, MCP, or a workspace | You just need a model (plan / extract / summarize / classify) |

They compose: a multi‑step pipeline often uses the provider for its pure text/JSON steps and the Agent only for the steps that touch tools.

Install

Requires Node ≥ 22 and ai v7. The constructors throw an actionable error when another ai major is detected, instead of failing cryptically mid‑generation. The guard fails open when the installed version can't be resolved.

Quick start

generate() returns a real AI SDK GenerateTextResult; stream() returns a real StreamTextResult (.textStream, .fullStream, .toUIMessageStream(), .steps, .usage, …). Because CoderAgent _is_ an Agent, it composes with the rest of the AI SDK.

Examples

Runnable scripts in examples/ run against a real deployment via tsx:

Each example creates a new chat and archives it when done; none touches workspaces. Details: examples/README.md.

Custom tools

Tools you pass are registered with Coder Agents as client‑executed ("dynamic") tools; your execute runs in your process. This is the standard AI SDK tool loop:

1. The model calls your tool, and the run pauses on the server. 2. The AI SDK runs your tool's execute. 3. This package submits the result back, and the run resumes.

• Give tools an execute for scripting use; the loop runs to completion automatically. • Coder's own server‑side tools (file editing, shell, MCP, …) still run on the server. They appear in the transcript as providerExecuted tool calls/results: you observe them, you don't execute them.

Since v0.2.1: server tools stream as dynamic-tool parts

Server‑executed tools stream with dynamic: true: they aren't in your ToolSet, and the AI SDK only accepts unknown tool names on dynamic calls. In UI message streams they therefore surface as dynamic-tool parts rather than tool-{name} parts. Key off toolName, not part.type, when rendering them.

Files

Pick by whether the model should read the file or operate on it.

Chat attachments carry content for the model to read (a PDF, image, CSV…). Drop a native AI SDK file part into a message and it's uploaded transparently:

To upload once and reuse across turns, use attach(). It also accepts a Blob/File or stream; fs.openAsBlob avoids reading the whole file into memory:

Attachments are capped at 10 MiB and restricted to this media‑type allowlist: application/pdf, application/json, text/{plain,markdown,csv}, image/{png,jpeg,gif,webp}. Oversized or unsupported files throw a clear error up front.

Workspace files are material for the agent to operate on: a zip of assets, a dataset, a binary — anything outside the allowlist or over the cap. Write it onto the workspace filesystem and let the agent's tools take over.

This needs a workspaceFiles adapter. The agent core stays dependency‑free, so whoever holds a workspace connection supplies a few‑line adapter:

Structured output

Coder Agents has no server‑side response_format, so CoderAgent cannot constrain what the model says to a JSON schema. A responseFormat / experimental_output request emits a warning and is best‑effort at most.

• Pure text‑in / JSON‑out, no server‑side tools → use @coder/ai-sdk-provider with generateObject / Output.object (schema‑constrained; requires AI Gateway on the deployment). • The answer must come out of an agent run (server‑side tools, MCP, a workspace) → have the model submit its answer by _calling a tool_ whose inputSchema is your Zod schema. The answer arrives as the tool call's typed input.

The tool pattern needs four rules to stay robust (validate client‑side, never stop on the call, and more). Guide: docs/structured-output.md. Copyable helper: examples/06-structured-output.ts.

Sessions

One CoderAgent instance maps to one chat ("session") on the Coder server. The chat is created on the first turn and reused by later generate()/stream() calls, with history kept server‑side. agent.chatId is the current chat id.

| Call | What it does |…

Description from the npm listing.