From d3141261ce29364db23aaab75e6df71af0ed1d6e Mon Sep 17 00:00:00 2001 From: Ian Macartney <366683+ianmacartney@users.noreply.github.com> Date: Fri, 2 Oct 2026 16:55:42 -0700 Subject: [PATCH 1/3] docs: use Convex AI Gateway in agent examples --- docs/agent-usage.mdx | 15 +++++++++------ docs/getting-started.mdx | 26 ++++++++++++++++++++------ docs/streaming.mdx | 7 +++++-- 3 files changed, 34 insertions(+), 14 deletions(-) diff --git a/docs/agent-usage.mdx b/docs/agent-usage.mdx index 669e78e3..f3502f1d 100644 --- a/docs/agent-usage.mdx +++ b/docs/agent-usage.mdx @@ -18,14 +18,17 @@ structured LLM outputs, or a myriad of other techniques via custom code. ## Basic Agent definition +These examples use the [Convex AI Gateway](https://docs.convex.dev/ai-gateway). +See [Getting Started](./getting-started.mdx) for installation and requirements. + ```ts import { components } from "./_generated/api"; import { Agent } from "@convex-dev/agent"; -import { openai } from "@ai-sdk/openai"; +import { convexGateway } from "@convex-dev/ai-sdk-provider"; const agent = new Agent(components.agent, { name: "Basic Agent", - languageModel: openai.chat("gpt-4o-mini"), + languageModel: convexGateway("openai/gpt-4o-mini"), }); ``` @@ -195,23 +198,23 @@ returning a text response. ## Customizing the agent -The agent by default only needs a `chat` model to be configured. However, for +The agent by default only needs a `languageModel` to be configured. However, for vector search, you'll need an `embeddingModel`. A `name` is helpful to attribute each message to a specific agent. Other options are defaults that can be over-ridden at each LLM call-site. ```ts import { tool, stepCountIs } from "ai"; -import { openai } from "@ai-sdk/openai"; +import { convexGateway } from "@convex-dev/ai-sdk-provider"; import { z } from "zod/v3"; import { Agent, createTool, type Config } from "@convex-dev/agent"; import { components } from "./_generated/api"; const sharedDefaults = { // The language model to use for the agent. - languageModel: openai.chat("gpt-4o-mini"), + languageModel: convexGateway("openai/gpt-4o-mini"), // Embedding model to power vector search of message history (RAG). - embeddingModel: openai.embedding("text-embedding-3-small"), + embeddingModel: convexGateway.embeddingModel("openai/text-embedding-3-small"), // Used for fetching context messages. See https://docs.convex.dev/agents/context contextOptions, // Used for storing messages. See https://docs.convex.dev/agents/messages diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx index 647b5550..113cca62 100644 --- a/docs/getting-started.mdx +++ b/docs/getting-started.mdx @@ -13,10 +13,19 @@ Run `npm create convex` or follow any of the ## Installation -Install the component package: - -```ts -npm install @convex-dev/agent +These examples use the [Convex AI Gateway](https://docs.convex.dev/ai-gateway), +available to paid teams on Convex Cloud and +[project-linked local deployments](https://docs.convex.dev/ai-gateway/setup#local-development). +See [Gateway setup](https://docs.convex.dev/ai-gateway/setup#vercel-ai-sdk) for +package and Node.js runtime requirements. On the Free plan, use an +[AI SDK provider](https://ai-sdk.dev/providers/ai-sdk-providers) with your own +API key stored in an +[environment variable](https://docs.convex.dev/production/environment-variables). + +Install the component and Gateway provider: + +```sh +npm install @convex-dev/agent @convex-dev/ai-sdk-provider@^0.2.0 ai@^7.0.105 convex@latest ``` Create a `convex.config.ts` file in your app's `convex/` folder and install the @@ -38,14 +47,18 @@ successfully run once before you start defining Agents. ## Defining your first Agent +The Gateway provider obtains a service token automatically when the model is +called inside a Convex action; no provider API key is needed. See +[Gateway setup](https://docs.convex.dev/ai-gateway/setup) for details. + ```ts import { components } from "./_generated/api"; import { Agent, stepCountIs } from "@convex-dev/agent"; -import { openai } from "@ai-sdk/openai"; +import { convexGateway } from "@convex-dev/ai-sdk-provider"; const agent = new Agent(components.agent, { name: "My Agent", - languageModel: openai.chat("gpt-4o-mini"), + languageModel: convexGateway("openai/gpt-4o-mini"), instructions: "You are a weather forecaster.", tools: { getWeather, getGeocoding }, stopWhen: stepCountIs(3), @@ -56,6 +69,7 @@ const agent = new Agent(components.agent, { ```ts import { action } from "./_generated/server"; +import { createThread } from "@convex-dev/agent"; import { v } from "convex/values"; export const helloWorld = action({ diff --git a/docs/streaming.mdx b/docs/streaming.mdx index 44dff764..59901e4f 100644 --- a/docs/streaming.mdx +++ b/docs/streaming.mdx @@ -195,12 +195,15 @@ The requirements for reading and writing the streams are just that they use a `threadId` from the Agent component, and that each stream is saved with a distinct `order`, for ordering on the client side. +The example uses the [Convex AI Gateway](https://docs.convex.dev/ai-gateway); +see [Getting Started](./getting-started.mdx) for installation and requirements. + ```ts import { components } from "./_generated/api"; import { type ActionCtx } from "./_generated/server"; import { DeltaStreamer, compressUIMessageChunks } from "@convex-dev/agent"; import { streamText } from "ai"; -import { openai } from "@ai-sdk/openai"; +import { convexGateway } from "@convex-dev/ai-sdk-provider"; async function stream(ctx: ActionCtx, threadId: string, order: number) { const streamer = new DeltaStreamer( @@ -224,7 +227,7 @@ async function stream(ctx: ActionCtx, threadId: string, order: number) { ); // Do the normal streaming with the AI SDK const response = streamText({ - model: openai.chat("gpt-4o-mini"), + model: convexGateway("openai/gpt-4o-mini"), prompt: "Tell me a joke", abortSignal: streamer.abortController.signal, onError: (error) => { From 7cc0576bc8dc1fd8c946ba607dfa55f8862b7973 Mon Sep 17 00:00:00 2001 From: Ian Macartney <366683+ianmacartney@users.noreply.github.com> Date: Fri, 2 Oct 2026 16:59:07 -0700 Subject: [PATCH 2/3] docs: preserve current Gateway models and installation guidance --- docs/agent-usage.mdx | 4 ++-- docs/getting-started.mdx | 4 ++-- docs/streaming.mdx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/agent-usage.mdx b/docs/agent-usage.mdx index f3502f1d..15493159 100644 --- a/docs/agent-usage.mdx +++ b/docs/agent-usage.mdx @@ -28,7 +28,7 @@ import { convexGateway } from "@convex-dev/ai-sdk-provider"; const agent = new Agent(components.agent, { name: "Basic Agent", - languageModel: convexGateway("openai/gpt-4o-mini"), + languageModel: convexGateway("openai/gpt-5-mini"), }); ``` @@ -212,7 +212,7 @@ import { components } from "./_generated/api"; const sharedDefaults = { // The language model to use for the agent. - languageModel: convexGateway("openai/gpt-4o-mini"), + languageModel: convexGateway("openai/gpt-5-mini"), // Embedding model to power vector search of message history (RAG). embeddingModel: convexGateway.embeddingModel("openai/text-embedding-3-small"), // Used for fetching context messages. See https://docs.convex.dev/agents/context diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx index 113cca62..735e0061 100644 --- a/docs/getting-started.mdx +++ b/docs/getting-started.mdx @@ -25,7 +25,7 @@ API key stored in an Install the component and Gateway provider: ```sh -npm install @convex-dev/agent @convex-dev/ai-sdk-provider@^0.2.0 ai@^7.0.105 convex@latest +npm install @convex-dev/agent @convex-dev/ai-sdk-provider ai convex ``` Create a `convex.config.ts` file in your app's `convex/` folder and install the @@ -58,7 +58,7 @@ import { convexGateway } from "@convex-dev/ai-sdk-provider"; const agent = new Agent(components.agent, { name: "My Agent", - languageModel: convexGateway("openai/gpt-4o-mini"), + languageModel: convexGateway("openai/gpt-5-mini"), instructions: "You are a weather forecaster.", tools: { getWeather, getGeocoding }, stopWhen: stepCountIs(3), diff --git a/docs/streaming.mdx b/docs/streaming.mdx index 59901e4f..7ae9409c 100644 --- a/docs/streaming.mdx +++ b/docs/streaming.mdx @@ -227,7 +227,7 @@ async function stream(ctx: ActionCtx, threadId: string, order: number) { ); // Do the normal streaming with the AI SDK const response = streamText({ - model: convexGateway("openai/gpt-4o-mini"), + model: convexGateway("openai/gpt-5-mini"), prompt: "Tell me a joke", abortSignal: streamer.abortController.signal, onError: (error) => { From 600f850456b204eb4652598939f3dc9430626fca Mon Sep 17 00:00:00 2001 From: Ian Macartney <366683+ianmacartney@users.noreply.github.com> Date: Fri, 2 Oct 2026 17:08:20 -0700 Subject: [PATCH 3/3] docs: include OpenTelemetry API in tracing setup --- docs/debugging.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/debugging.mdx b/docs/debugging.mdx index 30943c19..7c7cbdcb 100644 --- a/docs/debugging.mdx +++ b/docs/debugging.mdx @@ -49,9 +49,9 @@ const supportAgent = new Agent(components.agent, { The AI SDK can emit OpenTelemetry spans with the model, token usage, prompt, and response for generate and stream calls. Install `@ai-sdk/otel`, -`@opentelemetry/exporter-trace-otlp-http`, `@opentelemetry/resources`, and -`@opentelemetry/sdk-trace-base`, then register the AI SDK's OpenTelemetry -integration to enable them. +`@opentelemetry/api`, `@opentelemetry/exporter-trace-otlp-http`, +`@opentelemetry/resources`, and `@opentelemetry/sdk-trace-base`, then register +the AI SDK's OpenTelemetry integration to enable them. To export them to an OTLP backend, register a tracer provider and the AI SDK integration: