Progressive tutorials for learning AgentEx from basics to production-ready patterns.
Before starting any tutorial:
- Set up your development environment following the main repo README
- Start backend services from repository root:
cd /path/to/agentex-python make dev - Verify Temporal UI is accessible at http://localhost:8233
For troubleshooting, see the AgentEx debugging guide.
graph TD
A[👋 Start Here] --> B[00_sync/000_hello_acp]
B --> C[00_sync/010_multiturn]
C --> D[00_sync/020_streaming]
D --> E{Need Task<br/>Management?}
E -->|Yes| F[10_async/00_base/<br/>000_hello_acp]
E -->|No| G[Continue with<br/>sync patterns]
F --> H[00_base/010_multiturn]
H --> I[00_base/020_streaming]
I --> J[00_base/030_tracing]
J --> K[00_base/040_other_sdks]
K --> L[00_base/080_batch_events]
L --> M{Building for<br/>Production?}
M -->|Yes| N[10_temporal/<br/>000_hello_acp]
M -->|No| O[00_base/090_multi_agent]
N --> P[10_temporal/010_agent_chat]
P --> Q[10_temporal/020_state_machine]
Q --> R[10_temporal/030_custom_activities]
R --> S[10_temporal/050_guardrails]
S --> T{Using<br/>OpenAI SDK?}
T -->|Yes| U[10_temporal/060_openai_hello]
U --> V[10_temporal/070_openai_tools]
V --> W[10_temporal/080_openai_hitl]
T -->|No| X[🎉 Production Ready!]
W --> X
style A fill:#e1f5e1
style X fill:#fff3cd
style E fill:#e3f2fd
style M fill:#e3f2fd
style T fill:#e3f2fd
Simple request-response patterns without task management. Start here if you're new to AgentEx.
- 000_hello_acp - Your first agent
- 010_multiturn - Maintaining conversation context
- 020_streaming - Real-time response streaming
When to use: Simple chatbots, stateless Q&A, quick prototypes
Task-based architecture without workflow orchestration. Adds task management on top of sync patterns.
- 000_hello_acp - Task-based hello world
- 010_multiturn - Multiturn with task management
- 020_streaming - Streaming with tasks
- 030_tracing - Observability with Scale Groundplane
- 040_other_sdks - Integrating OpenAI, Anthropic, etc.
- 080_batch_events - Event batching (shows limitations → Temporal)
- 090_multi_agent_non_temporal - Complex multi-agent coordination
When to use: Task tracking needed but workflows are simple, no durability requirements
Durable, fault-tolerant agents with Temporal workflow orchestration.
Core Patterns:
- 000_hello_acp - Temporal basics
- 010_agent_chat - Stateful conversations
- 020_state_machine - Structured state management
- 030_custom_activities - Custom Temporal activities
- 050_agent_chat_guardrails - Safety & validation
OpenAI Agents SDK Series:
- 060_openai_hello_world - Plugin-based agents
- 070_openai_tools - Tool integration patterns
- 080_openai_hitl - Human oversight workflows
When to use: Production systems requiring durability, fault tolerance, long-running workflows, or complex state management
# 1. Start backend services (from repo root)
make dev
# 2. Navigate to a tutorial
cd examples/tutorials/00_sync/000_hello_acp
# 3. Run it
uv run python hello_acp.py# Format tutorial code (always scope to specific files you're modifying)
uv run ruff format examples/tutorials/00_sync/000_hello_acp/
# Run all async tutorial tests
cd examples/tutorials
./run_all_async_tests.sh
# Run specific tutorial test
cd examples/tutorials
uv run pytest 00_sync/000_hello_acp/ -v
# Check Temporal UI (when running temporal tutorials)
open http://localhost:8233| Category | Tutorials | Focus | Use When |
|---|---|---|---|
| Sync | 3 | Request-response basics | Learning fundamentals, simple chatbots |
| Async Base | 7 | Task management without workflows | Need task tracking, simple coordination |
| Temporal | 8 | Production-grade workflows | Need durability, fault tolerance, complex state |
- Each tutorial includes: README explaining concepts, annotated source code, and tests
- Common issues? See AgentEx troubleshooting guide
- Need more context? Check the main AgentEx documentation
Ready to start? → Begin with 00_sync/000_hello_acp