Cleanup the readmes

examples/tutorials/00_sync/000_hello_acp/README.md

@@ -1,7 +1,27 @@
 # [Sync] Hello ACP
 
-This is a simple AgentEx agent that just says hello and acknowledges the user's message to show which ACP methods need to be implemented for the sync ACP type.
+## What You'll Learn
 
-## Official Documentation
+The simplest agent type: synchronous request/response pattern with a single `@acp.on_message_send` handler. Best for stateless operations that complete immediately.
 
-[000 Hello ACP](https://dev.agentex.scale.com/docs/tutorials/sync/000_hello_acp)
+**When to use sync:** Quick responses, no long-running operations, no need for task management or durability.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/00_sync/000_hello_acp
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Code
+
+```python
+@acp.on_message_send
+async def handle_message_send(params: SendMessageParams):
+    return TextContent(
+        author="agent",
+        content=f"Echo: {params.content.content}"
+    )
+```
+
+That's it - one handler, immediate response. No task creation, no state management.

examples/tutorials/00_sync/010_multiturn/README.md

@@ -1,7 +1,38 @@
 # [Sync] Multiturn
 
-This tutorial demonstrates how to handle multiturn conversations in AgentEx agents using the Agent 2 Client Protocol (ACP).
+## What You'll Learn
 
-## Official Documentation
+Handle multi-turn conversations in synchronous agents by maintaining conversation history and context between messages.
 
-[010 Multiturn](https://dev.agentex.scale.com/docs/tutorials/sync/010_multiturn)
+**Use case:** Chatbots that need to reference previous messages within the same session.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/00_sync/010_multiturn
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Pattern
+
+Sync agents are stateless by default. To handle multi-turn conversations, you need to:
+1. Accept conversation history in the request
+2. Maintain context across messages
+3. Return responses that build on previous exchanges
+
+```python
+@acp.on_message_send
+async def handle_message_send(params: SendMessageParams):
+    # Accept conversation history from client
+    history = params.conversation_history
+
+    # Build context from history
+    context = build_context(history)
+
+    # Generate response considering full context
+    response = generate_response(params.content, context)
+
+    return TextContent(author="agent", content=response)
+```
+
+The handler accepts history, builds context, and returns responses that reference previous exchanges.

examples/tutorials/00_sync/020_streaming/README.md

@@ -1,9 +1,28 @@
 # [Sync] Streaming
 
-This tutorial demonstrates how to implement streaming responses in AgentEx agents using the Agent 2 Client Protocol (ACP).
+## What You'll Learn
 
-## Official Documentation
+Stream responses progressively using async generators instead of returning a single message. Enables showing partial results as they're generated.
 
-[020 Streaming](https://dev.agentex.scale.com/docs/tutorials/sync/020_streaming)
+**Use case:** LLM responses, large data processing, or any operation where you want to show progress.
 
+## Quick Start
 
+```bash
+cd examples/tutorials/00_sync/020_streaming
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Code
+
+```python
+@acp.on_message_send
+async def handle_message_send(params: SendMessageParams):
+    async def stream_response():
+        for chunk in response_chunks:
+            yield TaskMessageUpdate(content=TextContent(...))
+
+    return stream_response()
+```
+
+Return an async generator instead of a single response - each `yield` sends an update to the client.

examples/tutorials/10_agentic/00_base/000_hello_acp/README.md

@@ -1,7 +1,32 @@
 # [Agentic] Hello ACP
 
-This tutorial demonstrates how to implement the base agentic ACP type in AgentEx agents.
+## What You'll Learn
 
-## Official Documentation
+Agentic agents use three handlers for async task management: `on_task_create`, `on_task_event_send`, and `on_task_cancel`. Unlike sync agents, tasks persist and can receive multiple events over time.
 
-[000 Hello Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/hello_acp/) 
+**When to use agentic:** Long-running conversations, stateful operations, or when you need task lifecycle management.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/10_agentic/00_base/000_hello_acp
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Pattern
+
+```python
+@acp.on_task_create
+async def handle_task_create(params: CreateTaskParams):
+    # Initialize task state, send welcome message
+
+@acp.on_task_event_send
+async def handle_event_send(params: SendEventParams):
+    # Handle each message/event in the task
+
+@acp.on_task_cancel
+async def handle_task_cancel(params: CancelTaskParams):
+    # Cleanup when task is cancelled
+```
+
+Three handlers instead of one, giving you full control over task lifecycle. Tasks can receive multiple events and maintain state across them.

examples/tutorials/10_agentic/00_base/010_multiturn/README.md

@@ -1,7 +1,18 @@
 # [Agentic] Multiturn
 
-This tutorial demonstrates how to handle multiturn conversations in AgentEx agents using the agentic ACP type.
+## What You'll Learn
 
-## Official Documentation
+Handle multi-turn conversations in agentic agents with task-based state management. Each task maintains its own conversation history.
 
-[010 Multiturn Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/multiturn/)
+**Use case:** Conversational agents that need to remember context across multiple exchanges within a task.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/10_agentic/00_base/010_multiturn
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Pattern
+
+In sync agents, you manually pass conversation history. In agentic agents, the task itself maintains state across multiple `on_task_event_send` calls, making it easier to build stateful conversations.

examples/tutorials/10_agentic/00_base/020_streaming/README.md

@@ -1,7 +1,30 @@
 # [Agentic] Streaming
 
-This tutorial demonstrates how to implement streaming responses in AgentEx agents using the agentic ACP type.
+## What You'll Learn
 
-## Official Documentation
+Stream responses in agentic agents using `adk.messages.create()` to send progressive updates. More flexible than sync streaming since you can send multiple messages at any time.
 
-[020 Streaming Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/streaming/)
+**Use case:** Long-running operations where you want to show progress, or multi-step processes with intermediate results.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/10_agentic/00_base/020_streaming
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Pattern
+
+```python
+@acp.on_task_event_send
+async def handle_event_send(params: SendEventParams):
+    # Send first message
+    await adk.messages.create(task_id=task_id, content=...)
+
+    # Do work...
+
+    # Send second message
+    await adk.messages.create(task_id=task_id, content=...)
+```
+
+Unlike sync streaming (which uses async generators), agentic streaming uses explicit message creation calls, giving you more control over when and what to send.

examples/tutorials/10_agentic/00_base/030_tracing/README.md

@@ -1,7 +1,35 @@
 # [Agentic] Tracing
 
-This tutorial demonstrates how to implement hierarchical and custom tracing in AgentEx agents using the agentic ACP type.
+## What You'll Learn
 
-## Official Documentation
+Add observability to your agents with spans and traces using `adk.tracing.start_span()`. Track execution flow, measure performance, and debug complex agent behaviors.
 
-[030 Tracing Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/tracing/)
+**Use case:** Understanding agent behavior, debugging issues, monitoring performance in production.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/10_agentic/00_base/030_tracing
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Pattern
+
+```python
+# Start a span to track an operation
+span = await adk.tracing.start_span(
+    trace_id=task.id,
+    name="LLM Call",
+    input={"prompt": prompt}
+)
+
+# Do work...
+
+# End span with output
+await adk.tracing.end_span(
+    span_id=span.id,
+    output={"response": response}
+)
+```
+
+Spans create a hierarchical view of agent execution, making it easy to see which operations take time and where errors occur.

examples/tutorials/10_agentic/00_base/040_other_sdks/README.md

@@ -1,7 +1,27 @@
 # [Agentic] Other SDKs
 
-This tutorial demonstrates how to use other SDKs in AgentEx agents to show the flexibility that agents are just code.
+## What You'll Learn
 
-## Official Documentation
+Agents are just Python code - integrate any SDK you want (OpenAI, Anthropic, LangChain, LlamaIndex, custom libraries, etc.). AgentEx doesn't lock you into a specific framework.
 
-[040 Other SDKs Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/other_sdks/)
+**Use case:** Using your preferred LLM provider, existing agent frameworks, or custom tooling.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/10_agentic/00_base/040_other_sdks
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Insight
+
+AgentEx provides:
+- ACP protocol implementation (task management, message handling)
+- Deployment infrastructure
+- Monitoring and observability
+
+You provide:
+- Agent logic using whatever SDK/library you want
+- Tools and capabilities specific to your use case
+
+Mix and match OpenAI, Anthropic, LangChain, or roll your own - it's all just Python.

examples/tutorials/10_agentic/00_base/080_batch_events/README.md

@@ -1,7 +1,28 @@
 # [Agentic] Batch Events
 
-This tutorial demonstrates batch event processing and the limitations of the base agentic ACP protocol.
+## What You'll Learn
 
-## Official Documentation
+Demonstrates limitations of the base agentic protocol with concurrent event processing. When multiple events arrive rapidly, base agentic agents handle them sequentially, which can cause issues.
 
-[080 Batch Events Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/batch_events/)
+**Problem shown:** Race conditions and ordering issues when events arrive faster than the agent can process them.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/10_agentic/00_base/080_batch_events
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Why This Matters
+
+This tutorial shows **when you need Temporal**. If your agent needs to:
+- Handle events that might arrive out of order
+- Process multiple events in parallel safely
+- Maintain consistent state under concurrent load
+
+Then you should use Temporal workflows (see tutorials 10_agentic/10_temporal/) which provide:
+- Deterministic event ordering
+- Safe concurrent processing
+- Guaranteed state consistency
+
+This is the "breaking point" tutorial that motivates moving to Temporal for production agents.

examples/tutorials/10_agentic/10_temporal/000_hello_acp/README.md

@@ -1,7 +1,41 @@
-# [Agentic] Hello ACP with Temporal
+# [Temporal] Hello ACP
 
-This tutorial demonstrates how to implement the agentic ACP type with Temporal workflows in AgentEx agents.
+## What You'll Learn
 
-## Official Documentation
+Temporal workflows make agents durable - they survive restarts and can run indefinitely without consuming resources while idle. Instead of handlers, you define a workflow class with `@workflow.run` and `@workflow.signal` methods.
 
-[000 Hello Temporal Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/temporal/hello_acp/)
+**When to use Temporal:** Production agents that need guaranteed execution, long-running tasks (hours/days/weeks), or operations that must survive system failures.
+
+**Coming from base agentic?** See tutorial `080_batch_events` to understand when you need Temporal.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/10_agentic/10_temporal/000_hello_acp
+uv run agentex agents run --manifest manifest.yaml
+```
+
+**Monitor:** Check Temporal UI at http://localhost:8080 to see your durable workflow running.
+
+## Key Pattern
+
+```python
+@workflow.defn(name="my-workflow")
+class MyWorkflow(BaseWorkflow):
+    @workflow.run
+    async def on_task_create(self, params: CreateTaskParams):
+        # Wait indefinitely for events - workflow stays alive
+        await workflow.wait_condition(lambda: self._complete)
+
+    @workflow.signal(name=SignalName.RECEIVE_EVENT)
+    async def on_task_event_send(self, params: SendEventParams):
+        # Handle events as signals to the workflow
+```
+
+## Why This Matters
+
+**Without Temporal:** If your worker crashes, the agent loses all state and has to start over.
+
+**With Temporal:** The workflow resumes exactly where it left off. If it crashes mid-conversation, Temporal brings it back up with full context intact. Can run for years if needed, only consuming resources when actively processing.
+
+This is the foundation for production-ready agents that handle real-world reliability requirements.

examples/tutorials/10_agentic/10_temporal/010_agent_chat/README.md

@@ -1,7 +1,28 @@
-# [Agentic] Agent Chat with Temporal
+# [Temporal] Agent Chat
 
-This tutorial demonstrates how to implement streaming multiturn tool-enabled chat with tracing using Temporal workflows in AgentEx agents.
+## What You'll Learn
 
-## Official Documentation
+Combine streaming responses, multi-turn chat, tool calling, and tracing - all with Temporal's durability guarantees. This shows how to build a complete conversational agent that can survive failures.
 
-[010 Agent Chat Temporal Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/temporal/agent_chat/)
+**Use case:** Production chatbots with tools, long-running customer service conversations, or any agent that needs both capabilities and reliability.
+
+## Quick Start
+
+```bash
+cd examples/tutorials/10_agentic/10_temporal/010_agent_chat
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Pattern
+
+- **Streaming**: Progressive response generation with `adk.messages.create()`
+- **Multi-turn**: Conversation history maintained in durable workflow state
+- **Tools**: Agent can call functions to perform actions
+- **Tracing**: Full observability of tool calls and LLM interactions
+- **Durability**: All of the above survives worker restarts
+
+**Monitor:** Open Temporal UI at http://localhost:8080 to see the workflow and all tool call activities.
+
+## Key Insight
+
+In base agentic agents, all this state lives in memory and is lost on crash. With Temporal, the entire conversation - history, tool calls, intermediate state - is durably persisted. The agent can pick up a conversation that paused days ago as if no time passed.