Quickstart: Build your first autopilot

In this quickstart, you take an autopilot from nothing to a working instance in Microsoft Teams. You provision the infrastructure, create an autopilot blueprint from a hosted agent, publish it, have an administrator approve it, and hire your own instance.

An autopilot is an agent that acts as itself in Microsoft 365, under its own identity. You don't build an autopilot directly: you build a blueprint, and each autopilot is an instance created from it. For the model behind that, see What is an autopilot in Microsoft Foundry?

Prerequisites

Licensing and enrollment

Creating an autopilot with an agent user account requires the following:

• Enroll your tenant in the Frontier preview program.
• Accept the Microsoft Agent 365 terms of service after you enroll. For details, see Preview Microsoft Agent 365 features through the Frontier program.
• Confirm that your tenant has at least one Microsoft 365 Copilot license or one Microsoft Agent 365 license, including Microsoft E7.
• Confirm that a Microsoft Agent 365 Frontier license is available. After enrollment, eligible tenants receive a 25-seat preview subscription. Each Foundry autopilot instance consumes one license, because each instance creates an agent user account.

Check the seat count before you begin. If your tenant has no free seats, the build completes and then fails when you create the instance.

Permissions

Provisioning creates role assignments as well as resources, which is why Contributor alone isn't enough. For the full matrix, see Hosted agent permissions reference.

You don't need a Microsoft Entra directory role. Foundry creates the agent identity blueprint when you create the agent.

Tools

• Azure CLI
• Azure Developer CLI
• Docker, running

Create all resources in a region that supports hosted agents. See Region availability.

Choose a code sample

Who does this: you.

This quickstart uses a code sample. Everything you deploy comes from the sample, so clone one before you start. Both samples do the same thing, so pick the language you prefer:

• Autopilot agent sample (C#)
• Autopilot agent sample (Python)

Clone the sample, and then open its folder in a terminal. Run every command in this quickstart from that folder.

The sample contains the agent code, the infrastructure templates, and the scripts that create and publish the agent.

Provision, build, and publish

Who does this: you or an Azure administrator. This stage needs every permission in the Permissions table except the two that belong to your administrator and to hiring.

From the sample folder, sign in with both CLIs, and then provision.

az login --tenant <tenant-id>
azd auth login --tenant-id <tenant-id>
azd provision

One command runs three stages: it provisions the infrastructure, builds the agent blueprint, and publishes it. The next three sections explain what each stage does and how to confirm it worked.

Expected result: azd provision completes with no failed resources, and a request is waiting in the Microsoft 365 admin center.

Depending on your tenant settings, you might need extra Azure CLI sign-in scopes before you provision, such as scopes for Foundry, Microsoft Graph, and Azure Resource Manager. If azd auth login returns an authorization error, use the sign-in commands in the sample README.

You can also run the stages separately, which is useful when different people hold the permissions or when you want to change the agent between stages. Use azd provision --preview to see what the template creates before you commit to it. To control each stage yourself, call the create and publish scripts in the sample's scripts folder directly instead of letting the post-provision hooks run them.

Provision the infrastructure

Permission needed: Owner, or Contributor plus Role Based Access Control Administrator, at resource group scope.

The sample creates a Foundry account and project, a model deployment, an Azure Container Registry, and Application Insights with a Log Analytics workspace. It also creates the role assignments those resources need, which is the part Contributor alone can't do.

Expected result: every resource in the sample template exists and reports success.

Build the agent blueprint

Permission needed: Foundry User at project scope, and AcrPush or Container Registry Repository Writer at registry scope.

The sample compiles your agent code into a container image, pushes it to the registry, and creates a hosted agent along with its first agent version. Traffic routes to that version.

The agent creates two Microsoft Entra objects: an agent identity blueprint and an agent identity for the agent itself. You don't create these objects, and you don't need a directory role to get them.

Save the deployment values. You need them if you troubleshoot:

azd env get-values

Expected result: the output includes your agent name, agent version, and blueprint ID.

To change what the agent does before you publish it, edit the agent instructions and tool manifest in the sample, and then run azd provision again. Each run creates a new agent version.

Publish the agent blueprint

Permission needed: Foundry User at project scope.

Publishing submits your agent as an autopilot blueprint and puts it in front of your administrator. The sample does this at the end of provisioning, using the publish script in its scripts folder.

Publishing sets three things that matter later:

• Autopilot publishing, which is what makes this a blueprint that hires instances rather than an agent published to the agent store.
• The hiring scope, which decides who can create instances after approval.
• The display details, including name, descriptions, and icon.

Expected result: the publish call succeeds and a request is waiting in the Microsoft 365 admin center.

The publish API

The sample calls the Microsoft 365 publish API for you. Read this section if you're automating the flow, or if you want to know what the sample sends.

POST {{endpoint}}/agents/<agent-name>/microsoft365/publish?api-version=2025-11-15-preview
Authorization: Bearer <access-token>
Content-Type: application/json

{{endpoint}} is your project endpoint, in the form https://<resource-name>.services.ai.azure.com/api/projects/<project-name>. Get a token for the https://ai.azure.com audience:

az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv

Four fields distinguish an autopilot from an agent published to the Microsoft 365 Copilot and Teams agent stores. Set all four:

The agenticUserTemplate object carries the identity settings for the agent user account:

The remaining fields are the display details users see, and they behave the same as for any published agent: agentDisplayName, appVersion, shortDescription, fullDescription, developerName, developerWebsiteUrl, privacyUrl, and termsOfUseUrl. Set canRespondWithoutMention to control whether the autopilot responds to all messages on its Teams surfaces or only when someone @mentions it.

A complete request body for an autopilot:

{
  "agentDisplayName": "Contoso Workstream Manager",
  "publishAsAutopilot": true,
  "publishScope": "Tenant",
  "appVersion": "1.0.0",
  "canRespondWithoutMention": true,
  "shortDescription": "Keeps release work on track.",
  "fullDescription": "Tracks release readiness, updates work items, and sends weekly status.",
  "developerName": "Contoso IT",
  "developerWebsiteUrl": "https://contoso.com",
  "privacyUrl": "https://contoso.com/privacy",
  "termsOfUseUrl": "https://contoso.com/terms",
  "useAgenticUserTemplate": true,
  "agenticUserTemplate": {
    "Id": "digitalWorkerTemplate",
    "File": "agenticUserTemplateManifest.json",
    "SchemaVersion": "0.1.0-preview",
    "AgentIdentityBlueprintId": "<blueprint-client-id>",
    "CommunicationProtocol": "activityProtocol"
  }
}

To publish an agent to the agent stores instead, set publishAsAutopilot to false and omit the agent user template. For that flow, see Publish agents to Microsoft 365 and Teams by using the REST API.

Approve the blueprint

Who does this: your tenant administrator, with Global Administrator or AI Administrator. Reader roles can see the request but can't approve it.

Approving runs a four-part wizard: choose who gets the agent, apply a policy template, grant consent, and publish.

1. Sign in to the Microsoft 365 admin center, and then select Agents > All agents.

2. On the Requests tab, find your autopilot. Its state is Pending activate.

   

3. Select the autopilot to open the Publish new agent wizard.

4. On Publish to users, confirm the host products and the publish audience. Under Activate, select who can create agent instances: None, All users, or Specific users or groups. This choice is the hiring scope.

   

5. On Apply template, choose a policy template. Microsoft policies apply by default, and administrators add and edit custom policies. This step also shows how many autopilot licenses the tenant has available.

   

6. On Accept permissions, review the permissions the autopilot requests and select Grant admin consent. Consent here governs the token, meaning what kinds of calls the autopilot is ever allowed to make. It grants no team's data to anyone.

   

7. On Review and finish, check the audience, the activation scope, and the policy template, and then select Publish.

   

8. Verify the autopilot on the Registry tab. Its status is Available.

   

Expected result: the autopilot appears in the registry as Available, and the people in the hiring scope can create instances.

Create your instance

Who does this: you, if your administrator included you in the hiring scope.

After the autopilot is in the registry, you can hire it from either the Microsoft Teams app store or the Microsoft 365 Copilot agent store.

1. Find the autopilot under Agents for your team.

   In Microsoft Teams, go to Apps > Agents for your team.

   

   In Microsoft 365 Copilot, go to Agents > Agents for your team.

   

2. Select the autopilot, and then select Create instance.

3. Name the instance, set its alias and domain, and confirm who manages it. The name can be up to 32 characters.

   

4. Select Create.

Creating the instance consumes one license and creates the instance's own agent identity and agent user account. You become its manager.

Expected result: the autopilot starts a Teams chat with you and appears in your organization chart.

Clean up resources

To remove the Azure resources you created, run:

azd down

Deleting Azure resources doesn't remove the instances people hired from your blueprint. Work with your administrator to retire the blueprint.

Troubleshooting

Related content

• What is an autopilot in Microsoft Foundry? explains the identity model and why autopilots use blueprints.
• Autopilot lifecycle in Microsoft Foundry covers what happens after you publish, including updating and ending an autopilot.
• Microsoft Agent 365 integration with Foundry covers registry sync, data collection, and data residency.