docs(streaming): document the unified harness surface (#337)

Author: declan-scale

agentex/docs/docs/development_guides/streaming_patterns.md

@@ -266,10 +266,75 @@ async def streaming_with_override(params: SendMessageParams) -> AsyncGenerator[T
 - **Analysis**: Stream thinking process, then replace with final conclusion
 - **Tool integration**: Stream partial results, then override with tool-enhanced content
 
+## Unified Harness Surface (Framework Agents)
+
+!!! tip "Recommended for framework-based agents"
+    If your agent is built on an agent framework (LangGraph, Pydantic AI, OpenAI Agents SDK) or a coding CLI (Claude Code, Codex), the **unified harness surface** is the recommended way to stream. You write nothing ACP-specific: wrap the framework's native event stream in a `HarnessTurn` and hand it to a `UnifiedEmitter`. The emitter delivers the same canonical `StreamTaskMessage*` stream over either channel **and derives tracing spans from it automatically** — no separate tracing handler.
+
+The canonical event stream (`StreamTaskMessageStart/Delta/Full/Done`) is produced **once** by a per-framework *tap* (`convert_<framework>_to_agentex_events`). The emitter consumes it and handles delivery + tracing uniformly, so the same `turn` object works for Sync, Async, and Temporal — only the delivery call changes.
+
+Per-framework `HarnessTurn` wrappers ship today, all re-exported from `agentex.lib.adk` (requires `agentex-sdk >= 0.14.0`):
+
+| Framework | Turn class | Tap function |
+|---|---|---|
+| Pydantic AI | `PydanticAITurn` | `convert_pydantic_ai_to_agentex_events` |
+| LangGraph | `LangGraphTurn` | `convert_langgraph_to_agentex_events` |
+| OpenAI Agents | `OpenAITurn` | `convert_openai_to_agentex_events` |
+| Claude Code | `ClaudeCodeTurn` | `convert_claude_code_to_agentex_events` |
+| Codex | `CodexTurn` | `convert_codex_to_agentex_events` |
+
+```python
+import agentex.lib.adk as adk
+from agentex.lib.adk import UnifiedEmitter, LangGraphTurn  # swap for any Turn above
+
+# Sync ACP — yield over the HTTP response:
+@acp.on_message_send
+async def handle_message_send(params: SendMessageParams):
+    task_id = params.task.id
+    async with adk.tracing.span(
+        trace_id=task_id, task_id=task_id, name="message",
+        data={"__span_type__": "AGENT_WORKFLOW"},
+    ) as turn_span:
+        emitter = UnifiedEmitter(
+            task_id=task_id, trace_id=task_id,
+            parent_span_id=turn_span.id if turn_span else None,
+        )
+        turn = LangGraphTurn(graph.astream(...))      # feed the framework's native stream
+        async for event in emitter.yield_turn(turn):
+            yield event
+
+# Async ACP — push to Redis, get final text + usage back:
+@acp.on_task_event_send
+async def handle_event_send(params: SendEventParams):
+    task_id = params.task.id
+    async with adk.tracing.span(
+        trace_id=task_id, task_id=task_id, name="turn",
+        data={"__span_type__": "AGENT_WORKFLOW"},
+    ) as turn_span:
+        emitter = UnifiedEmitter(
+            task_id=task_id, trace_id=task_id,
+            parent_span_id=turn_span.id if turn_span else None,
+        )
+        turn = LangGraphTurn(graph.astream(...))
+        result = await emitter.auto_send_turn(turn)  # auto_send_turn replaces yield_turn
+        # result.final_text, result.usage
+```
+
+In a **Temporal** workflow the body is the same — construct the `UnifiedEmitter`, build the `turn`, and `await emitter.auto_send_turn(turn, created_at=workflow.now())` (pass `created_at` so events carry deterministic workflow time).
+
+**Why use it:**
+
+- **One mental model** for Sync, Async, and Temporal — `yield_turn` vs `auto_send_turn`, same `turn`.
+- **Tracing for free** — tool and reasoning spans are derived from the canonical stream (tool spans paired by `tool_call_id`) and fan out to every registered processor. No `create_<framework>_tracing_handler` to wire (those per-framework tracing handlers have been removed).
+- **Usage + final text** — `auto_send_turn` returns a `TurnResult` (`final_text`, `usage`) with normalized token/cost numbers.
+- **Streamed tool args survive async** — the emitter honors streamed `ToolRequestDelta`s on the Redis channel, not just sync.
+
+To add a framework that doesn't have a `HarnessTurn` yet, follow the `agentex-add-agent-framework` workflow: write a tap + a `<Fw>Turn`, export both from `agentex.lib.adk`. There is no per-framework async streamer or tracing handler to author.
+
 ## OpenAI Agents SDK Streaming
 
-!!! note "More Modular Approach"
-    The **OpenAI Agents SDK** provides a more modular alternative to `auto_send`. Instead of black-box logic, you write custom **providers** (for sync agents) and/or **hooks + providers** (for agentic ACPs) by inheriting classes and overriding methods. This Pythonic approach gives you full control over streaming behavior while working with **any LiteLLM model** (GPT-4, Claude, Gemini, etc.).
+!!! note "Lower-level alternative for fine-grained OpenAI SDK control"
+    The unified harness `OpenAITurn` above covers most OpenAI Agents SDK agents. The custom **provider** (sync) and **hooks + provider** (agentic) approach below is the lower-level path when you need to override streaming behavior directly — it works with **any LiteLLM model** (GPT-4, Claude, Gemini, etc.).
 
 The OpenAI Agents SDK supports [any LiteLLM model](https://openai.github.io/openai-agents-python/models/litellm/) and provides a cleaner architecture than `auto_send`:
 
@@ -516,6 +581,10 @@ graph TB
 
 !!! info "Choose the Right Pattern"
 
+    **Framework / coding-CLI agents (Recommended): Unified Harness Surface**
+    - Wrap the framework's stream in a `HarnessTurn` (`LangGraphTurn`, `PydanticAITurn`, `OpenAITurn`, `ClaudeCodeTurn`, `CodexTurn`) and deliver via `UnifiedEmitter`.
+    - `yield_turn` for Sync, `auto_send_turn` for Async/Temporal — same `turn`, tracing derived automatically.
+
     **Standard LiteLLM Providers (via ADK):**
     - **Sync ACP**: Manual delta accumulation, full control
     - **Async Auto Send**: Automatic but black-box (easiest, least flexible)

agentex/docs/docs/development_guides/tutorials.md

@@ -14,6 +14,14 @@ Basic agent patterns with simple request-response interactions.
 - **[Multiturn](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/00_sync/010_multiturn){target="_blank"}**: Conversation history and memory
 - **[Streaming](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/00_sync/020_streaming){target="_blank"}**: Real-time response streaming
 
+Framework starters (the `agentex init` Sync ACP options, each on the [unified harness](streaming_patterns.md#unified-harness-surface-framework-agents)):
+
+- **[LangGraph](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/00_sync/030_langgraph){target="_blank"}**
+- **[Pydantic AI](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/00_sync/040_pydantic_ai){target="_blank"}**
+- **[OpenAI Agents SDK](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/00_sync/050_openai_agents){target="_blank"}**
+- **[Claude Code](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/00_sync/060_claude_code){target="_blank"}**
+- **[Codex](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/00_sync/070_codex){target="_blank"}**
+
 ### Async ACP - Base (Learning & Development)
 
 Stateful workflows with full lifecycle control for development and advanced patterns.
@@ -26,6 +34,14 @@ Stateful workflows with full lifecycle control for development and advanced patt
 - **[Batch Events](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/00_base/080_batch_events){target="_blank"}**: Efficient multi-event handling
 - **[Multi-Agent Assembly Line](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/00_base/090_multi_agent_non_temporal){target="_blank"}**: Multi-agent coordination without Temporal
 
+Framework starters (the `agentex init` Async - ACP Only options, each on the [unified harness](streaming_patterns.md#unified-harness-surface-framework-agents)):
+
+- **[LangGraph](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/00_base/100_langgraph){target="_blank"}**
+- **[Pydantic AI](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/00_base/110_pydantic_ai){target="_blank"}**
+- **[OpenAI Agents SDK](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/00_base/120_openai_agents){target="_blank"}**
+- **[Claude Code](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/00_base/130_claude_code){target="_blank"}**
+- **[Codex](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/00_base/140_codex){target="_blank"}**
+
 ### Async ACP - Temporal (Production)
 
 Enterprise-ready patterns with durable execution for production deployments requiring reliability and fault tolerance.
@@ -40,6 +56,14 @@ Enterprise-ready patterns with durable execution for production deployments requ
     - [OpenAI Agents SDK: Tools](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools){target="_blank"}: Single and multi-activity tool patterns
     - [OpenAI Agents SDK: Human-in-the-Loop](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop){target="_blank"}: Human approval workflows
 
+Framework starters (the `agentex init` Async - Temporal options, each on the [unified harness](streaming_patterns.md#unified-harness-surface-framework-agents)):
+
+- **[Pydantic AI](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/10_temporal/110_pydantic_ai){target="_blank"}**
+- **[OpenAI Agents SDK](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/10_temporal/120_openai_agents){target="_blank"}**
+- **[LangGraph](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/10_temporal/130_langgraph){target="_blank"}**
+- **[Claude Code](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/10_temporal/140_claude_code){target="_blank"}**
+- **[Codex](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/tutorials/10_async/10_temporal/150_codex){target="_blank"}**
+
 ## Why Tutorials are on GitHub
 
 ✅ **Runnable code**: Clone the repository and run examples immediately

agentex/docs/docs/getting_started/choose_your_agent_type.md

@@ -21,6 +21,34 @@ Agentex supports three agent types with different execution models and capabilit
 
 ---
 
+## Pick a Framework (Harness)
+
+Choosing an agent type is only the **first** prompt in `agentex init`. After you pick Sync / Async-base / Temporal, the CLI asks which **agent framework** to scaffold. This is independent of the agent type — each type offers the same framework starters:
+
+| `agentex init` prompt | Framework options |
+|---|---|
+| **Sync ACP** | Basic · OpenAI Agents SDK (Recommended) · OpenAI Agents SDK + Local Sandbox · LangGraph · Pydantic AI · Claude Code · Codex |
+| **Async - ACP Only** | Basic · OpenAI Agents SDK · LangGraph · Pydantic AI · Claude Code · Codex |
+| **Async - Temporal** | Basic · OpenAI Agents SDK (Recommended) · Pydantic AI · LangGraph · Claude Code · Codex |
+
+!!! note "OpenAI Agents SDK + Local Sandbox"
+    The **Local Sandbox** variant is the OpenAI Agents SDK starter wired to run tools inside a local sandbox. It shares the same harness wiring and tutorial base as the plain [OpenAI Agents SDK](../development_guides/tutorials.md#sync-acp-simple-agents) starter — there is no separate tutorial for it.
+
+**What "Basic" gives you:** a blank handler that you fill in yourself (the examples in the [Project Structure Guide](project_structure.md) show this variant). Pick it when you're writing your agent loop by hand or calling an LLM through LiteLLM directly.
+
+**What a framework template gives you:** the same project layout **plus** the [unified harness](../development_guides/streaming_patterns.md#unified-harness-surface-framework-agents) wiring already in place — the framework's stream wrapped in a `HarnessTurn` and delivered by `UnifiedEmitter`, so streaming and tracing work out of the box. Some frameworks also add helper files (e.g. `agent.py` + `tools.py` for Pydantic AI / OpenAI Agents, `graph.py` + `tools.py` for LangGraph).
+
+How to choose:
+
+- **Writing the loop yourself / LiteLLM only** → Basic.
+- **Already standardized on a framework** → pick it directly (LangGraph, Pydantic AI, OpenAI Agents SDK).
+- **Wrapping a coding CLI** → Claude Code (spawns the `claude` CLI) or Codex (spawns the `codex` CLI) as a local subprocess, streamed through the harness.
+- **Want tools + good defaults and unsure** → OpenAI Agents SDK (the Recommended option for Sync and Temporal).
+
+To add a framework that isn't in the list, see the `agentex-add-agent-framework` workflow.
+
+---
+
 ## Upgrade Path
 
 | Current Type | When to Upgrade | Upgrade To | Key Benefit |

agentex/docs/docs/getting_started/project_structure.md

@@ -10,6 +10,11 @@ When you run `agentex init`, the CLI creates a complete agent project with every
 - **Async Base Agent** - Custom async implementations  
 - **Async Temporal Agent** - Complex, durable workflows
 
+`agentex init` then asks which **agent framework** to scaffold (Basic, OpenAI Agents SDK, LangGraph, Pydantic AI, Claude Code, or Codex) — see [Pick a Framework (Harness)](choose_your_agent_type.md#pick-a-framework-harness).
+
+!!! note "These examples are the **Basic** variant"
+    The `project/acp.py` shown for each agent type below is the **Basic** (blank-slate) template. If you pick a framework instead, the handler comes pre-wired with the [unified harness](../development_guides/streaming_patterns.md#unified-harness-surface-framework-agents) (the framework's stream wrapped in a `HarnessTurn`, delivered by `UnifiedEmitter`, with streaming + tracing handled), and some frameworks add helper files: `agent.py` + `tools.py` (Pydantic AI, OpenAI Agents) or `graph.py` + `tools.py` (LangGraph). For **Sync** and **Async-base** agents this wiring lives in `acp.py`; for **Temporal** agents it lives in `workflow.py` / `activities.py` instead. The rest of the layout is identical.
+
 This guide is organized by agent type. Jump to your section:
 
 - [Sync Agent Structure](#sync-agent-structure)