Update left nav for docs + agents doc (#36476)

GitOrigin-RevId: 538a82feef01934a28c2a1773726012b21f8668b

Author: ikhare

npm-packages/docs/docs/agents.mdx

@@ -0,0 +1,105 @@
+---
+title: "AI Agents"
+sidebar_position: 100
+description: "Building AI Agents with Convex"
+---
+
+# Building AI Agents with Convex
+
+Convex provides a powerful platform for building AI agents through its robust
+set of components.
+
+## Why Convex for AI Agents?
+
+Convex offers several advantages for building AI agents:
+
+1. **Durable Execution**: Long-running workflows that survive server restarts
+2. **Real-time State Management**: Reactive state updates for agent progress
+3. **Built-in Persistence**: Store conversation history and agent state
+4. **Parallel Processing**: Run multiple agent tasks concurrently
+5. **Error Handling**: Robust retry mechanisms for API calls
+
+## Core Components
+
+The [Agent](https://www.convex.dev/components/agent) and
+[Workflow](https://www.convex.dev/components/workflow) components can be used
+together to create powerful long running agents with memory.
+
+Learn more by reading:
+[AI Agents with Built-in Memory](https://stack.convex.dev/ai-agents).
+
+Sample code:
+
+```typescript
+// Define an agent similarly to the AI SDK
+const supportAgent = new Agent(components.agent, {
+  chat: openai.chat("gpt-4o-mini"),
+  textEmbedding: openai.embedding("text-embedding-3-small"),
+  instructions: "You are a helpful assistant.",
+  tools: { accountLookup, fileTicket, sendEmail },
+});
+
+// Use the agent from within a normal action:
+export const createThread = action({
+  args: { prompt: v.string() },
+  handler: async (ctx, { prompt }) => {
+    const { threadId, thread } = await supportAgent.createThread(ctx);
+    const result = await thread.generateText({ prompt });
+    return { threadId, text: result.text };
+  },
+});
+
+// Pick up where you left off, with the same or a different agent:
+export const continueThread = action({
+  args: { prompt: v.string(), threadId: v.string() },
+  handler: async (ctx, { prompt, threadId }) => {
+    // This includes previous message history from the thread automatically.
+    const { thread } = await anotherAgent.continueThread(ctx, { threadId });
+    const result = await thread.generateText({ prompt });
+    return result.text;
+  },
+});
+
+// Or use it within a workflow, specific to a user:
+export const supportAgentStep = supportAgent.asAction({ maxSteps: 10 });
+
+const workflow = new WorkflowManager(components.workflow);
+const s = internal.example; // where steps are defined
+
+export const supportAgentWorkflow = workflow.define({
+  args: { prompt: v.string(), userId: v.string(), threadId: v.string() },
+  handler: async (step, { prompt, userId, threadId }) => {
+    const suggestion = await step.runAction(s.supportAgentStep, {
+      threadId,
+      generateText: { prompt },
+    });
+    const polished = await step.runAction(s.adaptSuggestionForUser, {
+      suggestion,
+      userId,
+    });
+    await step.runMutation(s.sendUserMessage, {
+      userId,
+      message: polished.message,
+    });
+  },
+});
+```
+
+## Other Components
+
+Convex also provides other components to help you build reliable AI
+applications.
+
+The
+[Persistent Text Streaming](https://www.convex.dev/components/persistent-text-streaming)
+component provides a React hook for streaming text from HTTP actions while
+simultaneously storing the data in the database. This persistence allows the
+text to be accessed after the stream ends or by other users.
+
+The [Action Retrier](https://www.convex.dev/components/retrier) Component is
+useful for one of flaky AI calls that you want to automatically retry. It will
+run the action and retry it on failure, sleeping with exponential backoff, until
+the action succeeds or the maximum number of retries is reached.
+
+The [Workpool](https://www.convex.dev/components/workpool) Component lets you
+create tiers of parallelism to handle large number of external requests.

npm-packages/docs/sidebars.js

@@ -107,13 +107,29 @@ const sidebars = {
       items: [{ type: "autogenerated", dirName: "components" }],
       className: "convex-sidebar-components",
     },
+
+    {
+      type: "html",
+      value: '<hr class="convex-menu-divider" />',
+      defaultStyle: false,
+    },
+    {
+      type: "html",
+      value: '<div class="convex-menu-header">Guides</div>',
+      defaultStyle: false,
+    },
     {
       type: "category",
       label: "AI Code Gen",
       link: { type: "doc", id: "ai" },
       items: [{ type: "autogenerated", dirName: "ai" }],
       className: "convex-sidebar-ai",
     },
+    {
+      type: "doc",
+      id: "agents",
+      className: "convex-sidebar-ai-agents",
+    },
     {
       type: "category",
       label: "Testing",

npm-packages/docs/src/css/custom.css

@@ -721,6 +721,10 @@ html[data-theme="dark"] .convex-menu-header {
   --convex-icon: url("../../static/img/sidebar-icons/magic-wand.svg");
 }
 
+.convex-sidebar-ai-agents {
+  --convex-icon: url("../../static/img/sidebar-icons/bot.svg");
+}
+
 .convex-sidebar-production {
   --convex-icon: url("../../static/img/sidebar-icons/paper-plane.svg");
 }