Merge pull request #156 from scaleapi/jason/document-examples

Cleanup the readmes

Author: jasonyang101

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

@@ -1,7 +1,43 @@
 # [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.
+The simplest agent type: synchronous request/response pattern with a single `@acp.on_message_send` handler. Best for stateless operations that complete immediately.
 
-## Official Documentation
+## What You'll Learn
+- Building a basic synchronous agent
+- The `@acp.on_message_send` handler pattern
+- When to use sync vs agentic agents
 
-[000 Hello ACP](https://dev.agentex.scale.com/docs/tutorials/sync/000_hello_acp)
+## 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
+
+```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.
+
+## 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,7 +1,54 @@
 # [Sync] Multiturn
 
-This tutorial demonstrates how to handle multiturn conversations in AgentEx agents using the Agent 2 Client Protocol (ACP).
+Handle multi-turn conversations in synchronous agents by manually maintaining conversation history and context between messages.
 
-## Official Documentation
+## What You'll Learn
+- How to handle conversation history in sync agents
+- Building context from previous messages
+- The limitations of stateless multiturn patterns
 
-[010 Multiturn](https://dev.agentex.scale.com/docs/tutorials/sync/010_multiturn)
+## 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
+
+```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.
+
+## 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,9 +1,45 @@
 # [Sync] Streaming
 
-This tutorial demonstrates how to implement streaming responses in AgentEx agents using the Agent 2 Client Protocol (ACP).
+Stream responses progressively using async generators instead of returning a single message. Enables showing partial results as they're generated.
 
-## Official Documentation
+## What You'll Learn
+- How to stream responses using async generators
+- The `yield` pattern for progressive updates
+- When streaming improves user experience
 
-[020 Streaming](https://dev.agentex.scale.com/docs/tutorials/sync/020_streaming)
+## 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
 
+```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.
+
+## 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,7 +1,49 @@
 # [Agentic] Hello ACP
 
-This tutorial demonstrates how to implement the base agentic ACP type in AgentEx agents.
+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.
 
-## Official Documentation
+## What You'll Learn
+- The three-handler pattern for agentic agents
+- How tasks differ from sync messages
+- When to use agentic vs sync agents
 
-[000 Hello Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/hello_acp/) 
+## 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
+
+```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.
+
+## 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,7 +1,61 @@
 # [Agentic] Multiturn
 
-This tutorial demonstrates how to handle multiturn conversations in AgentEx agents using the agentic ACP type.
+Handle multi-turn conversations in agentic agents with task-based state management. Each task maintains its own conversation history automatically.
 
-## Official Documentation
+## 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
 
-[010 Multiturn Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/multiturn/)
+## 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
+
+```bash
+cd examples/tutorials/10_agentic/00_base/010_multiturn
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Pattern
+
+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,7 +1,47 @@
 # [Agentic] Streaming
 
-This tutorial demonstrates how to implement streaming responses in AgentEx agents using the agentic ACP type.
+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.
 
-## Official Documentation
+## 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
 
-[020 Streaming Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/streaming/)
+## 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
+
+```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.
+
+## 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,7 +1,53 @@
 # [Agentic] Tracing
 
-This tutorial demonstrates how to implement hierarchical and custom tracing in AgentEx agents using the agentic ACP type.
+Add observability to your agents with spans and traces using `adk.tracing.start_span()`. Track execution flow, measure performance, and debug complex agent behaviors.
 
-## Official Documentation
+## 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
 
-[030 Tracing Base Agentic](https://dev.agentex.scale.com/docs/tutorials/agentic/base/tracing/)
+## 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
+
+```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.
+
+## 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