Cleanup tutorials

Author: jasonyang101

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

@@ -1,10 +1,15 @@
 # [Sync] Hello ACP
 
-## What You'll Learn
-
 The simplest agent type: synchronous request/response pattern with a single `@acp.on_message_send` handler. Best for stateless operations that complete immediately.
 
-**When to use sync:** Quick responses, no long-running operations, no need for task management or durability.
+## What You'll Learn
+- Building a basic synchronous agent
+- The `@acp.on_message_send` handler pattern
+- When to use sync vs agentic agents
+
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
 
 ## Quick Start
 
@@ -25,3 +30,14 @@ async def handle_message_send(params: SendMessageParams):
 ```
 
 That's it - one handler, immediate response. No task creation, no state management.
+
+## When to Use
+- Simple chatbots with no memory requirements
+- Quick Q&A or information lookup agents
+- Prototyping and testing agent responses
+- Operations that complete in under a second
+
+## Why This Matters
+Sync agents are the simplest way to get started with AgentEx. They're perfect for learning the basics and building stateless agents. Once you need conversation memory or task tracking, you'll graduate to agentic agents.
+
+**Next:** [010_multiturn](../010_multiturn/) - Add conversation memory to your agent

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

@@ -1,10 +1,16 @@
 # [Sync] Multiturn
 
-## What You'll Learn
+Handle multi-turn conversations in synchronous agents by manually maintaining conversation history and context between messages.
 
-Handle multi-turn conversations in synchronous agents by maintaining conversation history and context between messages.
+## What You'll Learn
+- How to handle conversation history in sync agents
+- Building context from previous messages
+- The limitations of stateless multiturn patterns
 
-**Use case:** Chatbots that need to reference previous messages within the same session.
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of basic sync agents (see [000_hello_acp](../000_hello_acp/))
 
 ## Quick Start
 
@@ -36,3 +42,13 @@ async def handle_message_send(params: SendMessageParams):
 ```
 
 The handler accepts history, builds context, and returns responses that reference previous exchanges.
+
+## When to Use
+- Simple chatbots that need conversation memory
+- When client can maintain and send conversation history
+- Quick prototypes before building full agentic agents
+
+## Why This Matters
+While sync agents can handle conversations, you're responsible for managing state on the client side. This becomes complex quickly. For production conversational agents, consider agentic agents ([10_agentic/00_base/010_multiturn](../../10_agentic/00_base/010_multiturn/)) where the platform manages state automatically.
+
+**Next:** [020_streaming](../020_streaming/) - Stream responses in real-time

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

@@ -1,10 +1,16 @@
 # [Sync] Streaming
 
-## What You'll Learn
-
 Stream responses progressively using async generators instead of returning a single message. Enables showing partial results as they're generated.
 
-**Use case:** LLM responses, large data processing, or any operation where you want to show progress.
+## What You'll Learn
+- How to stream responses using async generators
+- The `yield` pattern for progressive updates
+- When streaming improves user experience
+
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of basic sync agents (see [000_hello_acp](../000_hello_acp/))
 
 ## Quick Start
 
@@ -26,3 +32,14 @@ async def handle_message_send(params: SendMessageParams):
 ```
 
 Return an async generator instead of a single response - each `yield` sends an update to the client.
+
+## When to Use
+- Streaming LLM responses (OpenAI, Anthropic, etc.)
+- Large data processing with progress updates
+- Any operation that takes >1 second to complete
+- Improving perceived responsiveness
+
+## Why This Matters
+Streaming dramatically improves user experience for longer operations. Instead of waiting 10 seconds for a complete response, users see results immediately as they're generated. This is essential for modern AI agents.
+
+**Next:** Ready for task management? → [10_agentic/00_base/000_hello_acp](../../10_agentic/00_base/000_hello_acp/)

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

@@ -1,10 +1,16 @@
 # [Agentic] Hello ACP
 
-## What You'll Learn
-
 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.
 
-**When to use agentic:** Long-running conversations, stateful operations, or when you need task lifecycle management.
+## What You'll Learn
+- The three-handler pattern for agentic agents
+- How tasks differ from sync messages
+- When to use agentic vs sync agents
+
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of sync agents (see [00_sync/000_hello_acp](../../../00_sync/000_hello_acp/))
 
 ## Quick Start
 
@@ -30,3 +36,14 @@ async def handle_task_cancel(params: CancelTaskParams):
 ```
 
 Three handlers instead of one, giving you full control over task lifecycle. Tasks can receive multiple events and maintain state across them.
+
+## When to Use
+- Conversational agents that need memory
+- Operations that require task tracking
+- Agents that need lifecycle management (initialization, cleanup)
+- Building towards production systems
+
+## Why This Matters
+The task-based model is the foundation of production agents. Unlike sync agents where each message is independent, agentic agents maintain persistent tasks that can receive multiple events, store state, and have full lifecycle management. This is the stepping stone to Temporal-based agents.
+
+**Next:** [010_multiturn](../010_multiturn/) - Add conversation memory

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

@@ -1,10 +1,16 @@
 # [Agentic] Multiturn
 
-## What You'll Learn
+Handle multi-turn conversations in agentic agents with task-based state management. Each task maintains its own conversation history automatically.
 
-Handle multi-turn conversations in agentic agents with task-based state management. Each task maintains its own conversation history.
+## What You'll Learn
+- How tasks maintain conversation state across multiple exchanges
+- Difference between sync and agentic multiturn patterns
+- Building stateful conversational agents with minimal code
 
-**Use case:** Conversational agents that need to remember context across multiple exchanges within a task.
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of basic agentic agents (see [000_hello_acp](../000_hello_acp/))
 
 ## Quick Start
 
@@ -15,4 +21,41 @@ 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.
+Unlike sync agents where you manually track conversation history, agentic agents automatically maintain state within each task:
+
+```python
+@app.on_task_event_send()
+async def on_task_event_send(event_send: TaskEventSendInput):
+    # The task's messages list automatically includes all previous exchanges
+    messages = event_send.task.messages
+
+    # No need to manually pass history - it's already there!
+    response = await openai_client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=messages
+    )
+
+    return {"content": response.choices[0].message.content}
+```
+
+## Try It
+
+1. Start the agent with the command above
+2. Open the web UI or use the notebook to create a task
+3. Send multiple messages in the same task:
+   - "What's 25 + 17?"
+   - "What was that number again?"
+   - "Multiply it by 2"
+4. Notice the agent remembers context from previous exchanges
+
+## When to Use
+- Conversational agents that need memory across exchanges
+- Chat interfaces where users ask follow-up questions
+- Agents that build context over time within a session
+
+## Why This Matters
+Task-based state management eliminates the complexity of manually tracking conversation history. The AgentEx platform handles state persistence automatically, making it easier to build stateful agents without custom session management code.
+
+**Comparison:** In the sync version ([00_sync/010_multiturn](../../../00_sync/010_multiturn/)), you manually manage conversation history. Here, the task object does it for you.
+
+**Next:** [020_streaming](../020_streaming/) - Add real-time streaming responses

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

@@ -1,10 +1,16 @@
 # [Agentic] Streaming
 
-## What You'll Learn
-
 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.
 
-**Use case:** Long-running operations where you want to show progress, or multi-step processes with intermediate results.
+## What You'll Learn
+- How to stream with explicit message creation
+- Difference between sync and agentic streaming patterns
+- When to send multiple messages vs single streamed response
+
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of agentic basics (see [000_hello_acp](../000_hello_acp/))
 
 ## Quick Start
 
@@ -28,3 +34,14 @@ async def handle_event_send(params: SendEventParams):
 ```
 
 Unlike sync streaming (which uses async generators), agentic streaming uses explicit message creation calls, giving you more control over when and what to send.
+
+## When to Use
+- Multi-step processes with intermediate results
+- Long-running operations with progress updates
+- Agents that need to send messages at arbitrary times
+- More complex streaming patterns than simple LLM responses
+
+## Why This Matters
+Agentic streaming is more powerful than sync streaming. You can send messages at any time, from anywhere in your code, and even from background tasks. This flexibility is essential for complex agents with multiple concurrent operations.
+
+**Next:** [030_tracing](../030_tracing/) - Add observability to your agents

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

@@ -1,10 +1,17 @@
 # [Agentic] Tracing
 
-## What You'll Learn
-
 Add observability to your agents with spans and traces using `adk.tracing.start_span()`. Track execution flow, measure performance, and debug complex agent behaviors.
 
-**Use case:** Understanding agent behavior, debugging issues, monitoring performance in production.
+## What You'll Learn
+- How to instrument agents with tracing
+- Creating hierarchical spans to track operations
+- Viewing traces in Scale Groundplane
+- Performance debugging with observability
+
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of agentic agents (see [000_hello_acp](../000_hello_acp/))
 
 ## Quick Start
 
@@ -33,3 +40,14 @@ await adk.tracing.end_span(
 ```
 
 Spans create a hierarchical view of agent execution, making it easy to see which operations take time and where errors occur.
+
+## When to Use
+- Debugging complex agent behaviors
+- Performance optimization and bottleneck identification
+- Production monitoring and observability
+- Understanding execution flow in multi-step agents
+
+## Why This Matters
+Without tracing, debugging agents is like flying blind. Tracing gives you visibility into what your agent is doing, how long operations take, and where failures occur. It's essential for production agents and invaluable during development.
+
+**Next:** [040_other_sdks](../040_other_sdks/) - Integrate any SDK or framework

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

@@ -1,10 +1,17 @@
 # [Agentic] Other SDKs
 
-## What You'll Learn
-
 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.
 
-**Use case:** Using your preferred LLM provider, existing agent frameworks, or custom tooling.
+## What You'll Learn
+- How to integrate OpenAI, Anthropic, or any SDK
+- What AgentEx provides vs what you bring
+- Framework-agnostic agent development
+- Building agents with your preferred tools
+
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of agentic agents (see [000_hello_acp](../000_hello_acp/))
 
 ## Quick Start
 
@@ -25,3 +32,14 @@ You provide:
 - Tools and capabilities specific to your use case
 
 Mix and match OpenAI, Anthropic, LangChain, or roll your own - it's all just Python.
+
+## When to Use
+- You have an existing agent codebase to migrate
+- Your team prefers specific SDKs or frameworks
+- You need features from multiple providers
+- You want full control over your agent logic
+
+## Why This Matters
+AgentEx is infrastructure, not a framework. We handle deployment, task management, and protocol implementation - you handle the agent logic with whatever tools you prefer. This keeps you flexible and avoids vendor lock-in.
+
+**Next:** [080_batch_events](../080_batch_events/) - See when you need Temporal

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

@@ -1,10 +1,17 @@
 # [Agentic] Batch Events
 
-## What You'll Learn
-
 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.
 
-**Problem shown:** Race conditions and ordering issues when events arrive faster than the agent can process them.
+## What You'll Learn
+- Limitations of non-Temporal agentic agents
+- Race conditions and ordering issues in concurrent scenarios
+- When you need workflow orchestration
+- Why this motivates Temporal adoption
+
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of agentic patterns (see previous tutorials)
 
 ## Quick Start
 
@@ -26,3 +33,14 @@ Then you should use Temporal workflows (see tutorials 10_agentic/10_temporal/) w
 - Guaranteed state consistency
 
 This is the "breaking point" tutorial that motivates moving to Temporal for production agents.
+
+## When to Use (This Pattern)
+This tutorial shows what NOT to use for production. Use base agentic agents only when:
+- Events are infrequent (< 1 per second)
+- Order doesn't matter
+- State consistency isn't critical
+
+## Why This Matters
+Every production agent eventually hits concurrency issues. This tutorial shows you those limits early, so you know when to graduate to Temporal. Better to learn this lesson in a tutorial than in production!
+
+**Next:** Ready for production? → [../10_temporal/000_hello_acp](../../10_temporal/000_hello_acp/) or explore [090_multi_agent_non_temporal](../090_multi_agent_non_temporal/) for complex non-Temporal coordination

examples/tutorials/10_agentic/00_base/090_multi_agent_non_temporal/README.md

@@ -45,9 +45,11 @@ The system uses a shared build configuration with type-safe interfaces:
 ## 🚀 Quick Start
 
 ### Prerequisites
-- Python 3.12+
-- uv package manager
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Python 3.12+ and uv package manager
 - OpenAI API key (set `OPENAI_API_KEY` or create `.env` file)
+- Understanding of agentic patterns (see previous tutorials)
 
 ### Running the System
 
@@ -195,3 +197,14 @@ This tutorial demonstrates:
 - **AgentEx CLI usage** for development and deployment
 - **Inter-agent communication patterns** with proper error handling
 - **Scalable agent architecture** with clear separation of concerns
+
+## When to Use
+- Complex workflows requiring multiple specialized agents
+- Content pipelines with review/approval steps
+- Systems where each stage needs different capabilities
+- When you want agent separation without Temporal (though Temporal is recommended for production)
+
+## Why This Matters
+This shows how far you can go with non-Temporal multi-agent systems. However, note the limitations: manual state management, potential race conditions, and no built-in durability. For production multi-agent systems, consider Temporal ([../10_temporal/](../../10_temporal/)) which provides workflow orchestration, durability, and state management out of the box.
+
+**Next:** Ready for production workflows? → [../../10_temporal/000_hello_acp](../../10_temporal/000_hello_acp/)