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

Catches up strands's shared-state-read-write and subagents demos (added in
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 (8 regions total)
- subagents: delegation-log-frontend on the log component;
  subagent-setup + supervisor-delegation-tools on src/agents/agent.py
  wrapping the _SUBAGENT_SYSTEM_PROMPTS dict and the @tool delegation
  wrappers (3 regions total — strands keeps everything in one god-file
  but both regions still have clean wrappable boundaries)

Author: samjulien

showcase/integrations/strands/src/agents/agent.py

@@ -379,6 +379,12 @@ async def notes_state_from_args(context):
 # entry the moment the tool returns.
 
 
+# @region[subagent-setup]
+# Each sub-agent is a single-shot OpenAI completion driven by its own
+# system prompt. They don't share memory or tools with the supervisor —
+# the supervisor only sees the returned text. We keep the prompts in a
+# dict (rather than spinning up a full secondary Strands ``Agent`` per
+# delegation) because the demo only needs one round-trip per call.
 _SUBAGENT_SYSTEM_PROMPTS: dict[str, str] = {
     "research_agent": (
         "You are a research sub-agent. Given a topic, produce a concise "
@@ -394,6 +400,7 @@ async def notes_state_from_args(context):
         "2-3 crisp, actionable critiques. No preamble."
     ),
 }
+# @endregion[subagent-setup]
 
 
 # Per-thread scratchpad of delegations. Keyed by ``thread_id``; the entry
@@ -521,6 +528,14 @@ class name. ``_make_subagent_state_from_result`` recognizes the
         return f"{_SUBAGENT_FAILURE_MARKER}{exc.__class__.__name__}"
 
 
+# @region[supervisor-delegation-tools]
+# Each @tool wraps a sub-agent invocation. The supervisor LLM "calls"
+# these tools to delegate work; ``_run_subagent`` synchronously runs the
+# matching sub-agent (a single-shot OpenAI completion), and the result
+# string is returned to the supervisor as the tool result. The matching
+# ``ToolBehavior(state_from_result=...)`` hook on each tool (registered
+# in ``build_showcase_agent``) appends a Delegation entry to shared
+# state so the UI's <DelegationLog/> reflects the call in real time.
 @tool
 def research_agent(task: str) -> str:
     """Delegate a research task to the research sub-agent.
@@ -557,6 +572,7 @@ def critique_agent(task: str) -> str:
         task: The draft to critique.
     """
     return _run_subagent("critique_agent", task)
+# @endregion[supervisor-delegation-tools]
 
 
 def _make_subagent_state_from_result(sub_agent_name: str):

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

@@ -18,6 +18,11 @@ export interface NotesCardProps {
  * 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
@@ -69,3 +74,4 @@ export function NotesCard({ notes, onClear }: NotesCardProps) {
     </div>
   );
 }
+// @endregion[notes-card-render]

showcase/integrations/strands/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 emitting a
   // StateSnapshotEvent through ag_ui_strands' ToolBehavior hook) this
@@ -46,6 +48,8 @@ function DemoContent() {
     agentId: "shared-state-read-write",
     updates: [UseAgentUpdate.OnStateChanged],
   });
+  // @endregion[use-agent-read]
+  // @endregion[use-agent]
 
   useConfigureSuggestions({
     suggestions: [
@@ -79,6 +83,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, `build_state_prompt` (the Strands
   // state_context_builder) reads this back out of state and prepends a
@@ -90,6 +96,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/strands/src/app/demos/shared-state-read-write/preferences-card.tsx

@@ -34,6 +34,12 @@ export interface PreferencesCardProps {
  * `input_data.state` and prepends it to the user message so the agent's
  * reply visibly adapts.
  */
+// @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 });
@@ -142,3 +148,4 @@ export function PreferencesCard({ value, onChange }: PreferencesCardProps) {
     </div>
   );
 }
+// @endregion[preferences-card-render]

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

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