ATK CLI and Deployment for M365 Agents

ATK CLI Overview

The Agents Toolkit (ATK) CLI is the official toolchain for M365 agent project management. It handles the complete agent lifecycle from creation to deployment.

Golden Rule: Check if ATK CLI is available (npx -y --package @microsoft/m365agentstoolkit-cli atk --version). If not found, STOP and tell the user that the ATK CLI is required but not installed. Do NOT attempt to install it yourself. Then use npx -y --package @microsoft/m365agentstoolkit-cli atk for all commands.

🚨 Never use shortcuts, .vscode tasks, or abbreviated commands.

Agent Lifecycle

1. Project Creation

# Create new agent project
npx -y --package @microsoft/m365agentstoolkit-cli atk new \
  -n my-agent \
  -c declarative-agent \
  -with-plugin type-spec \
  -i false

# Navigate into project
cd my-agent

Project structure created:

my-agent/
├── appPackage/
│   ├── manifest.json                   # Teams app manifest
│   ├── declarativeAgent.json           # Declarative agent definition
│   ├── instructions.txt                # Agent instructions
│   └── adaptiveCards/
│       └── card.json                   # Adaptive card template (from template)
├── assets/                             # Asset files directory
├── env/
│   ├── .env.local                      # Local environment (template)
│   └── .env.local.user                 # Local environment (secrets, generated)
├── package.json                        # Node.js dependencies
├── m365agents.yml                      # M365 agents config
├── m365agents.local.yml                # M365 agents local config
└── README.md

2. Provisioning

Provisioning generates M365 Title ID on first time and makes the updated agent available to the developer on Microsoft 365 Copilot.

# Provision for development
npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env dev --interactive false

# Provision for staging
npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env staging --interactive false

# Provision for production
npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env prod --interactive false

# Provision for a custom environment
npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env custom --interactive false

What provisioning does:

Registers agent in Microsoft 365 Copilot
Generates M365_TITLE_ID and adds to env file
Sets up authentication and permissions
Registers OAuth credentials (if oauth/register is in the lifecycle — see authentication.md)

⚠️ M365_TITLE_ID requires teamsApp/extendToM365: The M365_TITLE_ID environment variable is generated by the teamsApp/extendToM365 lifecycle step during provisioning. Without this step, the Teams app registers but the agent will not appear in Copilot Chat. If you scaffolded the project with npx -y --package @microsoft/m365agentstoolkit-cli atk new, this step is included automatically. If you set up the project manually, verify that your m365agents.yml includes the teamsApp/extendToM365 lifecycle action — see the mcp-plugin.md scaffold section for the required lifecycle steps.

⚠️ CRITICAL: ALWAYS RENDER THIS AFTER ANY PROVISION OPERATION ⚠️

After EVERY provisioning command (regardless of environment or whether it's first-time or re-provisioning), you MUST output a test link:

Local environment — read M365_TITLE_ID from env/.env.local and construct the URL:

✅ Provision completed successfully!

🚀 Test Your Agent:
🔗 https://m365.cloud.microsoft/chat/?titleId={M365_TITLE_ID}

Non-local environments (dev, staging, prod, etc.) — use the SHARE_LINK value from env/.env.{environment}:

✅ Provision completed successfully!

🚀 Test Your Agent:
🔗 {SHARE_LINK}

This is REQUIRED for:

✅ First-time provisioning
✅ Re-provisioning after changes
✅ Any environment (local, dev, staging, prod, custom)
✅ Every single npx -y --package @microsoft/m365agentstoolkit-cli atk provision command — ALWAYS use --interactive false

Do NOT skip this output. The user needs this link to test their agent.

4. Packaging (Optional)

Package agent for distribution or publishing.

# Package for development
npx -y --package @microsoft/m365agentstoolkit-cli atk package --env dev

# Package for production
npx -y --package @microsoft/m365agentstoolkit-cli atk package --env prod

What packaging does:

Creates .zip file in appPackage/build/
Validates manifest and package structure
Prepares for sharing or publishing

5. Sharing (Shared Agents Only)

Share agents with users or entire tenant.

IMPORTANT: Only for agents with AGENT_SCOPE=shared

Check before sharing:

grep "AGENT_SCOPE=shared" env/.env.dev

If the developers isn't clear on the sharing scope, ask follow-up questions to clarify.

Do you want to share the agent with the entire tenant or specific users / groups?
What is the environment you want to share in (dev, staging, prod)?
If they schoose specific users or groups, what are the email addresses of those users or groups?

Share with entire tenant:

npx -y --package @microsoft/m365agentstoolkit-cli atk share \
  --scope tenant \
  --env dev \
  -i false

Share with specific users:

npx -y --package @microsoft/m365agentstoolkit-cli atk share \
  --scope users \
  --email 'user1@contoso.com,user2@contoso.com' \
  --env dev \
  -i false

6. Publishing (Optional)

Publish to Microsoft 365 App Store or organizational catalog.

# Publish to catalog
npx -y --package @microsoft/m365agentstoolkit-cli atk publish --env prod

What publishing does:

Submits agent to Microsoft 365 catalog
Requires admin approval in tenant
Makes agent discoverable to users

Environment Management

Agent Scope

Two deployment models:

Personal Agents (AGENT_SCOPE=personal):

Each user gets their own instance
Agent accesses user's personal data
No sharing required
Use for: Personal productivity agents

Shared Agents (AGENT_SCOPE=shared):

Single instance shared by multiple users
Requires explicit sharing via npx -y --package @microsoft/m365agentstoolkit-cli atk share
Use for: Team agents, organizational assistants

Environment Files Structure

env/
├── .env.local      # Local development (not committed)
├── .env.dev        # Development environment
├── .env.staging    # Staging environment
└── .env.prod       # Production environment

If there are any secrets or sensitive values, the content will be in a separate file named .env.{environment}.user that is not committed to source control.

env/
├── .env.local.user      # Local development (not committed)
├── .env.dev.user        # Development environment
├── .env.staging.user    # Staging environment
└── .env.prod.user       # Production environment

Common variables in .env files:

# Agent identification
APP_NAME_SHORT=MyAgent
M365_TITLE_ID=U_abc123xyz           # Generated during provision

# Agent configuration
AGENT_SCOPE=shared                  # or 'personal'

# API configuration (if using API plugins)
API_ENDPOINT=https://api.example.com

# Azure resources (generated during provision)
AZURE_RESOURCE_GROUP=rg-myagent-dev
AZURE_APP_SERVICE=app-myagent-dev

Common variables in .env.{environment}.user files:

# API configuration (if using API plugins)
API_KEY=your-api-key

Security best practices:

Add env/.env.local to .gitignore
Never commit secrets to source control
Use different credentials per environment

Version Management

When to Bump Version

Version must be bumped before re-provisioning a shared agent that already has M365_TITLE_ID.

Check if version bump is required:

grep -q "AGENT_SCOPE=shared" env/.env.dev && \
grep -q "M365_TITLE_ID=" env/.env.dev && \
echo "⚠️ VERSION BUMP REQUIRED"

If there is no environment variable to handle the APP_VERSION, create one and assign the current value of the version in the manifest.

How to Bump Version

Edit appPackage/manifest.json:

{
  "version": "${{APP_VERSION}}",  // Update this field
  // ... rest of manifest
}

Edit env/.env.{environment}:

APP_VERSION=1.0.1  # Bump patch, minor, or major as needed
# ... rest of env variables

Semantic Versioning

Follow semver (major.minor.patch):

Patch (1.0.0 → 1.0.1): Bug fixes, content updates, minor changes
Minor (1.0.0 → 1.1.0): New features, capabilities, backward compatible
Major (1.0.0 → 2.0.0): Breaking changes, incompatible updates

Complete Workflows

Initial Deployment Workflow

# 1. Validate
# Run the validation to ensure everything is correct

# 2. Provision (first time only)
# Run the provsion to register agent in M365 and make it available

# 3. Share (only if AGENT_SCOPE=shared)
# Share with users or tenant as needed

# 4. Test agent
# Open link provided in deploy output

Update Workflows

For code changes or manifest changes:

# 1. Validate
# Run validation to ensure changes are correct

# 2. Provision
# Run provision to update agent in M365

For shared agent re-provisioning:

# 1. Bump APP_VERSION in env/.env.{environment}
# Edit version: "1.0.0" → "1.0.1"

# 2. Validate
# Run validation to ensure everything is correct

# 3. Re-provision
# Run provision to update agent in M365

# 4. Share with users (if not already shared)
# Run share command if needed

Multi-Environment Deployment

# 1. Deploy to dev
# Run provision for dev environment
# Test in dev environment

# 2. Deploy to staging
# Run provision for staging environment
# Validate in staging

# 3. Deploy to production
# Run provision for production environment
# Share with tenant if needed

Authentication

Microsoft 365 Authentication

Required for sharing and publishing agents.

# Login to M365
npx -y --package @microsoft/m365agentstoolkit-cli atk auth login m365

# List current authentication
npx -y --package @microsoft/m365agentstoolkit-cli atk auth list

# Logout
npx -y --package @microsoft/m365agentstoolkit-cli atk auth logout m365

Required permissions:

Need to have a M365 Copilot license

Testing Agents

Testing Deployed Agents

After deployment, ATK provides a test link:

🚀 Test Your Agent:
🔗 https://m365.cloud.microsoft/chat/?titleId=abc123xyz

Testing checklist:

✅ Agent appears in Copilot
✅ Conversation starters display correctly
✅ Capabilities work (search, API calls, etc.)
✅ Instructions are followed
✅ Error scenarios handled gracefully
✅ Permissions are appropriate

Troubleshooting

Check System Prerequisites

npx -y --package @microsoft/m365agentstoolkit-cli atk doctor

Checks:

Node.js version
npm version
Azure CLI installation
Authentication status
Network connectivity

Common Issues

"Command not found" or slow first run:

ATK CLI downloads on first use (10-30 seconds)
Wait for download to complete
Ensure internet connectivity

"Authentication required":

# Check auth status
npx -y --package @microsoft/m365agentstoolkit-cli atk auth list

# Login to M365
npx -y --package @microsoft/m365agentstoolkit-cli atk auth login m365

"Environment not provisioned":

Check env/.env.{environment} exists
Check M365_TITLE_ID is present in env file
Run provision for the environment

"Permission denied":

Verify Azure Contributor/Owner role
Verify M365 admin permissions
Check Azure subscription is active

"Version conflict" (shared agents):

Bump APP_VERSION in env/.env.{environment}
Re-run provision after version bump

"Validation failed":

Verify all required manifest fields
Ensure icons exist in appPackage/

Best Practices

Environment Strategy

Local (.env.local): Developer personal testing
Dev (.env.dev): Shared development environment
Staging (.env.staging): Pre-production validation
Prod (.env.prod): Production deployment

Version Control

Commit environment templates (without secrets)
Don't commit .env.user.local or files with secrets
Use .gitignore for sensitive files
Document required environment variables

Deployment Strategy

Develop and test locally
Deploy to dev environment
Validate in staging
Deploy to production
Monitor and iterate

Sharing Strategy

Start with user-scoped sharing for testing
Expand to tenant-wide after validation
Document who has access
Review sharing permissions regularly

/declarative-agent-developer

referencesdeployment.md