Skip to content

Commit 0e7f595

Browse files
Copilotdylan-mccarthy
Copilot
and
dylan-mccarthy
committed
E8-T3: Add quick start guide and non-interactive demo script, fix shellcheck warnings
Co-authored-by: dylan-mccarthy <[email protected]>
1 parent 34741ae commit 0e7f595

File tree

4 files changed

+322
-4
lines changed

4 files changed

+322
-4
lines changed

‎QUICKSTART.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Quick Start - Invoice Classifier Demo
2+
3+
Get the Business Process Agents platform running in under 5 minutes!
4+
5+
## Prerequisites
6+
7+
- Docker and Docker Compose
8+
- 4GB+ RAM available
9+
- Linux, macOS, or Windows (WSL2)
10+
11+
Install required tools:
12+
```bash
13+
# macOS
14+
brew install jq curl
15+
16+
# Ubuntu/Debian
17+
sudo apt-get install -y jq curl
18+
```
19+
20+
## 1-Minute Quick Start
21+
22+
```bash
23+
# Clone the repository
24+
git clone https://github.com/dylan-mccarthy/Scalable-Process-Agent-System.git
25+
cd Scalable-Process-Agent-System
26+
27+
# Run the interactive demo
28+
./demo-invoice-classifier.sh
29+
```
30+
31+
That's it! The demo will:
32+
1. ✅ Start all required services
33+
2. ✅ Deploy the Invoice Classifier agent
34+
3. ✅ Show you the complete workflow
35+
4. ✅ Demonstrate observability features
36+
37+
## What You'll See
38+
39+
The demo showcases invoice classification using AI:
40+
41+
```
42+
Invoice → Azure Service Bus → Node Runtime → GPT-4 Classification → API Delivery
43+
```
44+
45+
**Sample Invoice:**
46+
```json
47+
{
48+
"vendorName": "Office Depot",
49+
"invoiceNumber": "DEMO-001",
50+
"totalAmount": 542.75,
51+
"currency": "USD"
52+
}
53+
```
54+
55+
**Classification Result:**
56+
```json
57+
{
58+
"vendorCategory": "Office Supplies",
59+
"routingDestination": "Procurement Department",
60+
"confidence": 0.98
61+
}
62+
```
63+
64+
## Services Started
65+
66+
| Service | URL | Purpose |
67+
|---------|-----|---------|
68+
| Control Plane API | http://localhost:8080 | REST + gRPC API |
69+
| PostgreSQL | localhost:5432 | Persistent storage |
70+
| Redis | localhost:6379 | Leases & locks |
71+
| NATS | localhost:4222 | Event streaming |
72+
| Node Runtime | (internal) | Agent execution |
73+
74+
## Explore the API
75+
76+
After the demo starts, try these commands:
77+
78+
```bash
79+
# List agents
80+
curl http://localhost:8080/v1/agents | jq
81+
82+
# List nodes
83+
curl http://localhost:8080/v1/nodes | jq
84+
85+
# View agent details
86+
curl http://localhost:8080/v1/agents/invoice-classifier | jq
87+
```
88+
89+
## View Logs
90+
91+
```bash
92+
# All logs
93+
docker compose logs -f
94+
95+
# Control Plane only
96+
docker compose logs -f control-plane
97+
98+
# Node Runtime only
99+
docker compose logs -f node-runtime
100+
```
101+
102+
## Cleanup
103+
104+
```bash
105+
./demo-invoice-classifier.sh cleanup
106+
```
107+
108+
To remove all data:
109+
```bash
110+
docker compose down -v
111+
```
112+
113+
## Next Steps
114+
115+
1. **Read the full walkthrough**: [DEMO.md](DEMO.md)
116+
2. **Deploy to Kubernetes**: `./infra/scripts/setup-k3d.sh`
117+
3. **Run E2E tests**: `dotnet test tests/E2E.Tests/`
118+
4. **Configure Azure AI**: [docs/AZURE_AI_FOUNDRY_INTEGRATION.md](docs/AZURE_AI_FOUNDRY_INTEGRATION.md)
119+
120+
## Troubleshooting
121+
122+
**Services won't start?**
123+
- Check Docker is running: `docker ps`
124+
- Ensure ports are available: 5432, 6379, 4222, 8080
125+
- Check available RAM: Minimum 4GB required
126+
127+
**Control Plane not ready?**
128+
- Wait up to 60 seconds for first startup
129+
- Check logs: `docker compose logs control-plane`
130+
131+
**Need help?**
132+
- See full troubleshooting guide in [DEMO.md](DEMO.md)
133+
134+
## What's Running?
135+
136+
The platform demonstrates:
137+
- ✅ **Distributed Orchestration**: Control Plane schedules work to nodes
138+
- ✅ **Agent Execution**: Microsoft Agent Framework + GPT-4
139+
- ✅ **Service Integration**: Azure Service Bus + HTTP output
140+
- ✅ **Observability**: OpenTelemetry metrics, traces, and logs
141+
- ✅ **Resilience**: DLQ, retries, lease management
142+
143+
---
144+
145+
**Ready for more?** See the [full demo walkthrough](DEMO.md) for detailed explanations and advanced features.

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@ This interactive demo walks you through:
4545

4646
**See [DEMO.md](DEMO.md) for detailed walkthrough documentation.**
4747

48+
**For a faster start, see [QUICKSTART.md](QUICKSTART.md).**
49+
4850
### Option 1: Local Kubernetes with k3d (Recommended)
4951

5052
The fastest way to get a complete environment running locally:

‎demo-invoice-classifier-noninteractive.sh‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
#!/bin/bash
2+
3+
################################################################################
4+
# Invoice Classifier Demo - Non-Interactive Version
5+
#
6+
# This script runs the demo in non-interactive mode, suitable for:
7+
# - CI/CD pipelines
8+
# - Automated testing
9+
# - Quick validation
10+
#
11+
# Usage:
12+
# ./demo-invoice-classifier-noninteractive.sh
13+
#
14+
################################################################################
15+
16+
set -e
17+
18+
# Colors for output
19+
GREEN='\033[0;32m'
20+
BLUE='\033[0;34m'
21+
YELLOW='\033[1;33m'
22+
RED='\033[0;31m'
23+
NC='\033[0m'
24+
25+
# Configuration
26+
CONTROL_PLANE_URL="${CONTROL_PLANE_URL:-http://localhost:8080}"
27+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
28+
TIMEOUT=120
29+
30+
log_info() {
31+
echo -e "${BLUE}[INFO]${NC} $1"
32+
}
33+
34+
log_success() {
35+
echo -e "${GREEN}[SUCCESS]${NC} $1"
36+
}
37+
38+
log_error() {
39+
echo -e "${RED}[ERROR]${NC} $1"
40+
}
41+
42+
wait_for_service() {
43+
local url=$1
44+
local service_name=$2
45+
local max_attempts=60
46+
local attempt=1
47+
48+
log_info "Waiting for $service_name to be ready (timeout: ${max_attempts}s)..."
49+
50+
while [ $attempt -le $max_attempts ]; do
51+
if curl -s -f "$url" > /dev/null 2>&1; then
52+
log_success "$service_name is ready!"
53+
return 0
54+
fi
55+
sleep 1
56+
attempt=$((attempt + 1))
57+
done
58+
59+
log_error "$service_name failed to start after $max_attempts attempts"
60+
return 1
61+
}
62+
63+
# Check prerequisites
64+
log_info "Checking prerequisites..."
65+
for cmd in docker jq curl; do
66+
if ! command -v $cmd &> /dev/null; then
67+
log_error "Required command not found: $cmd"
68+
exit 1
69+
fi
70+
done
71+
log_success "Prerequisites OK"
72+
73+
# Start services
74+
log_info "Starting infrastructure services..."
75+
docker compose up -d postgres redis nats
76+
77+
log_info "Waiting for infrastructure to be healthy..."
78+
sleep 10
79+
80+
log_info "Starting Control Plane..."
81+
docker compose up -d control-plane
82+
83+
# Wait for Control Plane
84+
if ! wait_for_service "${CONTROL_PLANE_URL}/health" "Control Plane API"; then
85+
log_error "Control Plane failed to start"
86+
docker compose logs control-plane
87+
exit 1
88+
fi
89+
90+
log_info "Starting Node Runtime..."
91+
docker compose up -d node-runtime
92+
93+
sleep 5
94+
95+
# Seed agent
96+
log_info "Seeding Invoice Classifier agent..."
97+
if [ -f "${SCRIPT_DIR}/agents/seed-invoice-classifier.sh" ]; then
98+
cd "${SCRIPT_DIR}/agents"
99+
CONTROL_PLANE_URL="${CONTROL_PLANE_URL}" ./seed-invoice-classifier.sh > /dev/null 2>&1
100+
cd "${SCRIPT_DIR}"
101+
log_success "Agent seeded"
102+
else
103+
log_error "Seed script not found"
104+
exit 1
105+
fi
106+
107+
# Create deployment
108+
log_info "Creating deployment..."
109+
deployment_response=$(curl -s -X POST "${CONTROL_PLANE_URL}/v1/deployments" \
110+
-H "Content-Type: application/json" \
111+
-d '{
112+
"agentId": "invoice-classifier",
113+
"version": "1.0.0",
114+
"env": "demo",
115+
"target": {
116+
"replicas": 2,
117+
"placement": {}
118+
}
119+
}')
120+
121+
dep_id=$(echo "$deployment_response" | jq -r '.depId')
122+
if [ "$dep_id" == "null" ] || [ -z "$dep_id" ]; then
123+
log_error "Failed to create deployment"
124+
echo "$deployment_response"
125+
exit 1
126+
fi
127+
log_success "Deployment created: $dep_id"
128+
129+
# Verify nodes
130+
log_info "Checking node registration..."
131+
nodes=$(curl -s "${CONTROL_PLANE_URL}/v1/nodes")
132+
node_count=$(echo "$nodes" | jq '. | length')
133+
log_info "Registered nodes: $node_count"
134+
135+
if [ "$node_count" -eq 0 ]; then
136+
log_error "No nodes registered!"
137+
exit 1
138+
fi
139+
140+
# Verify agent
141+
log_info "Verifying agent deployment..."
142+
agent=$(curl -s "${CONTROL_PLANE_URL}/v1/agents/invoice-classifier")
143+
agent_name=$(echo "$agent" | jq -r '.name')
144+
145+
if [ "$agent_name" != "Invoice Classifier" ]; then
146+
log_error "Agent verification failed"
147+
exit 1
148+
fi
149+
log_success "Agent deployed: $agent_name"
150+
151+
# Success
152+
log_success "Demo environment is ready!"
153+
echo ""
154+
echo "Access points:"
155+
echo " • Control Plane API: ${CONTROL_PLANE_URL}"
156+
echo " • Health check: ${CONTROL_PLANE_URL}/health"
157+
echo ""
158+
echo "Test commands:"
159+
echo " curl ${CONTROL_PLANE_URL}/v1/agents | jq"
160+
echo " curl ${CONTROL_PLANE_URL}/v1/nodes | jq"
161+
echo " curl ${CONTROL_PLANE_URL}/v1/deployments | jq"
162+
echo ""
163+
echo "View logs:"
164+
echo " docker compose logs -f control-plane"
165+
echo " docker compose logs -f node-runtime"
166+
echo ""
167+
echo "Cleanup:"
168+
echo " docker compose down"

‎demo-invoice-classifier.sh‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -265,11 +265,14 @@ send_demo_invoices() {
265265

266266
for i in "${!invoices[@]}"; do
267267
local invoice="${invoices[$i]}"
268-
local vendor_name=$(echo "$invoice" | jq -r '.vendorName')
269-
local invoice_number=$(echo "$invoice" | jq -r '.invoiceNumber')
270-
local amount=$(echo "$invoice" | jq -r '.totalAmount')
268+
local vendor_name
269+
local invoice_number
270+
local amount
271+
vendor_name=$(echo "$invoice" | jq -r '.vendorName')
272+
invoice_number=$(echo "$invoice" | jq -r '.invoiceNumber')
273+
amount=$(echo "$invoice" | jq -r '.totalAmount')
271274

272-
echo -e " ${BOLD}$(($i + 1)). $vendor_name${NC}"
275+
echo -e " ${BOLD}$((i + 1)). $vendor_name${NC}"
273276
echo " Invoice: $invoice_number"
274277
echo " Amount: \$$amount USD"
275278
echo ""

0 commit comments

Comments
 (0)