Skip to content

Commit 19c437b

Browse files
jasonyang101jasonyang101
committed
Add README
1 parent b980b45 commit 19c437b

File tree

1 file changed

+155
-0
lines changed

1 file changed

+155
-0
lines changed

‎examples/tutorials/README.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# AgentEx Tutorials
2+
3+
Progressive tutorials for learning AgentEx from basics to production-ready patterns.
4+
5+
## Prerequisites
6+
7+
**Before starting any tutorial:**
8+
1. Set up your development environment following the [main repo README](https://github.com/scaleapi/scale-agentex#setup)
9+
2. Start backend services from repository root:
10+
```bash
11+
cd /path/to/agentex-python
12+
make dev
13+
```
14+
3. Verify Temporal UI is accessible at http://localhost:8233
15+
16+
For troubleshooting, see the [AgentEx debugging guide](https://github.com/scaleapi/scale-agentex#troubleshooting).
17+
18+
## Learning Path
19+
20+
```mermaid
21+
graph TD
22+
A[👋 Start Here] --> B[00_sync/000_hello_acp]
23+
B --> C[00_sync/010_multiturn]
24+
C --> D[00_sync/020_streaming]
25+
26+
D --> E{Need Task<br/>Management?}
27+
E -->|Yes| F[10_agentic/00_base/<br/>000_hello_acp]
28+
E -->|No| G[Continue with<br/>sync patterns]
29+
30+
F --> H[00_base/010_multiturn]
31+
H --> I[00_base/020_streaming]
32+
I --> J[00_base/030_tracing]
33+
J --> K[00_base/040_other_sdks]
34+
K --> L[00_base/080_batch_events]
35+
36+
L --> M{Building for<br/>Production?}
37+
M -->|Yes| N[10_temporal/<br/>000_hello_acp]
38+
M -->|No| O[00_base/090_multi_agent]
39+
40+
N --> P[10_temporal/010_agent_chat]
41+
P --> Q[10_temporal/020_state_machine]
42+
Q --> R[10_temporal/030_custom_activities]
43+
R --> S[10_temporal/050_guardrails]
44+
45+
S --> T{Using<br/>OpenAI SDK?}
46+
T -->|Yes| U[10_temporal/060_openai_hello]
47+
U --> V[10_temporal/070_openai_tools]
48+
V --> W[10_temporal/080_openai_hitl]
49+
T -->|No| X[🎉 Production Ready!]
50+
W --> X
51+
52+
style A fill:#e1f5e1
53+
style X fill:#fff3cd
54+
style E fill:#e3f2fd
55+
style M fill:#e3f2fd
56+
style T fill:#e3f2fd
57+
```
58+
59+
## Tutorial Structure
60+
61+
### 00_sync/ - Synchronous Agents
62+
Simple request-response patterns without task management. Start here if you're new to AgentEx.
63+
64+
- **[000_hello_acp](00_sync/000_hello_acp/)** - Your first agent
65+
- **[010_multiturn](00_sync/010_multiturn/)** - Maintaining conversation context
66+
- **[020_streaming](00_sync/020_streaming/)** - Real-time response streaming
67+
68+
**When to use:** Simple chatbots, stateless Q&A, quick prototypes
69+
70+
---
71+
72+
### 10_agentic/ - Task-Based Agents
73+
74+
#### 00_base/ - Non-Temporal Patterns
75+
Task-based architecture without workflow orchestration. Adds task management on top of sync patterns.
76+
77+
- **[000_hello_acp](10_agentic/00_base/000_hello_acp/)** - Task-based hello world
78+
- **[010_multiturn](10_agentic/00_base/010_multiturn/)** - Multiturn with task management
79+
- **[020_streaming](10_agentic/00_base/020_streaming/)** - Streaming with tasks
80+
- **[030_tracing](10_agentic/00_base/030_tracing/)** - Observability with Scale Groundplane
81+
- **[040_other_sdks](10_agentic/00_base/040_other_sdks/)** - Integrating OpenAI, Anthropic, etc.
82+
- **[080_batch_events](10_agentic/00_base/080_batch_events/)** - Event batching (shows limitations → Temporal)
83+
- **[090_multi_agent_non_temporal](10_agentic/00_base/090_multi_agent_non_temporal/)** - Complex multi-agent coordination
84+
85+
**When to use:** Task tracking needed but workflows are simple, no durability requirements
86+
87+
---
88+
89+
#### 10_temporal/ - Production Workflows
90+
Durable, fault-tolerant agents with Temporal workflow orchestration.
91+
92+
**Core Patterns:**
93+
- **[000_hello_acp](10_agentic/10_temporal/000_hello_acp/)** - Temporal basics
94+
- **[010_agent_chat](10_agentic/10_temporal/010_agent_chat/)** - Stateful conversations
95+
- **[020_state_machine](10_agentic/10_temporal/020_state_machine/)** - Structured state management
96+
- **[030_custom_activities](10_agentic/10_temporal/030_custom_activities/)** - Custom Temporal activities
97+
- **[050_agent_chat_guardrails](10_agentic/10_temporal/050_agent_chat_guardrails/)** - Safety & validation
98+
99+
**OpenAI Agents SDK Series:**
100+
- **[060_openai_hello_world](10_agentic/10_temporal/060_open_ai_agents_sdk_hello_world/)** - Plugin-based agents
101+
- **[070_openai_tools](10_agentic/10_temporal/070_open_ai_agents_sdk_tools/)** - Tool integration patterns
102+
- **[080_openai_hitl](10_agentic/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/)** - Human oversight workflows
103+
104+
**When to use:** Production systems requiring durability, fault tolerance, long-running workflows, or complex state management
105+
106+
---
107+
108+
## Quick Start
109+
110+
```bash
111+
# 1. Start backend services (from repo root)
112+
make dev
113+
114+
# 2. Navigate to a tutorial
115+
cd examples/tutorials/00_sync/000_hello_acp
116+
117+
# 3. Run it
118+
uv run python hello_acp.py
119+
```
120+
121+
## Common Commands
122+
123+
```bash
124+
# Format tutorial code (always scope to specific files you're modifying)
125+
rye run format examples/tutorials/00_sync/000_hello_acp/
126+
127+
# Run all agentic tutorial tests
128+
cd examples/tutorials
129+
./run_all_agentic_tests.sh
130+
131+
# Run specific tutorial test
132+
cd examples/tutorials
133+
uv run pytest 00_sync/000_hello_acp/ -v
134+
135+
# Check Temporal UI (when running temporal tutorials)
136+
open http://localhost:8233
137+
```
138+
139+
## Tutorial Categories at a Glance
140+
141+
| Category | Tutorials | Focus | Use When |
142+
|----------|-----------|-------|----------|
143+
| **Sync** | 3 | Request-response basics | Learning fundamentals, simple chatbots |
144+
| **Agentic Base** | 7 | Task management without workflows | Need task tracking, simple coordination |
145+
| **Temporal** | 8 | Production-grade workflows | Need durability, fault tolerance, complex state |
146+
147+
## Getting Help
148+
149+
- **Each tutorial includes:** README explaining concepts, annotated source code, and tests
150+
- **Common issues?** See [AgentEx troubleshooting guide](https://github.com/scaleapi/scale-agentex#troubleshooting)
151+
- **Need more context?** Check the [main AgentEx documentation](https://github.com/scaleapi/scale-agentex)
152+
153+
---
154+
155+
**Ready to start?** → Begin with [00_sync/000_hello_acp](00_sync/000_hello_acp/)

0 commit comments

Comments
 (0)