docs(showcase/claude-sdk-python): region markers across 10 cells

Brings claude-sdk-python to feature parity with langgraph-python on the
shell-docs snippet audit. 10 (framework x cell) targets advanced from B
(missing regions) to A (ready), following the patterns established in
CopilotKit#4326 (mastra), CopilotKit#4361 (smalls batch 1), CopilotKit#4363 (ms-agent), and CopilotKit#4369
(google-adk).

Frontend regions (in-place markers):
- agentic-chat: configure-suggestions, provider-setup
- frontend-tools: frontend-tool-handler, frontend-tool-registration
- headless-complete: page-send-message
- open-gen-ui: minimal-provider-setup
- open-gen-ui-advanced: sandbox-function-registration (multi-file:
  page.tsx + sandbox-functions.ts)
- readonly-state-agent-context: context-provider-sketch,
  use-agent-context-call
- tool-rendering: render-weather-tool
- tool-rendering-custom-catchall: use-default-render-tool-wildcard
- tool-rendering-default-catchall: default-catchall-zero-config

Runtime regions (route.ts, in-place):
- open-gen-ui: minimal-runtime-flag
- open-gen-ui-advanced: advanced-runtime-config
  (both names share one block — server config is identical)

Backend regions (Python, in-place):
- subagents: subagent-setup wraps SUB_AGENT_PROMPTS plus _invoke_sub_agent;
  supervisor-delegation-tools wraps _delegation_tool_schema plus
  SUPERVISOR_TOOLS — captures the Claude Agent SDK idiom (Anthropic tool
  schemas plus a manual run loop) rather than langgraph-python's
  @tool/create_agent shape.

Sibling teaching files (production demo carries QA hooks irrelevant to
the docs page):
- agentic-chat/chat-component.snippet.tsx — minimal Chat for the
  prebuilt-chat docs page
- tool-rendering/render-flight-tool.snippet.tsx — flight + catchall
  renderer patterns; production demo only registers a weather renderer
- tool-rendering/weather_tool.snippet.py — single-tool teaching example
  for the Anthropic tool-schema idiom; production agent.py declares
  get_weather inside a shared TOOLS list with dispatch via _execute_tool

Markers are comment-only and stripped from rendered output, so the
runtime demos are byte-for-byte unchanged. No manifest edits.

Author: samjulien

showcase/integrations/claude-sdk-python/src/agents/subagents_agent.py

@@ -54,6 +54,11 @@
 DEFAULT_ANTHROPIC_MODEL = "claude-3-5-sonnet-20241022"
 
 
+# @region[subagent-setup]
+# Each sub-agent is defined by its own system prompt; `_invoke_sub_agent`
+# (below) issues a single-shot Anthropic call as that sub-agent. They
+# don't share memory or tools with the supervisor — the supervisor only
+# ever sees what the sub-agent returns as a tool result.
 # @region[subagents-system-prompts]
 SUB_AGENT_PROMPTS: dict[str, str] = {
     "research_agent": (
@@ -89,6 +94,14 @@
 )
 
 
+# @region[supervisor-delegation-tools]
+# The supervisor delegates by calling tools. Each entry in
+# `SUPERVISOR_TOOLS` is an Anthropic tool schema that the supervisor LLM
+# "calls" to delegate work; the run loop in `run_subagents_agent` (see
+# the subagents-delegation-flow region) runs the matching sub-agent
+# synchronously, records the delegation into shared agent state, and
+# returns the sub-agent's output as a tool_result the supervisor can
+# read on its next step.
 def _delegation_tool_schema(name: str, description: str) -> dict[str, Any]:
     return {
         "name": name,
@@ -128,6 +141,7 @@ def _delegation_tool_schema(name: str, description: str) -> dict[str, Any]:
         "Delegate a critique task. Returns 2-3 actionable critiques.",
     ),
 ]
+# @endregion[supervisor-delegation-tools]
 
 
 # @region[subagents-invocation]
@@ -156,6 +170,7 @@ async def _invoke_sub_agent(
         raise RuntimeError("sub-agent returned empty response")
     return text
 # @endregion[subagents-invocation]
+# @endregion[subagent-setup]
 
 
 def _convert_messages(input_data: RunAgentInput) -> list[dict[str, Any]]:

showcase/integrations/claude-sdk-python/src/app/api/copilotkit-ogui/route.ts

@@ -29,6 +29,8 @@ export const POST = async (req: NextRequest) => {
     const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
       endpoint: "/api/copilotkit-ogui",
       serviceAdapter: new ExperimentalEmptyAdapter(),
+      // @region[minimal-runtime-flag]
+      // @region[advanced-runtime-config]
       // Server-side config is identical for minimal and advanced cells —
       // the advanced behaviour (sandbox -> host function calls) is wired
       // entirely on the frontend via `openGenerativeUI.sandboxFunctions` on
@@ -43,6 +45,8 @@ export const POST = async (req: NextRequest) => {
           agents: ["open-gen-ui", "open-gen-ui-advanced"],
         },
       }),
+      // @endregion[advanced-runtime-config]
+      // @endregion[minimal-runtime-flag]
     });
     return await handleRequest(req);
   } catch (error: unknown) {

showcase/integrations/claude-sdk-python/src/app/demos/agentic-chat/chat-component.snippet.tsx

@@ -0,0 +1,28 @@
+// Docs-only snippet — not imported or rendered. The actual route is served
+// by page.tsx, which carries QA hooks (frontend tools, render tools, agent
+// context) that aren't relevant to the prebuilt-chat docs page. This file
+// gives the docs a minimal Chat definition to point at via the
+// chat-component region without disturbing the runtime demo.
+//
+// Why a sibling file: the bundler walks every file in the demo folder and
+// extracts region markers from each, so a docs-targeted teaching example
+// can live alongside the production demo without being wired into the
+// route. See: showcase/scripts/bundle-demo-content.ts.
+
+import {
+  CopilotChat,
+  useConfigureSuggestions,
+} from "@copilotkit/react-core/v2";
+
+// @region[chat-component]
+export function Chat() {
+  useConfigureSuggestions({
+    suggestions: [
+      { title: "Write a sonnet", message: "Write a short sonnet about AI." },
+    ],
+    available: "always",
+  });
+
+  return <CopilotChat agentId="agentic_chat" className="h-full rounded-2xl" />;
+}
+// @endregion[chat-component]

showcase/integrations/claude-sdk-python/src/app/demos/agentic-chat/page.tsx

@@ -13,9 +13,11 @@ import { z } from "zod";
 
 export default function AgenticChatDemo() {
   return (
+    // @region[provider-setup]
     <CopilotKit runtimeUrl="/api/copilotkit" agent="agentic_chat">
       <Chat />
     </CopilotKit>
+    // @endregion[provider-setup]
   );
 }
 
@@ -68,6 +70,7 @@ function Chat() {
     },
   });
 
+  // @region[configure-suggestions]
   useConfigureSuggestions({
     suggestions: [
       {
@@ -81,6 +84,7 @@ function Chat() {
     ],
     available: "always",
   });
+  // @endregion[configure-suggestions]
 
   return (
     <div

showcase/integrations/claude-sdk-python/src/app/demos/frontend-tools/page.tsx

@@ -22,6 +22,7 @@ function Chat() {
     "var(--copilot-kit-background-color)",
   );
 
+  // @region[frontend-tool-registration]
   useFrontendTool({
     name: "change_background",
     description:
@@ -31,14 +32,17 @@ function Chat() {
         .string()
         .describe("The CSS background value. Prefer gradients."),
     }),
+    // @region[frontend-tool-handler]
     handler: async ({ background }: { background: string }) => {
       setBackground(background);
       return {
         status: "success",
         message: `Background changed to ${background}`,
       };
     },
+    // @endregion[frontend-tool-handler]
   });
+  // @endregion[frontend-tool-registration]
 
   useConfigureSuggestions({
     suggestions: [

showcase/integrations/claude-sdk-python/src/app/demos/headless-complete/page.tsx

@@ -51,6 +51,7 @@ export default function HeadlessCompleteDemo() {
 }
 
 function Chat() {
+  // @region[page-send-message]
   const threadId = useMemo(() => crypto.randomUUID(), []);
   const { agent } = useAgent({ agentId: AGENT_ID, threadId });
   const { copilotkit } = useCopilotKit();
@@ -101,6 +102,7 @@ function Chat() {
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [agent]);
+  // @endregion[page-send-message]
 
   return (
     <CopilotChatConfigurationProvider agentId={AGENT_ID} threadId={threadId}>

showcase/integrations/claude-sdk-python/src/app/demos/open-gen-ui-advanced/page.tsx

@@ -23,6 +23,10 @@ import { openGenUiSuggestions } from "./suggestions";
 
 export default function OpenGenUiAdvancedDemo() {
   return (
+    // @region[sandbox-function-registration]
+    // Pass the sandbox-function array on the `openGenerativeUI` provider prop.
+    // The built-in `OpenGenerativeUIActivityRenderer` wires these as callable
+    // remotes inside the agent-authored iframe.
     <CopilotKit
       runtimeUrl="/api/copilotkit-ogui"
       agent="open-gen-ui-advanced"
@@ -34,6 +38,7 @@ export default function OpenGenUiAdvancedDemo() {
         </div>
       </div>
     </CopilotKit>
+    // @endregion[sandbox-function-registration]
   );
 }
 

showcase/integrations/claude-sdk-python/src/app/demos/open-gen-ui-advanced/sandbox-functions.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 
+// @region[sandbox-function-registration]
 /**
  * Host-side functions that agent-authored, sandboxed UIs can invoke from
  * inside the iframe via `Websandbox.connection.remote.<name>(args)`.
@@ -54,3 +55,4 @@ export const openGenUiSandboxFunctions = [
     },
   },
 ];
+// @endregion[sandbox-function-registration]

showcase/integrations/claude-sdk-python/src/app/demos/open-gen-ui/page.tsx

@@ -87,6 +87,12 @@ const minimalSuggestions = [
 
 export default function OpenGenUiDemo() {
   return (
+    // @region[minimal-provider-setup]
+    // Minimal Open Generative UI frontend: the built-in activity renderer is
+    // registered by CopilotKitProvider, so a plain <CopilotChat /> is enough —
+    // no custom tool renderers, no activity-renderer registration.
+    // We DO pass `openGenerativeUI.designSkill` to swap in visualisation-tuned
+    // guidance in place of the default shadcn design skill.
     <CopilotKit
       runtimeUrl="/api/copilotkit-ogui"
       agent="open-gen-ui"
@@ -98,6 +104,7 @@ export default function OpenGenUiDemo() {
         </div>
       </div>
     </CopilotKit>
+    // @endregion[minimal-provider-setup]
   );
 }
 

showcase/integrations/claude-sdk-python/src/app/demos/readonly-state-agent-context/page.tsx

@@ -37,13 +37,16 @@ const ACTIVITIES = [
 ];
 
 function DemoContent() {
+  // @region[context-provider-sketch]
   const [userName, setUserName] = useState("Atai");
   const [userTimezone, setUserTimezone] = useState("America/Los_Angeles");
   const [recentActivity, setRecentActivity] = useState<string[]>([
     ACTIVITIES[0],
     ACTIVITIES[2],
   ]);
+  // @endregion[context-provider-sketch]
 
+  // @region[use-agent-context-call]
   useAgentContext({
     description: "The currently logged-in user's display name",
     value: userName,
@@ -56,6 +59,7 @@ function DemoContent() {
     description: "The user's recent activity in the app, newest first",
     value: recentActivity,
   });
+  // @endregion[use-agent-context-call]
 
   useConfigureSuggestions({
     suggestions: [