Agentic Architect 101

Synaptic AI Consulting

Hands-On Mini-Project - Deliver Phase

Module 07: Hands-On Mini-Project - Deliver Phase

Estimated time: ~30 minutes
Outcome: Package, run, and document operations for your recruitment assistant via deploy.md
Framework version: AAMAD v0.7.5 (Tier-0 simplified Deliver — primary artifact is deploy.md)

Learning Objectives

By the end of this module, you will be able to:

Prerequisites

Deliver Phase Overview

The Deliver phase ensures your application can run reliably, be monitored, and evolve over time. As an Agentic Architect, you’ll wear your Technical Hat to orchestrate @devops.eng, ensuring:

Tier-0 key activities:

  1. deploy.md — Hosting, env matrix, access, rollback, how to run (consolidates deployment + runbook)
  2. Monitoring & logging — Basic observability (including optional CrewAI tracing)
  3. End-to-end execution — Run the application and capture results
  4. Lessons learned — Document insights from the project

Go deeper (optional): Full AAMAD also recommends @security.eng → security.md before Deliver, *document-user-guide → user-guide.md, and aamad validate --phase deliver. See CHECKLIST.md.

Step 1: DevOps Engineer - Create deploy.md and Configurations

The DevOps Engineer packages the validated MVP for delivery.

1.1 Create Deployment Branch

git checkout -b feature/deployment

1.2 Invoke DevOps Engineer Persona

Start a NEW chat session:

@devops.eng

I need you to prepare the recruitment assistant for delivery. Please:

1. Review the PRD: project-context/1.define/prd.md
2. Review the SAD: project-context/1.define/sad.md
3. Confirm QA status: project-context/2.build/qa.md
4. Note security.md status (present or accepted gap for this Tier-0 mini-project)
5. Align packaging with AAMAD_TARGET_RUNTIME=crewai
6. Create deployment configs as needed (Dockerfile, docker-compose.yml, main.py, requirements.txt)
7. Complete project-context/3.deliver/deploy.md including:
   - Release scope / version summary
   - Hosting approach (local and/or Docker)
   - Environment variable matrix (reference .env.example keys only — no secrets)
   - How to install, start, stop, and roll back
   - Access control notes (MVP scope)
   - Monitoring / logging overview
   - Troubleshooting
   - Sources, Assumptions, Open Questions, Audit
   (use *prepare-release, *define-deploy, *document-deploy as available)

1.3 Review deploy.md

Wearing your Technical Hat, review:

Iterate with @devops.eng if needed.

1.4 Implementation Options

Common Deployment Options for Mini-Project:

  1. Local Python Script (Simplest)
    • Create a main.py or run.py entry point
    • Add requirements.txt with all dependencies
    • Document how to run: python main.py
  2. Docker Container (Recommended for learning)
    • Create Dockerfile
    • Create docker-compose.yml (if needed)
    • Document: docker build -t recruitment-assistant . && docker run --env-file .env recruitment-assistant
  3. CLI Entry Point (Good for testing)
    • Create a command-line interface
    • Use click or argparse for CLI
    • Document usage examples in deploy.md

1.5 Validate and Commit

git add project-context/3.deliver/deploy.md Dockerfile docker-compose.yml requirements.txt main.py
git commit -m "feat: Add deploy.md and deployment configuration

- DevOps Engineer created deploy runbook
- Deployment configurations added
- Ready for local/Docker run"

git checkout main
git merge feature/deployment
git branch -d feature/deployment

Step 2: Add Monitoring, Logging, and CrewAI Tracing

Add basic observability. For Tier 0, document monitoring inside deploy.md (or a short subsection) rather than a separate monitoring-plan file.

2.1 Create Monitoring Branch

git checkout -b feature/monitoring

2.2 Invoke DevOps Engineer Persona

@devops.eng

I need you to add monitoring and logging to the recruitment assistant. Please:

1. Review: project-context/3.deliver/deploy.md
2. Add basic logging to the application:
   - Log application startup
   - Log agent execution (when Application Crew runs)
   - Log API requests/responses
   - Log errors and exceptions
3. Enable CrewAI tracing for the Application Crew (optional but recommended):
   - Document crewai login / tracing=True setup
   - Document how to view traces in the CrewAI dashboard
4. Update deploy.md with a Monitoring & Observability section covering:
   - What to monitor
   - Log levels and where logs are stored
   - CrewAI tracing setup and access
5. Implement logging in the application code

2.3 Example Logging Setup

import logging
from datetime import datetime

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('logs/app.log'),
        logging.StreamHandler()
    ]
)

logger = logging.getLogger(__name__)

# Use in application
logger.info("Application started")
logger.info("Researcher agent executing...")
logger.error("Error occurred: %s", error_message)

CrewAI provides built-in tracing for Application Crew observability.

2.4.1 Set Up CrewAI AOP Account

  1. Visit app.crewai.com and sign up for a free account
  2. Install tools: pip install "crewai[tools]"
  3. Authenticate: crewai login

2.4.2 Enable Tracing in Your Application Crew

from crewai import Agent, Crew, Process, Task

crew = Crew(
    agents=[researcher, evaluator, recommender],
    tasks=[research_task, evaluation_task, recommendation_task],
    process=Process.sequential,
    tracing=True,  # Enable built-in tracing
    verbose=True
)

result = crew.kickoff()

Or set in .env:

CREWAI_TRACING_ENABLED=true

2.4.3 View Traces

  1. Visit app.crewai.com → Traces
  2. Review agent decisions, task timeline, tool usage, LLM calls, and errors

Reference: CrewAI Tracing Documentation

2.5 Validate and Commit

git add project-context/3.deliver/deploy.md src/ logs/
git commit -m "feat: Add monitoring and logging

- Logging infrastructure added
- CrewAI tracing documented in deploy.md
- Observability section updated"

git checkout main
git merge feature/monitoring
git branch -d feature/monitoring

Step 3: End-to-End Execution

Run your application end-to-end and capture the results.

3.1 Prepare for Execution

# Install dependencies
pip install -r requirements.txt

# Verify .env file is configured
cat .env | grep OPENAI_API_KEY
cat .env | grep AAMAD_TARGET_RUNTIME

# Review deploy runbook
cat project-context/3.deliver/deploy.md

3.2 Run the Application

Follow deploy.md:

Option 1: Local Python Script

python main.py

Option 2: Docker

docker build -t recruitment-assistant .
docker run --env-file .env recruitment-assistant

Option 3: CLI Entry Point

python -m src.cli --job-description "Python Developer" --requirements "5 years experience"

3.3 Capture Execution Results

git checkout -b feature/execution-results

Create project-context/3.deliver/execution-results.md:

# Execution Results

## Test Run: [Date]

### Input
- Job Description: [Your test job description]
- Requirements: [Key requirements]

### Execution
- Start Time: [timestamp]
- End Time: [timestamp]
- Duration: [duration]

### Application Crew Execution
- Researcher Agent: [Status and findings]
- Evaluator Agent: [Status and findings]
- Recommender Agent: [Status and recommendations]

### Output
[Capture the actual output/recommendations]

### Logs / Traces
[Key log entries or CrewAI AOP trace link]

### Issues Encountered
[Any errors or unexpected behavior]

### Observations
[What worked well, what didn't]

git add project-context/3.deliver/execution-results.md
git commit -m "docs: Add execution results

- End-to-end test execution completed
- Application Crew executed successfully
- Results documented"

git checkout main
git merge feature/execution-results
git branch -d feature/execution-results

Optional quality gate:

aamad validate --phase deliver

Step 4: Document Lessons Learned

Reflect on the entire project and document insights.

4.1 Create Lessons Learned Document

git checkout -b feature/lessons-learned

Create LESSONS.md in your project root covering:

  1. Define Phase — What worked; what you’d change; how @product-mgr helped
  2. Build Phase — Multi-persona orchestration; canonical artifacts; challenges
  3. Deliver Phase — Deployment challenges; usefulness of deploy.md; observability
  4. AAMAD Framework — Most valuable features; gaps vs full CHECKLIST
  5. Agentic Architect Role — Balancing Tech / Experience / Business hats
git add LESSONS.md
git commit -m "docs: Add lessons learned

- Document insights from entire project
- Reflect on AAMAD framework experience
- Capture recommendations for future projects"

git checkout main
git merge feature/lessons-learned
git branch -d feature/lessons-learned

Step 5: Final Review and Documentation

5.1 Review All Deliver Phase Artifacts

5.2 Update Project README

Update your project README with:

5.3 Optional: User Guide

Go deeper: Ask @devops.eng to run *document-user-guide and produce project-context/3.deliver/user-guide.md from .cursor/templates/user-guide-template.md.

5.4 Final Commit

git add README.md
git commit -m "docs: Complete Deliver phase documentation

- deploy.md and execution results complete
- README updated with project status
- Project ready for demonstration"

Exercise Summary

Complete the Deliver phase by:

  1. ✅ @devops.eng: Create deploy.md and deployment configurations
  2. ✅ Add monitoring, logging, and optional CrewAI tracing
  3. ✅ Run application end-to-end and capture results
  4. ✅ Document lessons learned
  5. ✅ Update project documentation

Key Practices Applied:

Deliverables

By the end of this module, you should have:

  1. ✅ project-context/3.deliver/deploy.md — Deployment + operations runbook
  2. ✅ project-context/3.deliver/execution-results.md — Test execution results
  3. ✅ LESSONS.md — Lessons learned document
  4. ✅ Deployment configurations (Dockerfile, scripts, and/or main.py)
  5. ✅ Logging implemented in application
  6. ✅ CrewAI tracing enabled/configured (recommended)
  7. ✅ Application runs end-to-end successfully
  8. ✅ Updated README.md with project status
  9. ✅ All code and documentation committed and merged to main

Check Your Understanding

  1. Why is the Deliver phase important?
    • What happens if you skip deployment and operational documentation?
  2. What’s the purpose of deploy.md?
    • How does it enable others to operate your application?
  3. Why add monitoring and logging?
    • What problems does observability solve?
  4. How does the Technical Hat help in the Deliver phase?
    • What operational decisions do you make as an Agentic Architect?
  5. Why document lessons learned?
    • How does reflection improve future projects?

Troubleshooting

Issue: Application won’t start

Issue: Docker build fails

Issue: Logs not appearing

Issue: CrewAI traces not appearing in dashboard

Issue: Application Crew agents not executing

Issue: Can’t follow deploy.md

Best Practices Applied

  1. Deployment Automation: Configuration files enable repeatable deployments
  2. Observability: Logging and tracing provide visibility into application behavior
  3. Documentation: deploy.md enables operational independence
  4. Testing: End-to-end execution validates the system works
  5. Reflection: Lessons learned improve future work
  6. Version Control: All operational artifacts are versioned

Next Steps

Once the Deliver phase is complete:

  1. Review all artifacts - Ensure everything is documented
  2. Share your project - Show others what you built
  3. Apply learnings - Use insights in future projects
  4. Proceed to Module 08 - Reflect on value and next steps

Continue to Module 08: Value and Next Steps

Additional Resources