Document dynamic workflows

docs.json

@@ -251,6 +251,7 @@
                 "group": "Agent Features",
                 "pages": [
                   "sdk/guides/agent-acp",
+                  "sdk/guides/agent-dynamic-workflows",
                   "sdk/guides/agent-interactive-terminal",
                   "sdk/guides/agent-browser-use",
                   "sdk/guides/agent-custom",

sdk/guides/agent-dynamic-workflows.mdx

@@ -0,0 +1,53 @@
+---
+title: Dynamic Workflows
+description: Let an agent generate Python workflow code that coordinates sub-agents through the WorkflowToolSet.
+---
+
+import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx";
+
+> A ready-to-run example is available [here](#ready-to-run-example)!
+
+<Warning>
+Dynamic workflows are experimental. The workflow tool executes generated Python orchestration code after best-effort validation, so use it only for workflows you are comfortable approving as generated code execution.
+</Warning>
+
+## Overview
+
+Dynamic workflows let a parent agent write a small Python script that coordinates sub-agents through a constrained `wf` object. This is useful when the parent agent needs to keep intermediate results out of the main conversation while fanning out work across independent areas and then reducing the results into one answer.
+
+The workflow script defines one entry point:
+
+```python
+async def main(wf):
+    ...
+```
+
+Inside that function, the script can:
+
+- run one sub-agent with `await wf.run_agent(...)`
+- fan out across many inputs with `await wf.map_agents(...)`
+- synthesize intermediate outputs with `await wf.reduce_agent(...)`
+- flatten one level of nested values with `wf.flatten(...)`
+
+The implementation reuses the SDK's existing sub-agent task machinery, so workflow sub-agents inherit the current workspace and normal tool/security behavior.
+
+## When to use dynamic workflows
+
+Use dynamic workflows for tasks where the parent agent should create the orchestration plan at runtime, such as:
+
+- auditing test coverage across multiple project areas
+- reviewing documentation quality by directory
+- comparing several implementation strategies in parallel
+- collecting independent findings and reducing them into a final report
+
+For simple sequential delegation, use [Task Tool Set](/sdk/guides/task-tool-set). For parallel tool calls chosen directly by a model in one step, see [Parallel Tool Execution](/sdk/guides/parallel-tool-execution).
+
+## Ready-to-run example
+
+The example below asks the parent agent to write and run workflow code for a realistic test coverage audit. The parent agent owns the workflow tool; the generated workflow fans out `coverage_auditor` sub-agents by project area and then reduces their findings into a repo-wide report.
+
+```python icon="python" expandable examples/01_standalone_sdk/52_dynamic_workflow.py
+# This code block is synced from the Agent SDK repository.
+```
+
+<RunExampleCode />