Automoto — MSR Research Accelerator

Agentic UI Factory from MSR Research Accelerator — AI-powered event recommendation agent with multi-channel deployment support. Demonstrates production-ready agent patterns for Teams, Copilot, HTTP APIs, and CLI.

---

Codespaces First Run

When this repository opens in GitHub Codespaces, the devcontainer setup verifies gh and installs the local gh automoto extension.

After startup, run:

gh automoto setup

This launches an interactive project setup wizard and generates a Copilot-ready prompt brief.

---

🌟 Overview

Automoto is a comprehensive AI agent showcasing enterprise-ready patterns:

Core Features

• ✅ Declarative manifest: Sessions, weights, and feature flags in JSON
• ✅ Multi-surface deployment: CLI, HTTP API, Teams, Copilot Studio, and M365 Copilot
• ✅ Bot Framework integration: Full Teams/Outlook bot with adaptive cards
• ✅ Microsoft Graph integration: Live calendar events with MSAL auth
• ✅ Adaptive Cards: Interactive UI for rich experiences
• ✅ Profile persistence: Save/load user preferences
• ✅ Structured telemetry: Application Insights + JSONL logging
• ✅ Security hardening: Input validation, rate limiting, CORS
• ✅ Production infrastructure: Docker, Bicep, CI/CD pipelines

Deployment Modes

Mode	Use Case	Entry Point	Documentation
CLI	Local testing, scripts	agent.py	Quick Start
HTTP API	REST endpoints	agent.py serve	API Docs
Teams Bot	Microsoft Teams	bot_server.py	Teams Setup · MS Learn: Bot Framework
Copilot Studio Agent	Copilot Studio channels	apps/copilot-studio/src/manifest/agent-manifest.json	Copilot products cheat sheet · apps/copilot-studio/
M365 Copilot / Teams Plugin	Teams compose extension, M365 Copilot	copilot-plugin.json	Copilot products cheat sheet · Teams Setup
Docker	Containerized deployment	deploy/Dockerfile	Deployment Guide · MS Learn: Container Apps

---

How This Fits in MSR Research Accelerator

MSR Research Accelerator provides innovation kits designed to accelerate AI agent prototyping. Automoto serves as:

1. Foundational example: Minimal agent architecture (manifest + logic)
2. Starter for real integrations: Easily extend to Microsoft Graph, SharePoint, or Agent SDK hosting
3. Pattern library: Demonstrates scoring, conflict detection, adaptive cards, telemetry

For production-ready Graph/SharePoint integration, see innovation-kit-repository/event-agent/ which includes:

• Microsoft 365 Agents SDK hosting scaffold
• Graph Calendar fetching with MSAL auth
• SharePoint page publishing
• Pydantic configuration with feature flags
• Full setup guide in MVP_GUIDE.md

---

<EFBFBD> Quick Start

Choose your testing environment:

1️⃣ CLI Mode (30 seconds)

# Install dependencies
pip install -r requirements.txt

# Recommend sessions
python agent.py recommend --interests "agents, ai safety" --top 3

# Explain a session
python agent.py explain --session "Generative Agents in Production" --interests "agents, gen ai"

# Export itinerary
python agent.py export --interests "agents, privacy" --output my_itinerary.md

2️⃣ HTTP API Mode (1 minute)

# Start server
python agent.py serve --port 8010 --card

# Test endpoints
curl http://localhost:8010/health
curl "http://localhost:8010/recommend?interests=agents,ai+safety&top=3"
curl "http://localhost:8010/explain?session=Generative+Agents&interests=agents"

3️⃣ Teams Bot Mode (5 minutes)

# Start bot server
python bot_server.py

# Download Bot Framework Emulator v4.14.1+
# https://github.com/microsoft/BotFramework-Emulator/releases/latest

# Connect to: http://localhost:3978/api/messages
# Send: @bot recommend agents, machine learning

Complete guide: docs/TESTING_GUIDE.md

4️⃣ Docker Mode (2 minutes)

# Build and run
docker build -t automoto:latest -f deploy/Dockerfile .
docker run -p 8010:8010 automoto:latest

# Or use Docker Compose
cd deploy
docker compose up

5️⃣ Microsoft Foundry Mode (15 minutes)

# Deploy infrastructure with Foundry
az deployment group create \
  --resource-group automoto-rg \
  --template-file infra/main.bicep \
  --parameters deployFoundry=true

# Install Agent Framework SDK (--pre flag required)
pip install agent-framework-azure-ai --pre

# Configure environment
export FOUNDRY_ENABLED=true
export FOUNDRY_PROJECT_ENDPOINT="https://eastus.api.azureml.ms"

# Run with Agent Framework
python agent_framework_adapter.py

Complete guide: docs/foundry-deployment.md

Microsoft Learn:

• Azure AI Foundry Overview
• Agent Service
• Prompt Flow

---

📚 Documentation

Quick Start

• 🚀 docs/getting-started/ - Get started
• 🎯 docs/DECISION_GUIDE.md - Choose the right integration pattern & platform ⭐
• 🧭 docs/copilot-products.md - Copilot Studio vs M365 Copilot vs GitHub Copilot cheat sheet
• 🧪 docs/TESTING_GUIDE.md - Testing guide

Architecture

• ⭐ docs/UNIFIED_ADAPTER_ARCHITECTURE.md - Unified adapter pattern (Azure AI Foundry, Power Platform, Bot Framework)
• 🔧 docs/EXTENSIBILITY_GUIDE.md - Extending with Power Platform, Azure Functions, declarative agents

Integration & Deployment

• 🤖 docs/agents-sdk-setup.md - Teams/M365 Copilot integration · MS Learn
• 🏭 docs/foundry-deployment.md - Azure AI Foundry deployment · MS Learn
• 🚀 docs/deployment-guide.md - Production deployment · MS Learn

API & Testing

• 🔧 docs/api-guide.md - HTTP API reference
• 📝 docs/api-examples.md - API usage examples
• ✅ docs/TESTING_GUIDE.md - Comprehensive testing guide (190+ tests)
• 🐛 docs/troubleshooting.md - Troubleshooting & common issues

---

🧪 Multi-Channel Testing Environments

Environment 1: Local CLI

Purpose: Quick testing, scripting, debugging

# Test recommendation logic
python agent.py recommend --interests "agents" --top 3

# Test with profile persistence
python agent.py recommend --interests "agents, telemetry" --profile-save demo
python agent.py recommend --profile-load demo --top 5

Best for: Algorithm testing, data validation, automation

---

Environment 2: HTTP API Server

Purpose: REST API testing, integration testing

# Start server with adaptive cards
python agent.py serve --port 8010 --card

Test with curl:

# Health check
curl http://localhost:8010/health

# Recommendations
curl "http://localhost:8010/recommend?interests=agents,ai+safety&top=5"

# With adaptive cards
curl "http://localhost:8010/recommend?interests=agents&top=3&card=1"

# Explain session
curl "http://localhost:8010/explain?session=AI+Safety+Foundations&interests=ai+safety"

# Export itinerary
curl "http://localhost:8010/export?interests=agents,privacy&format=markdown"

Best for: API integration, performance testing, HTTP client development

---

Environment 3: Bot Framework Emulator

Purpose: Teams bot testing, conversation flow testing

Setup:

1. Start bot server: python bot_server.py
2. Download Bot Framework Emulator v4.14.1+
3. Open emulator, connect to http://localhost:3978/api/messages
4. Leave App ID and Password empty for local testing

Test commands:

recommend agents, machine learning --top 5
explain "Generative Agents in Production" --interests agents
export agents, ai safety --profile my_profile
help

Features to test:

• ✅ Command parsing
• ✅ Adaptive cards rendering
• ✅ Natural language queries
• ✅ Error handling
• ✅ Typing indicators
• ✅ Profile persistence

Best for: Bot UX testing, conversation design, Teams preparation

Complete guide: docs/TESTING_GUIDE.md

---

Environment 4: Microsoft Teams (Local Tunnel)

Purpose: Real Teams environment testing

Setup with ngrok:

# Start bot server
python bot_server.py

# In another terminal, start ngrok
ngrok http 3978

# Copy ngrok URL (e.g., https://abc-123-def.ngrok.io)
# Update bot endpoint in Azure Portal or Bot Framework registration
# Upload teams-app.json to Teams Developer Portal

Test in Teams:

@Automoto recommend agents, machine learning
@Automoto explain "Session Title" --interests agents
@Automoto export agents --profile tech_days
@Automoto help

Best for: End-to-end Teams testing, user acceptance testing

---

Environment 5: Docker Container

Purpose: Production-like environment, deployment validation

# Build image
docker build -t Automoto:test -f deploy/Dockerfile .

# Run with environment variables
docker run -p 8010:8010 \
  -e BOT_ID="your-bot-id" \
  -e BOT_PASSWORD="your-password" \
  Automoto:test

# Or use Docker Compose
cd deploy
docker compose up

Test:

curl http://localhost:8010/health
curl "http://localhost:8010/recommend?interests=agents&top=3"

Best for: Deployment validation, container testing, CI/CD pipeline testing

---

Environment 6: Copilot Studio + Custom Webchat

Purpose: Copilot Studio agent testing, token validation, and UI customization

Setup:

1. Go to Copilot Studio or use pac copilot create --manifest apps/copilot-studio/src/manifest/agent-manifest.json
2. Import/publish the Copilot Studio artifacts from apps/copilot-studio/src/manifest/ (agent-manifest.json, topics.json, api-plugin.json)
3. Validate topics and actions in the Copilot Studio test pane
4. For a custom surface, run npm run dev --workspace=apps/copilot-studio-webchat and set the token endpoint from Channels → Mobile App

copilot-plugin.json is a Teams compose extension / M365 Copilot plugin manifest. Do not import it into Copilot Studio.

Test scenarios:

• "Find sessions about agents and AI"
• "Explain why this session matches my interests"
• "Export my personalized agenda"
• Validate the apps/copilot-studio-webchat/ experience with the mobile token endpoint

Best for: Copilot Studio UX testing, token endpoint validation, adaptive card iteration, custom webchat prototyping

---

Environment 7: Azure Production

Purpose: Production deployment, monitoring

Deploy:

# Using Bicep templates
az deployment group create \
  --resource-group Automoto-prod-rg \
  --template-file infra/main.bicep \
  --parameters infra/prod.bicepparam

Monitor:

• Application Insights for telemetry
• Log Analytics for centralized logs
• Azure Monitor for alerts

Best for: Production validation, load testing, performance monitoring

Complete guide: docs/deployment-guide.md

---

Environment 8: Microsoft Foundry

Purpose: AI Hub orchestration, Prompt Flow evaluation, model management

Setup:

# Deploy Foundry infrastructure
az deployment group create \
  --resource-group Automoto-foundry-rg \
  --template-file infra/main.bicep \
  --parameters deployFoundry=true

# Install Agent Framework SDK (--pre flag required)
pip install agent-framework-azure-ai --pre

# Configure environment
export FOUNDRY_ENABLED=true
export FOUNDRY_PROJECT_ENDPOINT="https://eastus.api.azureml.ms"
export FOUNDRY_PROJECT_NAME="Automoto-prod-project"

Test:

from agent_framework_adapter import AutomotoAgentFramework as AutomotoAgentFramework
agent = AutomotoAgentFramework()
response = await agent.run("recommend sessions about AI agents")

Features:

• ✅ AI Hub & Project for resource management
• ✅ GPT-4o and GPT-3.5-turbo deployments
• ✅ Prompt Flow orchestration (4-node workflow)
• ✅ Evaluation framework (precision, recall, F1, relevance)
• ✅ Managed compute and auto-scaling
• ✅ Enterprise security (RBAC, Key Vault)

Best for: Production AI orchestration, model evaluation, multi-agent systems, prompt engineering

Complete guide: docs/foundry-deployment.md

---

⚖️ Choosing the Right Platform

Microsoft Foundry or Copilot Studio? Here's how to decide:

Decision Framework

┌─────────────────────────────────────────────────────────────┐
│                  WHO IS BUILDING?                            │
└─────────────────────────────────────────────────────────────┘
                           │
          ┌────────────────┴────────────────┐
          │                                 │
   ┌──────▼──────┐                   ┌─────▼─────┐
   │ Line-of-    │                   │ Software  │
   │ Business    │                   │ Developers│
   │ Users + IT  │                   │ with      │
   │ Admins      │                   │ DevOps    │
   └──────┬──────┘                   └─────┬─────┘
          │                                 │
   ┌──────▼──────────────┐          ┌──────▼──────────────┐
   │ COPILOT STUDIO      │          │ MICROSOFT FOUNDRY   │
   │                     │          │                     │
   │ ✅ Low-code UI      │          │ ✅ Full Python/C#   │
   │ ✅ Managed platform │          │ ✅ Custom code      │
   │ ✅ Quick iteration  │          │ ✅ DevOps pipelines │
   │ ✅ Built-in actions │          │ ✅ Own resources    │
   │ ✅ No infra mgmt    │          │ ✅ Deep integration │
   └─────────────────────┘          └─────────────────────┘

When to Use Copilot Studio

✅ Choose Copilot Studio when:

• Team composition: Line-of-business users, IT admins, professional makers
• Development style: Low-code, visual design, managed environment
• Speed: Need to move from experimentation to execution quickly
• Complexity: Moderate workflows with built-in connectors
• Governance: Want managed security, compliance out-of-the-box

Example scenarios:

• HR building an employee onboarding agent
• IT help desk creating a ticket routing bot
• Marketing automating customer engagement
• Rapid prototyping with business stakeholders

Automoto in Copilot Studio:

• Use apps/copilot-studio/src/manifest/agent-manifest.json together with topics.json and api-plugin.json
• Deploy via Copilot Studio or Power Platform CLI (pac copilot create, pac copilot publish)
• Use apps/copilot-studio-webchat/ for testing, adaptive card iteration, and custom UI
• Get the client token endpoint from Channels → Mobile App
• See docs/copilot-products.md before choosing between Copilot Studio, M365 Copilot, and GitHub Copilot

Learn more:

• Microsoft Copilot Studio documentation
• Create your first copilot
• Add custom actions

---

When to Use Microsoft Foundry

✅ Choose Microsoft Foundry when:

• Team composition: Software developers, ML engineers, DevOps teams
• Development style: Pro-code, Python/C#/.NET, custom frameworks
• Control: Need deep customization, custom models, fine-tuning
• Integration: Complex enterprise systems, custom APIs
• DevOps: CI/CD pipelines, infrastructure as code, version control

Example scenarios:

• Building multi-agent orchestration systems
• Custom model deployment and evaluation
• Complex RAG (Retrieval-Augmented Generation) pipelines
• Production ML workflows with advanced monitoring
• Integration with legacy enterprise systems

Automoto in Microsoft Foundry:

• Use agent_framework_adapter.py for Agent Framework
• Deploy with flow.dag.yaml for Prompt Flow orchestration
• Full guide: docs/foundry-deployment.md
• Bicep infrastructure: infra/main.bicep with deployFoundry=true

Learn more:

• Azure AI Foundry documentation
• Develop AI agents
• Prompt Flow development
• Deploy generative AI

---

Fusion Teams: Use Both

Many organizations need both platforms - this is expected and supported:

Collaboration patterns:

• Copilot Studio agents for business users
• Foundry agents for backend processing, ML models
• Communication: Multi-agent workflows using MCP, A2A, Activity Protocol

Microsoft Agent Pre-Purchase Plan (P3):

• Single pool of funds for both platforms
• Choose the right tool at build time, not purchase time
• Flexibility as team composition changes

Automoto supports both:

• Copilot Studio manifest assets plus apps/copilot-studio-webchat/ for maker-managed experiences
• Agent Framework for Foundry orchestration
• Shared core logic (core.py) works across platforms

---

Feature Parity Reference

Feature	Copilot Studio	Microsoft Foundry	Automoto Support
Multi-agent workflows	✅	✅	✅ Both
Tools/Plugins	✅ Built-in	✅ Custom	✅ Both
Orchestration	✅ Visual	✅ Code-first	✅ Both
Enterprise governance	✅ Managed	✅ Custom RBAC	✅ Both
Low-code design	✅ Yes	❌ Pro-code only	⚠️ Copilot only
Custom models	⚠️ Limited	✅ Full control	✅ Foundry
DevOps integration	⚠️ Basic	✅ Advanced	✅ Foundry
Infrastructure control	❌ Managed	✅ Full control	✅ Foundry

Decision Checklist

Choose Copilot Studio if you answer YES to 3+ questions:

• Do you have non-developer business users building agents?
• Do you prefer visual/low-code tools?
• Is speed to market more important than deep customization?
• Do you want Microsoft to manage infrastructure?
• Are built-in connectors sufficient for your needs?

Choose Microsoft Foundry if you answer YES to 3+ questions:

• Do you have professional software developers on the team?
• Do you need custom model deployment or fine-tuning?
• Do you require advanced DevOps (CI/CD, IaC, testing)?
• Do you need deep integration with custom enterprise systems?
• Do you want full control over infrastructure and resources?

Need help deciding? Contact: Mads Bolaris, Shawn Henry, Anjli Chaudhry

Official Resources:

• Microsoft Agent Service documentation
• Build your first agent
• Azure AI platform decision guide

---

🎯 API Overview

HTTP Endpoints

Endpoint	Method	Purpose	Example
/health	GET	Health check	curl http://localhost:8010/health
/recommend	GET	Get personalized recommendations	curl "http://localhost:8010/recommend?interests=agents&top=3"
/explain	GET	Understand why a session matches	curl "http://localhost:8010/explain?session=Title&interests=agents"
/export	GET	Export itinerary to Markdown	curl "http://localhost:8010/export?interests=agents&format=markdown"
/recommend-graph	GET	Calendar-based recommendations	curl "http://localhost:8010/recommend-graph?interests=agents&top=5"

Full documentation: docs/api-guide.md (100+ examples)

Bot Commands (Teams/Emulator)

Command	Format	Example
Recommend	@bot recommend <interests> --top <n>	@bot recommend agents, ai safety --top 5
Explain	@bot explain "<title>" --interests <list>	@bot explain "Session Title" --interests agents
Export	@bot export <interests> --profile <name>	@bot export agents --profile my_profile
Help	@bot help	@bot help

Full reference: TEAMS_QUICK_REFERENCE.md

---

🏗️ Architecture & Components

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                     User Interfaces                          │
│  Teams | Outlook | Copilot Studio | HTTP API | CLI          │
└─────────────────┬───────────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────────┐
│                  Integration Layer                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Bot Handler  │  │ SDK Adapter  │  │ HTTP Server  │      │
│  │ (Teams)      │  │ (Copilot)    │  │ (REST API)   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────┬───────────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────────┐
│                    Core Engine                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ recommend()  │  │ explain()    │  │ export()     │      │
│  │ scoring      │  │ matching     │  │ itinerary    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│                                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Graph API    │  │ Telemetry    │  │ Profiles     │      │
│  │ Integration  │  │ Logging      │  │ Storage      │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└───────────────────────────────────────────────────────────────┘

Key Components

Component	File	Purpose	Lines
Core Logic	core.py	Recommendation engine	~400
Agent CLI	agent.py	Command-line interface	~800
Bot Handler	bot_handler.py	Teams message processing	455
Bot Server	bot_server.py	aiohttp HTTP server	223
Unified Adapters	adapters/base_adapter.py	Base adapter framework	450
Foundry Adapter	adapters/foundry_adapter.py	Azure AI Foundry	150
Power Adapter	adapters/power_adapter.py	Power Platform	120
Bot Adapter	adapters/bot_adapter.py	Bot Framework	150
Graph Service	graph_service.py	Microsoft Graph API	~300
Telemetry	telemetry.py	Application Insights	~200
Settings	settings.py	Configuration management	~150

Architecture: Automoto uses a unified adapter pattern to integrate with Azure AI Foundry, Power Platform, and Bot Framework. See docs/UNIFIED_ADAPTER_ARCHITECTURE.md for details.

Feature Matrix

Feature	CLI	HTTP API	Bot Emulator	Teams	Foundry	Copilot	Production
Recommendations	✅	✅	✅	✅	✅	✅	✅
Explanations	✅	✅	✅	✅	✅	✅	✅
Export Itinerary	✅	✅	✅	✅	✅	✅	✅
Adaptive Cards	❌	✅	✅	✅	✅	✅	✅
Graph Integration	✅	✅	✅	✅	✅	✅	✅
Profile Persistence	✅	✅	✅	✅	✅	✅	✅
Natural Language	❌	❌	✅	✅	✅	✅	✅
Rate Limiting	❌	✅	✅	✅	✅	✅	✅
Telemetry	✅	✅	✅	✅	✅	✅	✅
Authentication	❌	❌	❌	✅	✅	✅	✅
Monitoring	❌	❌	❌	❌	✅	❌	✅

---

API Quick Start

Endpoint	Method	Purpose
/health	GET	Health check
/recommend	GET	Get personalized recommendations
/explain	GET	Understand why a session matches
/export	GET	Export itinerary to Markdown
/recommend-graph	GET	Calendar-based recommendations

Example: curl "http://localhost:8010/recommend?interests=agents&top=3"

Full documentation with 100+ code examples: docs/api-guide.md

---

Local Quick Start

1. Run Locally (No Setup)

cd event-agent-example

# Install dependencies
pip install -r requirements.txt

# Recommend sessions
python agent.py recommend --interests "agents, ai safety" --top 3

# Explain a session
python agent.py explain --session "Generative Agents in Production" --interests "agents, gen ai"

# Export itinerary
python agent.py export --interests "agents, privacy" --output my_itinerary.md

# Start HTTP server
python agent.py serve --port 8010 --card

Test endpoints:

curl http://localhost:8010/health
curl "http://localhost:8010/recommend?interests=agents,ai+safety&top=3&card=1"
curl "http://localhost:8010/explain?session=Generative+Agents+in+Production&interests=agents,gen+ai"

2. Profile Persistence

# Save interests for later
python agent.py recommend --interests "agents, telemetry" --profile-save demo

# Load saved profile
python agent.py recommend --profile-load demo --top 5

Profiles stored in ~/.event_agent_profiles.json.

3. Run Tests

python -m pytest Automoto/tests -q

All 147 tests should pass (126 original + 21 security tests).

---

Development Workflow

Quick Commands

One-command setup:

bash setup.sh

Make commands:

make help          # Show all available commands
make install       # Install dependencies
make dev           # Install dev dependencies + pre-commit hooks
make test          # Run tests with coverage
make lint          # Check code quality
make format        # Auto-format code
make run           # Start the server locally
make docker-run    # Run in Docker
make deploy-dev    # Deploy to Azure (dev environment)

See docs/getting-started/ for complete guide.

GitHub Actions CI/CD

Automated workflows run on every push and PR:

• Tests (test.yml): Pytest with coverage on PR/push
• Linting (lint.yml): Black, isort, pylint checks
• Security (security.yml): Weekly Bandit + Safety scans
• Deploy (deploy.yml): Auto-deploy to Azure on merge to main

Configuration: See .github/workflows/README.md

Pre-commit Hooks

Automatically run code quality checks before commits:

pre-commit install
pre-commit run --all-files

Checks: Black, isort, pylint, bandit, pytest

---

Docker & Azure Deployment

Microsoft Learn: Azure Container Apps · Deploy containers

Local Docker:

make docker-build
make docker-run
make docker-logs

Deploy to Azure:

make deploy-dev      # Development
make deploy-prod     # Production

Includes:

• Multi-stage Docker build (optimized size)
• Azure App Service with managed identity
• Key Vault for secrets
• Application Insights for monitoring
• Log Analytics for centralized logging

Infrastructure: infra/README.md

---

Setup Dev Environment in VS Code

Prerequisites

• Python 3.11+
• VS Code with Python extension

Steps

1. Clone the repo (if not already):

   git clone https://github.com/msr-central/automoto.git
   cd automoto
   

2. Open Automoto in VS Code:

   code Automoto
   

   Or open the workspace folder in VS Code and navigate to Automoto/.

3. Create a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

4. Install dev dependencies (optional, for testing):

   pip install pytest
   

   The agent itself has zero dependencies — runs with Python stdlib only.

5. Configure VS Code:

   • Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
   • Select Python: Select Interpreter
   • Choose .venv/bin/python

6. Run the agent:

   Open integrated terminal in VS Code (Ctrl+ /Cmd+ ) and:

   python agent.py recommend --interests "agents, ai safety" --top 3
   

7. Run tests (in VS Code terminal):

   python -m pytest tests -v
   

   Or use VS Code's Testing sidebar (flask icon) to discover and run tests interactively.

8. Debug:

   Set breakpoints in agent.py, then press F5 (Run > Start Debugging). VS Code will prompt to create a launch.json — select "Python File" for CLI debugging or "Python: Current File" for general use.

---

Extending with Agent SDK

To integrate with Microsoft 365 Agents SDK (Teams, M365 Copilot, or Copilot Studio hosting):

1. See the full Agent SDK starter in innovation-kit-repository/event-agent/starter-code/agents_sdk_integration/
2. Follow MVP_GUIDE.md for Graph authentication, SharePoint publish, and SDK hosting setup
3. Compare patterns: Automoto (Automoto/agent.py) shows minimal logic; Agent SDK starter adds authentication, caching, and enterprise features

Key Differences

Feature	Automoto (Automoto/)	Agent SDK Starter (innovation-kit-repository/event-agent/)
Auth	None (mock data)	MSAL (Graph + SharePoint)
Data Source	Static JSON or external file	Microsoft Graph Calendar
Publishing	Markdown export	SharePoint page creation
Hosting	CLI + HTTP server	Microsoft 365 Agents SDK (Teams/M365 Copilot/Copilot Studio)
Config	JSON manifest	Pydantic settings + .env
Dependencies	None	pydantic, msal, requests, botbuilder-core

When to use Automoto: Prototyping agent logic, testing scoring algorithms, local demos

When to use Agent SDK Starter: Production deployment, Graph integration, Teams/Copilot experiences

---

📁 Project Structure

event-agent-example/
├── 🎯 Core Engine
│   ├── agent.py                      # CLI interface + command handlers
│   ├── core.py                       # Core recommendation logic
│   ├── agent.json                    # Event sessions catalog + scoring config
│   ├── agent-declaration.json        # Agents SDK manifest
│   └── agent.schema.json             # JSON schema validation
│
├── 🔌 Unified Adapters (NEW)
│   ├── adapters/
│   │   ├── __init__.py               # Package initialization
│   │   ├── base_adapter.py           # Base adapter framework (450 lines)
│   │   ├── foundry_adapter.py        # Azure AI Foundry (150 lines)
│   │   ├── power_adapter.py          # Power Platform (120 lines)
│   │   ├── bot_adapter.py            # Bot Framework (150 lines)
│   │   ├── directline_bot.py         # Direct Line bridge
│   │   └── requirements-directline.txt
│   ├── agent_framework_adapter.py    # Backward compat wrapper
│   └── agents_sdk_adapter.py         # Legacy adapter (539 lines)
│
├── 🤖 Bot Framework Integration
│   ├── bot_handler.py                # Teams activity handler (455 lines)
│   ├── bot_server.py                 # aiohttp HTTP server (223 lines)
│   ├── teams-app.json                # Teams app manifest
│   └── copilot-plugin.json           # Teams compose extension / M365 Copilot plugin manifest
│
├── 🌐 Microsoft Graph Integration
│   ├── graph_service.py              # Calendar API client
│   ├── graph_auth.py                 # MSAL authentication
│   └── runner.py                     # Multi-mode runner
│
├── ⚙️ Configuration & Utilities
│   ├── settings.py                   # Pydantic settings + environment config
│   ├── telemetry.py                  # Application Insights integration
│   ├── logging_config.py             # Structured logging
│   └── errors.py                     # Custom exceptions
│
├── 🧪 Tests (190+ tests passing)
│   ├── test_unified_adapters.py      # Unified adapter tests (NEW)
│   ├── test_agents_sdk.py            # SDK adapter tests
│   ├── test_graph_service.py         # Graph API tests
│   ├── test_core_graph.py            # Core logic tests
│   ├── test_bot_handler.py           # Bot Framework tests
│   └── ... (20 test files)
│
├── 📚 Documentation
│   ├── README.md                     # This file
│   ├── docs/
│   │   ├── getting-started/             # Getting started guide
│   │   ├── UNIFIED_ADAPTER_ARCHITECTURE.md  # Unified adapters (NEW)
│   │   ├── EXTENSIBILITY_GUIDE.md    # Power Platform integration
│   │   ├── TESTING_GUIDE.md          # Comprehensive testing
│   │   ├── copilot-products.md       # Copilot Studio vs M365 vs GitHub cheat sheet
│   │   ├── agents-sdk-setup.md       # Teams/M365 Copilot integration
│   │   ├── foundry-deployment.md     # Azure AI Foundry deployment
│   │   ├── deployment-guide.md       # Production deployment
│   │   ├── api-guide.md              # HTTP API reference
│   │   ├── api-examples.md           # API usage examples
│   │   └── troubleshooting.md        # Common issues
│
├── 🏗️ Infrastructure
│   ├── infra/
│   │   ├── main.bicep                # Azure resources (App Service, Key Vault, etc.)
│   │   ├── dev.bicepparam            # Development environment
│   │   └── prod.bicepparam           # Production environment
│   ├── deploy/
│   │   ├── Dockerfile                # Multi-stage build
│   │   ├── docker-compose.yml        # Local dev containers
│   │   └── nginx.conf                # Reverse proxy
│   └── .devcontainer/
│       └── devcontainer.json         # VS Code dev containers
│
├── 🔄 CI/CD & Automation
│   ├── .github/workflows/
│   │   ├── test.yml                  # Pytest on every PR
│   │   ├── lint.yml                  # Code quality checks
│   │   ├── security.yml              # Security scans
│   │   └── deploy.yml                # Azure deployment
│   ├── Makefile                      # Development commands
│   ├── setup.sh                      # One-command setup
│   └── .pre-commit-config.yaml       # Git hooks
│
├── 📦 Dependencies
│   ├── requirements.txt              # Production dependencies
│   ├── requirements-dev.txt          # Development dependencies
│   └── pyproject.toml                # Project metadata
│
└── 📊 Data & Assets
    ├── assets/
    │   ├── sample_itinerary.md       # Sample export output
    │   └── sessions_external.json    # External event data
    └── exports/                      # Generated itineraries
└── README.md                # This file

# Requires: MICROSOFT_APP_ID, MICROSOFT_APP_PASSWORD; optional AGENT_API_BASE
Automoto-runner --mode directline-adapter --port 3979

# Optional interests; add --publish to push pages
Automoto-runner --mode sharepoint-agent --interests "AI;agents" --max-sessions 3 --publish

Mode boundaries:

• MCP/tools only in custom-chat
• Graph/SharePoint integrations only in m365-agent / sharepoint-agent

Deployment playbooks:

• m365-agent: Azure App Service/Container Apps, Bot Framework channel
• sharepoint-agent: Azure Function/Container job
• custom-chat: Containerized web service + optional MCP servers

Config via Environment

You can set RUN_MODE and related variables in .env and run the runner without --mode:

cd Automoto
cp .env.example .env
# Edit .env, then export for the shell
export $(grep -v '^#' .env | xargs)

# RUN_MODE controls the behavior; falls back to CLI --mode if provided
Automoto-runner  # uses RUN_MODE

.env.example keys:

• RUN_MODE: custom-chat | m365-agent | sharepoint-agent
• PORT: Port for server modes (custom-chat, m365-agent)
• INCLUDE_CARD: true|false Adaptive Card in responses (custom-chat)
• GRAPH_TENANT_ID, GRAPH_CLIENT_ID, GRAPH_CLIENT_SECRET: Required for m365-agent; required for sharepoint-agent when publishing
• INTERESTS, MAX_SESSIONS, PUBLISH: Defaults for sharepoint-agent

Observability

• custom-chat: JSONL telemetry via telemetry.jsonl, health check at /health
• m365-agent: Integrate Azure Application Insights in the SDK host; expose liveness/readiness on the hosting platform
• sharepoint-agent: Log publish actions to JSONL and consider Azure Function logs or Container logs; add a simple CLI exit code for automation

MCP/Tooling Separation

• MCP servers and tooling are intended for custom-chat mode only.
• Avoid enabling MCP in m365-agent and sharepoint-agent paths unless a specific enterprise need is identified.
• Keep boundaries clear: SDK-hosted experiences should rely on Graph/SharePoint integrations and platform observability.

Deployment Playbooks

• m365-agent (Teams/M365 Copilot/Copilot Studio host):

  • Package the SDK host as a container and deploy to Azure App Service or Azure Container Apps.
  • Configure Bot Framework channel and required Graph credentials via app settings.
  • Add Application Insights for tracing and dashboards.

• sharepoint-agent (publisher service):

  • Implement as an Azure Function (timer/HTTP) or a scheduled container job.
  • Provide Graph credentials via Key Vault/App Settings; log publish results to JSONL and platform logs.
  • Keep no-chat boundary: this service publishes itineraries only.

• custom-chat (local/minimal web):

  • Containerize the HTTP server for portability; optionally run MCP servers alongside.
  • Expose /health and write local JSONL telemetry; consider lightweight reverse proxy for production demos.

Minimize Open Ports

To reduce security review scope, prefer a single externally exposed port:

• Use NGINX reverse proxy to expose only 8010 and proxy to internal services.
• Bind internal services to 127.0.0.1 and non-exposed ports (8011 for agent, 5174 for frontend when needed).

Quick container example (exposes only 8010):

cd Automoto/deploy
docker build -t Automoto-proxy .
docker run --rm -p 8010:8010 Automoto-proxy

Or use Docker Compose:

cd Automoto/deploy
docker compose up -d

This runs agent.py serve on 8011 internally and fronts it with NGINX at 8010. The optional frontend can be proxied under /app without opening 5174 publicly.

Devcontainer now forwards only 8010, consolidating all services behind the NGINX proxy.

Direct Line / Web Chat (Adaptive Cards)

Use the Bot Framework adapter shim in Automoto/adapters/directline_bot.py:

cd Automoto
python -m pip install -r adapters/requirements-directline.txt
MICROSOFT_APP_ID="<bot app id>" \
MICROSOFT_APP_PASSWORD="<bot app password>" \
AGENT_API_BASE="http://localhost:8010" \
python -m Automoto.adapters.directline_bot --port 3979

• Exposes /api/messages for Direct Line / Bot Framework Web Chat.
• Forwards user text to the Automoto /recommend endpoint and returns an Adaptive Card attachment.
• Deploy this container to Azure App Service/Container Apps, enable the Direct Line channel, and point Web Chat to the Direct Line token.

Feature Flags

Adjust behavior in agent.json > features:

• telemetry.enabled: Log actions to telemetry.jsonl
• export.enabled: Save markdown to exports/ directory
• externalSessions.enabled: Override sessions with sessions_external.json

---

Next Steps

1. Customize sessions: Edit agent.json to add your event data
2. Adjust scoring weights: Tweak weights (interest, popularity, diversity)
3. Connect real data: Enable externalSessions and provide JSON feed
4. Add authentication: See Agent SDK starter for Graph/MSAL patterns
5. Deploy as service: Use systemd or containerize (see docs/deployment-guide.md)
6. Integrate with Teams: Follow docs/agents-sdk-setup.md

---

Resources & Dependencies

Core Dependencies:

• Bot Framework SDK - Teams/Outlook bot integration
• Microsoft Graph - Calendar and M365 data access
• Application Insights - Telemetry and monitoring
• Azure Bicep - Infrastructure as Code
• pytest - Testing framework
• VS Code - Python development environment

---

📚 Additional Resources

Automoto Documentation

Getting Started:

• docs/getting-started/ - Getting started guide
• docs/TESTING_GUIDE.md - Testing guide

Architecture & Integration:

• docs/UNIFIED_ADAPTER_ARCHITECTURE.md ⭐ - Unified adapter pattern (Azure AI Foundry, Power Platform, Bot Framework)
• docs/EXTENSIBILITY_GUIDE.md - Power Platform, Azure Functions, declarative agents
• docs/agents-sdk-setup.md - Teams/M365 Copilot integration
• docs/foundry-deployment.md - Azure AI Foundry deployment
• docs/deployment-guide.md - Production deployment

Testing & Quality:

• docs/TESTING_GUIDE.md - Comprehensive testing guide (20 test files, 190+ tests)
• pytest.ini - Test configuration

Complete Documentation: docs/ - Full documentation library

Microsoft Learn Resources

AI & Agents:

• Azure AI Services overview
• Build AI agents
• Azure OpenAI Service
• Responsible AI principles

Bot Framework & Teams:

• Bot Framework documentation
• Teams bot development
• Teams Platform overview
• Teams JavaScript SDK
• Adaptive Cards
• Bot Framework SDK (Python)

Microsoft Graph & SharePoint:

• Microsoft Graph overview
• Graph Python SDK
• Calendar API reference
• SharePoint REST API
• SharePoint Framework (SPFx)
• Files & Lists via Graph
• Authentication with MSAL

Office Add-ins & Extensibility:

• Office Add-ins platform
• Office JavaScript API
• Outlook Add-ins
• Microsoft 365 Copilot extensibility

Azure Deployment & Functions:

• Azure App Service
• Azure Container Apps
• Azure Functions
• Azure Functions Python
• Bicep documentation
• Azure CLI reference

Power Platform & Connectors:

• Power Platform overview
• Custom Connectors
• Power Automate
• Power Apps
• Dataverse

Adaptive Cards & WebChat:

• Adaptive Cards Designer
• Adaptive Cards SDK
• Bot Framework WebChat
• Direct Line API

Declarative Agents & Skills:

• Declarative agents
• Agent builder
• API plugins
• Copilot connectors

Microsoft 365 Knowledge & Search:

• Microsoft Search API
• Knowledge connectors
• Graph Connectors
• Search external content

Monitoring & Security:

• Application Insights
• Azure Key Vault
• Azure RBAC
• Azure security baseline

---

License

MIT — See LICENSE