Python AG-UI docs: add workflow usage, MCP Apps compatibility, and advanced features

[moonbox3]

Summary

The Python AG-UI integration docs on Microsoft Learn are missing coverage for several supported features. Currently only basic single-agent chat and backend tool rendering are documented.

Scope: Python only. This issue covers the Python AG-UI integration (agent-framework-ag-ui). .NET AG-UI docs are tracked separately.

Docs location: https://learn.microsoft.com/en-us/agent-framework/integrations/ag-ui/?pivots=programming-language-python
Source repo code files: agent-framework/integrations/ag-ui/

What exists today

Page	Content
Overview	AG-UI intro, feature list, architecture diagram
Getting Started	Single Agent server + AGUIChatClient client
Backend Tool Rendering	Single agent with @tool functions

What's missing (Python)

1. Workflow usage with AG-UI (high priority)

AgentFrameworkWorkflow and Workflow are fully supported but undocumented. Should cover:

• Wrapping a Workflow with AgentFrameworkWorkflow (direct instance and workflow_factory for thread-scoped)
• Using add_agent_framework_fastapi_endpoint() with workflows
• AG-UI events emitted by workflows: STEP_STARTED/STEP_FINISHED, ACTIVITY_SNAPSHOT, CUSTOM (request_info, status, workflow_output)
• Interrupt/resume flow for workflows (request_info → RUN_FINISHED with interrupts → resume payload)
• Reference: samples/05-end-to-end/ag_ui_workflow_handoff/ is a full working example

2. Human-in-the-loop / tool approval (high priority)

The approval workflow is implemented but undocumented. Should cover:

• Using @tool(approval_mode="always_require") with AG-UI
• How approval requests flow: TOOL_CALL_START/ARGS/END → confirm_changes tool call → RUN_FINISHED with interrupt containing function_approval_request
• How the client sends approval/rejection via resume.interrupts payload
• The server-side pending approval registry (security model)

3. MCP Apps compatibility (medium priority)

We validated that MAF's Python AG-UI endpoints work correctly with the AG-UI ecosystem's TypeScript MCPAppsMiddleware (@ag-ui/mcp-apps-middleware). Should document:

• Supported topology: Frontend → CopilotKit Runtime / Node.js proxy with MCPAppsMiddleware → MAF FastAPI AG-UI endpoint
• No Python-side changes needed — MCP Apps support lives in the TS middleware layer, consistent with all other AG-UI Python integrations (LangGraph, Pydantic AI, etc.)
• Explicit non-goals: no Python MCPAppsMiddleware, no FastAPI handling of iframe-proxied MCP requests, no Python-side ui/resourceUri discovery
• Reference: samples/05-end-to-end/ag_ui_workflow_handoff/proxy/ has a working validation proxy
• Confirmed with CopilotKit (Atai Barkai, Markus Ecker) that this is the correct approach

4. Shared state and predictive state updates (medium priority)

Both are implemented in the Python AG-UI package via AgentFrameworkAgent config but undocumented:

• state_schema parameter for bidirectional state sync
• predict_state_config for streaming tool arguments as optimistic StateDeltaEvent updates
• StateSnapshotEvent and StateDeltaEvent usage
• default_state parameter on add_agent_framework_fastapi_endpoint()

5. CopilotKit integration details (low priority)

The overview page briefly mentions CopilotKit but doesn't show how to connect a Python MAF backend to CopilotKit's React frontend. Should cover:

• Using HttpAgent in CopilotKit runtime to point at a MAF AG-UI endpoint
• How CopilotKit's frontend tools flow through as client tools
• Link to CopilotKit's own MAF integration docs

Suggested page structure

ag-ui/
├── index.md                    (exists)
├── getting-started.md          (exists)
├── backend-tool-rendering.md   (exists)
├── workflows.md                (NEW - #1)
├── human-in-the-loop.md        (NEW - #2)
├── mcp-apps.md                 (NEW - #3)
└── shared-state.md             (NEW - #4)

Reference material (Python)

• AG-UI package source: python/packages/ag-ui/
• Working workflow + HITL sample: python/samples/05-end-to-end/ag_ui_workflow_handoff/
• AG-UI example agents: python/packages/ag-ui/agent_framework_ag_ui_examples/
• Golden tests (show exact event sequences): python/packages/ag-ui/tests/ag_ui/golden/