chore: docs sync from main — needs review (2026-04-30)

Author: copilotkit-devops-bot[bot]

showcase/shell-docs/src/content/docs/ag-ui-middleware.mdx

@@ -0,0 +1,69 @@
+---
+title: AG-UI Middleware
+icon: lucide/Layers
+description: Configure AG-UI middleware for your CopilotKit application.
+hideTOC: true
+---
+AG-UI agents expose a middleware layer via `agent.use(middleware)`, a powerful hook for logging, guardrails, request transformation, and event rewriting. Because CopilotKit runs the middleware server-side inside the [Copilot Runtime](/backend/copilot-runtime), it executes in a trusted environment where the client cannot tamper with it.
+
+## Defining a Middleware
+
+A middleware extends the `Middleware` base class from `@ag-ui/client` and implements `run(input, next)`. It receives the incoming `RunAgentInput` and returns an `Observable<BaseEvent>`, typically by subscribing to `runNextWithState(input, next)` and transforming the stream:
+
+```ts title="my-middleware.ts"
+import {
+  Middleware,
+  RunAgentInput,
+  AbstractAgent,
+  BaseEvent,
+} from "@ag-ui/client";
+import { Observable } from "rxjs";
+
+export class LoggingMiddleware extends Middleware {
+  run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent> {
+    return new Observable<BaseEvent>((subscriber) => {
+      const sub = this.runNextWithState(input, next).subscribe({
+        next: ({ event }) => {
+          console.log("[agent event]", event.type);
+          subscriber.next(event);
+        },
+        error: (err) => subscriber.error(err),
+        complete: () => subscriber.complete(),
+      });
+      return () => sub.unsubscribe();
+    });
+  }
+}
+```
+
+## Attaching Middleware to an Agent
+
+Call `.use(...)` on the agent before registering it with the runtime:
+
+```ts title="app/api/copilotkit/route.ts"
+import { CopilotRuntime } from "@copilotkit/runtime";
+import { LangGraphAgent } from "@copilotkit/runtime/langgraph";
+import { LoggingMiddleware } from "./my-middleware";
+
+const agent = new LangGraphAgent({
+  deploymentUrl: process.env.LANGGRAPH_DEPLOYMENT_URL!,
+  graphId: "sample_agent",
+});
+agent.use(new LoggingMiddleware());
+
+const runtime = new CopilotRuntime({
+  agents: { default: agent },
+});
+```
+
+## Built-in Middleware
+
+The runtime ships first-class middleware options you can enable directly on `CopilotRuntime` without calling `.use()` on each agent:
+
+- **`a2ui`** — apply `A2UIMiddleware` to all (or a subset of) registered agents. See [Copilot Runtime → A2UI](/backend/copilot-runtime#a2ui).
+- **`mcpApps`** — configure MCP servers for all agents from a single place. See [Copilot Runtime → mcpApps](/backend/copilot-runtime#mcpapps).
+
+## Related
+
+- [Copilot Runtime](/backend/copilot-runtime) — the server-side layer that executes middleware.
+- [AG-UI Protocol](/backend/ag-ui) — the event stream the middleware operates on.

showcase/shell-docs/src/content/docs/deploy/agentcore.mdx

@@ -0,0 +1,7 @@
+---
+title: AWS AgentCore
+icon: "lucide/Cloud"
+description: Add a production-ready frontend to your AWS AgentCore agents with CopilotKit.
+hideHeader: true
+---
+<Content />

showcase/shell-docs/src/content/docs/inspector.mdx

@@ -1,79 +1,11 @@
 ---
 title: Inspector
 icon: "lucide/SearchCheck"
-description: Overlay for debugging AG-UI events, agent state, frontend tools, context, and more — live, on top of your app.
+description: Inspector for debugging actions, readables, agent status, messages, and context.
 ---
-
-<video
-  src="https://cdn.copilotkit.ai/docs/copilotkit/videos/inspector.mp4"
-  style={{ width: "100%", borderRadius: "0.5rem", marginBottom: "1rem" }}
-  loop
-  playsInline
-  controls
-  autoPlay
-  muted
-/>
-
-## What it shows
-
-The **CopilotKit Inspector** is a built-in debugging overlay that sits on top of your app. It gives you live visibility into everything happening between your frontend and your Built-in Agent:
-
-| Panel | What you see |
-| --- | --- |
-| **AG-UI Events** | The raw event stream between the runtime and your agent, in real time — including `RUN_STARTED`, `TEXT_MESSAGE_CONTENT`, `TOOL_CALL_*`, `STATE_SNAPSHOT`, and any custom events. |
-| **Available Agents** | Which agents CopilotKit has discovered via `/info` and which one is currently active. |
-| **Agent State** | The current `agent.state` tree, rerendered as it updates. Great for debugging [shared state](./shared-state) flows. |
-| **Frontend Tools** | Every tool registered via `useFrontendTool`, `useComponent`, `useHumanInTheLoop`, or `useRenderTool`, along with its parameter schema. |
-| **Context** | The [`useAgentContext`](/langgraph-python/agent-app-context) entries the agent currently receives, plus any document context you've attached. |
-
-## When should I use it?
-
-Reach for the inspector when:
-
-- Your agent seems to ignore a tool you registered — check the **Frontend Tools** panel to confirm the registration landed.
-- A chat response looks "stuck" — the **AG-UI Events** panel shows exactly which event type arrived last.
-- You think state isn't syncing — the **Agent State** panel updates on every `onStateSnapshotEvent` / `onStateDeltaEvent`.
-- You want to confirm the Built-in Agent is reading the correct `useAgentContext` value.
-
-## Getting a license key
-
-The inspector is a **premium** feature. Grab a **free** `publicLicenseKey` at [https://cloud.copilotkit.ai](https://cloud.copilotkit.ai) and pass it to your provider:
-
-```tsx title="app/layout.tsx"
-import { CopilotKitProvider } from "@copilotkit/react-core/v2";
-
-export default function RootLayout({ children }) {
-  return (
-    <CopilotKitProvider
-      runtimeUrl="/api/copilotkit"
-      publicLicenseKey={process.env.NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY}
-    >
-      {children}
-    </CopilotKitProvider>
-  );
-}
-```
-
-The inspector is enabled by default whenever a valid license key is present.
-
-## Disabling it
-
-Sometimes you want the license key (for other premium features) but not the inspector overlay:
-
-```tsx
-<CopilotKitProvider
-  publicLicenseKey={process.env.NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY}
-  enableInspector={false}
->
-  {children}
-</CopilotKitProvider>
-```
+<Inspector />
 
 <Callout type="info">
-The inspector is **automatically disabled in production builds**. You don't need to guard it behind `process.env.NODE_ENV` or strip it manually — production bundles ship without the overlay code.
+  Want to preview A2UI catalog components directly in your editor? See the [VS Code Extension](/vs-code-extension)
+  for live preview with hot-reload.
 </Callout>
-
-## Related
-
-- [Debug mode](./troubleshooting/error-debugging) — console logging for the same event pipeline without a UI overlay.
-- [Observability](./premium/observability) — production-grade event + error hooks for Sentry, Datadog, and analytics.

showcase/shell-docs/src/content/docs/integrations/agent-spec/quickstart.mdx

@@ -334,7 +334,7 @@ hideTOC: true
           Wrap your application with the CopilotKit provider:
 
           ```tsx title="app/layout.tsx"
-          import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
+          import { CopilotKit } from "@copilotkit/react-core"; // [!code highlight]
           import "@copilotkit/react-ui/v2/styles.css";
           import './globals.css';
 

showcase/shell-docs/src/content/docs/integrations/aws-strands/deploy-agentcore.mdx

@@ -0,0 +1,7 @@
+---
+title: AWS AgentCore
+icon: "lucide/Cloud"
+description: Add a production-ready frontend to your AWS AgentCore agents with CopilotKit.
+hideHeader: true
+---
+<Content framework="strands" />

showcase/shell-docs/src/content/docs/integrations/aws-strands/quickstart.mdx

@@ -350,6 +350,10 @@ Before you begin, you'll need the following:
 
 </Steps>
 
+## Deploying to AWS?
+
+If you're planning to deploy your Strands agent to AWS Bedrock AgentCore, see the [AgentCore deploy guide](/agentcore).
+
 ## What's next?
 
 Now that you have your basic agent setup, explore these advanced features:

showcase/shell-docs/src/content/docs/integrations/built-in-agent/server-tools.mdx

@@ -34,7 +34,7 @@ const getWeather = defineTool({
 const builtInAgent = new BuiltInAgent({
   model: "openai:gpt-5.4-mini",
   tools: [getWeather],
-  maxSteps: 2, // Important for tool calls
+  maxSteps: 2                   //Important for tool calls
 });
 ```
 
@@ -76,7 +76,7 @@ const createTicket = defineTool({
 const builtInAgent = new BuiltInAgent({
   model: "openai:gpt-5.4-mini",
   tools: [searchDocs, createTicket], // [!code highlight]
-  maxSteps: 2,
+  maxSteps: 2                        
 });
 ```
 

showcase/shell-docs/src/content/docs/integrations/deepagents/frontend-tools.mdx

@@ -0,0 +1,134 @@
+---
+title: Frontend Tools
+icon: "lucide/Wrench"
+description: Create frontend tools and use them within your Deep Agents agent.
+hideTOC: true
+---
+{/* TODO: swap feature-viewer URLs back to /deepagents/ once the dojo supports that route */}
+<IframeSwitcher
+  id="frontend-actions-example"
+  exampleUrl="https://feature-viewer.copilotkit.ai/langgraph/feature/agentic_chat?sidebar=false&chatDefaultOpen=false"
+  codeUrl="https://feature-viewer.copilotkit.ai/langgraph/feature/agentic_chat?view=code&sidebar=false&codeLayout=tabs"
+  exampleLabel="Demo"
+  codeLabel="Code"
+  height="700px"
+/>
+
+## What is this?
+Frontend tools enable you to define client-side functions that your Deep Agents agent can invoke, with execution happening entirely in the user's browser. When your agent calls a frontend tool,
+the logic runs on the client side, giving you direct access to the frontend environment.
+
+This can be utilized to let your agent control the UI, for generative UI, or for Human-in-the-loop interactions.
+
+In this guide, we cover the use of frontend tools driving and interacting with the UI.
+
+## When should I use this?
+Use frontend tools when you need your agent to interact with client-side primitives such as:
+- Reading or modifying React component state
+- Accessing browser APIs like localStorage, sessionStorage, or cookies
+- Triggering UI updates or animations
+- Interacting with third-party frontend libraries
+- Performing actions that require the user's immediate browser context
+
+## Implementation
+
+<Steps>
+    <Step>
+        ### Run and connect your agent
+       <RunAndConnect />
+    </Step>
+
+    <Step>
+        ### Create a frontend tool
+
+        First, you'll need to create a frontend tool using the [useFrontendTool](/reference/v2/hooks/useFrontendTool) hook. Here's a simple one to get you started
+        that says hello to the user.
+
+        ```tsx title="page.tsx"
+        import { z } from "zod";
+        import { useFrontendTool } from "@copilotkit/react-core/v2" // [!code highlight]
+
+        export function Page() {
+          // ...
+
+          // [!code highlight:12]
+          useFrontendTool({
+            name: "sayHello",
+            description: "Say hello to the user",
+            parameters: z.object({
+              name: z.string().describe("The name of the user to say hello to"),
+            }),
+            handler: async ({ name }) => {
+              alert(`Hello, ${name}!`);
+              return `Said hello to ${name}!`;
+            },
+          });
+
+          // ...
+        }
+        ```
+    </Step>
+    <Step>
+        ### Install the CopilotKit SDK
+
+        Now, we'll need to modify the agent to access these frontend tools. In your terminal, navigate to your agent's folder and continue from there!
+
+        <InstallSDKSnippet/>
+    </Step>
+    <Step>
+        ### Wire CopilotKit state into your agent
+
+        To access the frontend tools provided by CopilotKit, register the CopilotKit state alongside any custom state your agent needs.
+
+        <Tabs groupId="agent_language" items={['Python', 'TypeScript']} persist>
+            <Tab value="Python">
+                In Python, inherit from `CopilotKitState` in your agent's state definition:
+
+                ```python title="agent.py"
+                from copilotkit import CopilotKitState # [!code highlight]
+
+                class YourAgentState(CopilotKitState): # [!code highlight]
+                    your_additional_properties: str
+                ```
+            </Tab>
+            <Tab value="TypeScript">
+                In TypeScript, define your custom state as a middleware via `createMiddleware` and compose it with `copilotkitMiddleware`:
+
+                ```ts title="agent.ts"
+                import { createMiddleware } from "langchain";
+                import { copilotkitMiddleware } from "@copilotkit/sdk-js/langgraph"; // [!code highlight]
+                import { z } from "zod";
+
+                export const yourStateMiddleware = createMiddleware({
+                    name: "YourAgentState",
+                    stateSchema: z.object({
+                        yourAdditionalProperty: z.string().optional(),
+                    }),
+                });
+
+                // Pass both middlewares when constructing the agent:
+                // createDeepAgent({ middleware: [yourStateMiddleware, copilotkitMiddleware], ... })
+                ```
+            </Tab>
+        </Tabs>
+
+        By doing this, your agent's state will include the `copilotkit` property, which contains the frontend tools that can be accessed and invoked.
+    </Step>
+    <Step>
+        ### Accessing Frontend Tools
+
+        Once your agent's state includes the `copilotkit` property, you can access the frontend tools and utilize them within your agent's logic.
+
+        Here's how you can call a frontend tool from your agent:
+
+        <FrontEndToolsImpl />
+
+        These tools are automatically populated by CopilotKit and are compatible with LangChain's tool call definitions, making it straightforward to integrate them into your agent's workflow.
+    </Step>
+    <Step>
+        ### Give it a try!
+        You've now given your agent the ability to directly call any frontend tools you've defined. These tools will be available to the agent where they can be used as needed.
+
+        <video src="https://cdn.copilotkit.ai/docs/copilotkit/images/frontend-actions-demo.mp4" className="rounded-lg shadow-xl" loop playsInline controls autoPlay muted />
+    </Step>
+</Steps>