Setting up Agent 365 config

The Agent 365 CLI needs to know your tenant, subscription, and other details to create the required agent resources like Agent Blueprint. The CLI stores this information in a central configuration file called a365.config.json in your working directory. All commands of the CLI use this configuration file.

Prerequisites

Before you begin, ensure you have the following prerequisites:

• Agent 365 CLI - See Agent 365 CLI installation.

Required permissions:

• Valid Microsoft Entra tenant user with one of the following roles:
  • Global Administrator
  • Agent ID Administrator
  • Agent ID Developer
• Access to an Azure subscription with permissions to create resources

Configure the Agent 365 CLI

The a365 config init command creates a365.config.json, the central configuration file used by all Agent 365 CLI commands, in your working directory. The CLI provides an interactive wizard with Azure CLI integration and smart defaults to minimize manual input.

Authenticate with Azure

Before initializing configuration, authenticate with Azure by using the az login command:

az login

Select the appropriate subscription when prompted. The configuration wizard uses Azure CLI to query available subscriptions, resource groups, and app service plans. For the smoothest development experience, set up your tenant user account with the right role and permissions, subscription, and app service plan before starting.

Initialize configuration

Run the a365 config init command to start the interactive configuration wizard:

a365 config init

The wizard uses Azure CLI integration and smart defaults to minimize manual input. You're prompted for:

The wizard automatically generates related resource names (web app, agent identity, blueprint, agent user) and validates your project type. Before saving, you can optionally configure custom blueprint permissions for external resources (such as Teams presence or OneDrive files) and customize any of the generated names.

Learn more about the configuration file structure

Custom blueprint permissions

If your agent needs access to resources beyond the default set (Microsoft Graph, Messaging Bot API, Observability API, Power Platform), declare them in the customBlueprintPermissions field of a365.config.json:

{
  "customBlueprintPermissions": [
    {
      "resourceAppId": "00000003-0000-0000-c000-000000000000",
      "resourceName": "Microsoft Graph",
      "scopes": ["Mail.Read", "Mail.Send"]
    },
    {
      "resourceAppId": "<your-api-app-id>",
      "resourceName": "My Custom API",
      "scopes": ["MyApi.ReadWrite"]
    }
  ]
}

After adding custom permissions to a365.config.json, apply them to your blueprint:

a365 setup permissions custom

Or include them in the full setup:

a365 setup all

Verify Agent 365 configuration files

Agent 365 uses multiple configuration files throughout the development lifecycle:

After completing the configuration, verify that you have the following items:

Verify creation of a365.config.json file

Visually verify that the a365.config.json file exists. Or, use the Test-Path PowerShell command in a script to automate this verification.

# Check file exists in current working directory
Test-Path a365.config.json
# Should return: True

Verify a365.config.json configuration data

Run the a365 config display command to view the current Agent 365 CLI configuration.

a365 config display

The output of this command looks like this:

{
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "resourceGroup": "your-resource-group",
  "location": "location-of-your-azure-resources",
  "environment": "prod",
  "aiTeammate": true,
  "needDeployment": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "appServicePlanName": "your-app-service-plan",
  "appServicePlanSku": "service-plan-sku",
  "webAppName": "your-web-app",
  "agentIdentityDisplayName": "your-agent-name Identity",
  "agentBlueprintDisplayName": "your-agent-name Blueprint",
  "agentUserPrincipalName": "youragent@yourtenant.onmicrosoft.com",
  "agentUserDisplayName": "your-agent-name Agent User",
  "managerEmail": "manager@yourtenant.com",
  "agentUserUsageLocation": "usage-location",
  "deploymentProjectPath": "C:\\path\\to\\your\\project",
  "agentDescription": "your-agent-name - Agent 365 Agent"
}

Verification checklist

✅ All fields have valid values (no empty strings or nulls)
✅ tenantId and subscriptionId are valid GUIDs
✅ clientAppId is a valid GUID (your custom client app registration)
✅ resourceGroup and appServicePlanName exist in your Azure subscription
✅ managerEmail uses your tenant domain
✅ deploymentProjectPath points to your agent code directory
✅ agentUserPrincipalName follows the format agentname@tenant.com
✅ environment is set (typically prod)
✅ needDeployment is true for initial setup. If you don't need deployment, learn how to set an agent messaging endpoint.

If your configuration doesn't match the expected output, see the Troubleshooting section for detailed solutions.

Add a365.generated.config.json to your .gitignore file. This file contains generated secrets and should never be committed to source control.

Next step

If everything checks out, you're ready to proceed.

Config-free setup with --agent-name

You can provision agents (not AI teammates) without creating an a365.config.json file. The CLI automatically resolves the required values at runtime.

# Provision an Agent without a config file
a365 setup all --agent-name <your-agent-name>

When you provide --agent-name:

• The CLI auto-detects the Tenant ID from az account show. Override it with --tenant-id <id> if needed.
• The CLI finds an Entra app registration named Agent 365 CLI in the tenant to resolve the Client app. You don't need to include clientAppId in the config.
• The Deployment project path defaults to the current directory. Run the command from your agent project folder.

To clean up resources provisioned without a config file:

a365 cleanup --agent-name <your-agent-name>

Cleanup reads resource IDs from the global generated config file written by the bootstrap setup, so no a365.config.json is required.

Agent identity modes

The aiTeammate field controls how agent instances are provisioned and what identity they carry at runtime. Choose the right mode based on what your agent needs to do.

Standard mode (aiTeammate: false) — default

Use this mode when your agent acts as a service or backend integration - processing messages, responding to events, or calling APIs - without needing a user identity per instance. This mode broadens the range of agents you can build: any service that communicates with the Agent 365 platform can be registered as an agent, even if it doesn't represent a user or participate in user-facing collaboration experiences.

This mode is the default. Run setup without flags, or pass --aiteammate false explicitly:

# Standard setup (default)
a365 setup all

# Equivalent explicit form
a365 setup all --aiteammate false

Agents also support config-free provisioning via --agent-name. See Config-free setup with --agent-name.

AI teammate mode (aiTeammate: true)

Use this mode when your agent needs to act as a first-class participant alongside human users - for example, joining meetings, sending messages on behalf of a user, or being assigned tasks in a workflow. Agent instances provisioned in this mode receive a dedicated user identity, allowing the platform to identify and interact with each instance individually.

AI teammate setup requires a a365.config.json initialized with a365 config init. Pass --aiteammate true to select this mode:

a365 setup all --aiteammate true

Troubleshooting

Use these steps to quickly diagnose and resolve common issues with a365.config.json and the Agent 365 CLI.

• Configuration file doesn't exist
• Missing or invalid configuration values
• Invalid tenant or subscription
• Custom client app validation fails
• Invalid agent user principal name
• Web app name already taken

Configuration file doesn't exist

Symptom: CLI commands fail with "Configuration not found" or Test-Path a365.config.json returns False.

Solution: Create a new a365.config.json file.

Complete the steps to Authenticate with Azure and Initialize configuration.

Missing or invalid configuration values

Symptom: Configuration file exists but has empty fields or validation errors.

Solution: Follow the steps to verify a365.config.json configuration data.

If any field is incorrect:

• Option 1: Rerun the wizard by using the a365 config init command.
• Option 2: Manually edit a365.config.json with correct values.

Invalid tenant or subscription

Symptom: CLI fails with authentication or authorization errors.

Solution:

Use these commands to reauthenticate with Azure, verify the signed-in account, switch to the correct subscription, and reinitialize the Agent 365 CLI configuration.

# Re-authenticate with Azure
az login

# Verify you're logged into the correct account
az account show

# If needed, switch to the correct subscription
az account set --subscription "<subscription-name-or-id>"

# Re-initialize configuration
a365 config init

Custom client app validation fails

Symptom: Configuration wizard fails when validating the custom client app ID.

Solution: Review your custom client app registration to ensure your app registration has all required permissions and admin consent.

Invalid agent user principal name

Symptom: Validation fails for the agent user principal name during configuration.

Solution: Ensure the UPN follows the format username@domain. For example, demo.agent@contoso.onmicrosoft.com. A missing domain suffix is the most common cause.

Web app name already taken

Symptom: Setup fails because the web app name is already in use.

Solution: Web app names must be globally unique in Azure. Update webAppName in a365.config.json to a unique value, or re-run a365 config init to generate a new name.