docs(showcase/ag2): region markers for shared-state-read-write + subagents

Catches up ag2's shared-state-read-write and subagents demos (added in
PR CopilotKit#4359, post smalls batch 1) to parity with langgraph-python.

- shared-state-read-write: nested use-agent/use-agent-read and
  set-state/use-agent-write on page.tsx; notes-card-render and
  preferences-card-render on the card components (6 regions total)
- subagents: delegation-log-frontend on the log component;
  subagent-setup + supervisor-delegation-tools on src/agents/subagents.py
  wrapping AG2/AutoGen ConversableAgent definitions and the
  @tool-decorated supervisor delegation functions (3 regions total)

Author: samjulien

showcase/integrations/ag2/src/agents/subagents.py

@@ -61,6 +61,7 @@ class SubagentsSnapshot(BaseModel):
 # prompt. They don't share memory or tools with the supervisor — the
 # supervisor only sees what each sub-agent's final reply produces.
 
+# @region[subagent-setup]
 _SUB_LLM_CONFIG = LLMConfig({"model": "gpt-4o-mini", "stream": False})
 
 _research_agent = ConversableAgent(
@@ -102,6 +103,7 @@ class SubagentsSnapshot(BaseModel):
     human_input_mode="NEVER",
     max_consecutive_auto_reply=1,
 )
+# @endregion[subagent-setup]
 
 
 async def _invoke_sub_agent(sub_agent: ConversableAgent, task: str) -> str:
@@ -215,6 +217,12 @@ async def _run_delegation(
 # ---------------------------------------------------------------------------
 
 
+# @region[supervisor-delegation-tools]
+# Each @tool wraps a sub-agent invocation. The supervisor LLM "calls"
+# these tools to delegate work; each call asynchronously runs the
+# matching sub-agent, records the delegation into shared state via
+# ContextVariables, and returns a ReplyResult the supervisor reads as
+# its tool output on the next step.
 @tool()
 async def research_agent(
     context_variables: ContextVariables,
@@ -266,6 +274,7 @@ async def critique_agent(
     return await _run_delegation(
         context_variables, "critique_agent", _critique_agent, task
     )
+# @endregion[supervisor-delegation-tools]
 
 
 # ---------------------------------------------------------------------------

showcase/integrations/ag2/src/app/demos/shared-state-read-write/notes-card.tsx

@@ -16,6 +16,11 @@ export interface NotesCardProps {
  * triggers a re-render. The "Clear" button is a write-back (UI -> agent
  * state) to demonstrate both directions on the same field.
  */
+// @region[notes-card-render]
+// Read-side render: this card reflects the agent-authored `notes` slice
+// of shared state. The parent page passes `state.notes` in; we never
+// touch agent state ourselves — we just render it. The Clear button is
+// a small write-back, exposed as an `onClear` prop.
 export function NotesCard({ notes, onClear }: NotesCardProps) {
   return (
     <div
@@ -67,3 +72,4 @@ export function NotesCard({ notes, onClear }: NotesCardProps) {
     </div>
   );
 }
+// @endregion[notes-card-render]

showcase/integrations/ag2/src/app/demos/shared-state-read-write/page.tsx

@@ -37,6 +37,8 @@ export default function SharedStateReadWriteDemo() {
 }
 
 function DemoContent() {
+  // @region[use-agent]
+  // @region[use-agent-read]
   // Subscribe the component to agent state changes. Any time the agent
   // mutates its state (e.g. via its `set_notes` tool returning a
   // ReplyResult with updated ContextVariables) this hook fires, we
@@ -45,6 +47,8 @@ function DemoContent() {
     agentId: "shared-state-read-write",
     updates: [UseAgentUpdate.OnStateChanged],
   });
+  // @endregion[use-agent-read]
+  // @endregion[use-agent]
 
   useConfigureSuggestions({
     suggestions: [
@@ -78,6 +82,8 @@ function DemoContent() {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // @region[set-state]
+  // @region[use-agent-write]
   // WRITE: every edit in the sidebar goes straight into agent state. On
   // the agent's next turn, AG2 hydrates ContextVariables from this and
   // the agent's `get_current_preferences` tool reflects them straight
@@ -88,6 +94,8 @@ function DemoContent() {
       notes, // preserve what the agent has written
     } as RWAgentState);
   };
+  // @endregion[use-agent-write]
+  // @endregion[set-state]
 
   // WRITE: let the user clear the agent-authored notes from the UI.
   const handleClearNotes = () => {

showcase/integrations/ag2/src/app/demos/shared-state-read-write/preferences-card.tsx

@@ -33,6 +33,12 @@ export interface PreferencesCardProps {
  * agent calls its `get_current_preferences` tool to read those values out
  * of `ContextVariables` and tailors its reply accordingly.
  */
+// @region[preferences-card-render]
+// Write-side render: every edit here bubbles up through `onChange`, and
+// the parent pipes it straight into `agent.setState({ preferences: ... })`.
+// Nothing in this component knows about the agent directly — that's
+// intentional: the card is a plain controlled form, and the agent state
+// wiring lives one layer up.
 export function PreferencesCard({ value, onChange }: PreferencesCardProps) {
   const set = <K extends keyof Preferences>(key: K, v: Preferences[K]) =>
     onChange({ ...value, [key]: v });
@@ -143,3 +149,4 @@ export function PreferencesCard({ value, onChange }: PreferencesCardProps) {
     </div>
   );
 }
+// @endregion[preferences-card-render]

showcase/integrations/ag2/src/app/demos/subagents/delegation-log.tsx

@@ -51,6 +51,7 @@ const STATUS_BADGE: Record<Delegation["status"], string> = {
   failed: "text-[#D14343]",
 };
 
+// @region[delegation-log-frontend]
 /**
  * Live delegation log — renders the `delegations` slot of agent state.
  *
@@ -137,3 +138,4 @@ export function DelegationLog({ delegations, isRunning }: DelegationLogProps) {
     </div>
   );
 }
+// @endregion[delegation-log-frontend]