docs: use Convex AI Gateway in agent examples

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-5-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-5-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

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:

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 ai convex
 ```
 
 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-5-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({

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-5-mini"),
     prompt: "Tell me a joke",
     abortSignal: streamer.abortController.signal,
     onError: (error) => {