แชร์ผ่าน

Build an Agent 365 agent deployed in Amazon Web Services (AWS)

Important

You need to be part of the Frontier preview program to get early access to Microsoft Agent 365. Frontier connects you directly with Microsoft’s latest AI innovations. Frontier previews are subject to the existing preview terms of your customer agreements. As these features are still in development, their availability and capabilities may change over time.

Learn how to build, host, register, and publish an Agent 365 agent that runs on AWS Elastic Beanstalk, using the Agent 365 CLI. Microsoft Entra and Graph provide the agent identity, permissions, and blueprint, while AWS Elastic Beanstalk provides the runtime.

If you want to point your agent to your code that resides behind an AWS endpoint, you only need the following step: Configure for non-azure hosting. Then, follow all other steps from Agent 365 Development Lifecycle.

Goals

Learn how to use Agent 365 and Microsoft 365 as the control plane and:

  • Deploy agent runtime on AWS Elastic Beanstalk
  • Configure a365.config.json for non‑Azure hosting
  • Create Agent Blueprint in Entra ID
  • Configure OAuth2 + inheritable permissions
  • Register Bot Framework messaging endpoint pointing to AWS
  • Create Agent Identity + Agent User
  • (Optional) Publish to Microsoft 365 app surfaces
  • Test interactions end-to-end

Prerequisites

Before you begin, ensure the following Azure / Microsoft 365, AWS, and local environment prerequisites are met.

Azure / Microsoft 365 prerequisites

Confirm your Microsoft Entra tenant access and install the following tools to create identities, blueprints, and register your agent.

Amazon Web Services (AWS) prerequisites

Ensure the following AWS services and tools are set up to deploy and manage your Elastic Beanstalk environment.

Local development environment prerequisites

Install and configure the following tools locally to build, run, and deploy the agent.

Create and deploy a .NET agent

The following instructions describe how to create a minimal agent that:

  • Responds to GET /
  • Accepts Bot Framework activities on POST /api/messages

Create project directory

mkdir aws-a365-agent
cd aws-a365-agent

Initialize .NET project

To streamline your experience, this article uses a sample that's already prepared. Clone the Agent365 Samples repository and go to the dotnet\semantic-kernel\sample-agent sample.

The Semantic Kernel Sample Agent - C#/.NET sample includes:

  • A minimal ASP.NET Core Web API
  • Bot Framework message handler at /api/messages
  • Health check endpoint at /
  • Semantic Kernel integration for AI capabilities

Go to dotnet\semantic-kernel\sample-agent and verify the project builds successfully:

dotnet restore
dotnet build

Configure model

Follow the instructions in Step 2: LLM configuration to configure the project by using your Open API key.

Test locally (optional)

  1. Before deploying to AWS, test your agent locally:

    # Run the application
dotnet run

  2. Test the endpoints in another terminal:

    # Test agent endpoint locally
curl http://localhost:3978

  3. Press Ctrl+C to stop the local server.

Build and deploy

Choose the option you prefer to build and deploy this sample application:

Option A: Build and deploy from Visual Studio

Use the AWS Toolkit for Visual Studio to publish the app to Elastic Beanstalk by using a guided wizard.

  1. In Solution Explorer, right-click your project.

  2. Select Publish to AWS Elastic Beanstalk.

  3. Follow the Beanstalk Deployment Wizard:

    • Choose your AWS credentials profile.
    • Select Region (For example, us-east-1).
    • Select Platform (.NET Core on Linux).
    • Configure environment settings.

  4. Select Deploy.

The wizard builds, packages, and deploys your application to AWS.

Option B: Build and deploy to AWS Elastic Beanstalk with CLI

Use the Elastic Beanstalk CLI to package and deploy the .NET agent to a 64‑bit Amazon Linux 2 environment. Make sure AWS CLI and EB CLI are configured. The app binds to the PORT environment variable set by Beanstalk.

  1. Build and publish your .NET application:

    # Publish for Linux runtime (AWS Elastic Beanstalk uses Amazon Linux)
dotnet publish -c Release -o ./publish --runtime linux-x64

    Create Procfile with the following content.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Initialize Elastic Beanstalk for .NET. You're prompted to choose Region and Platform:

    eb init

  3. Select:

    • Platform: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Region: Your preferred AWS region (for example: us-east-1)

  4. Create a deployment package and deploy:

    cd publish
zip -r ../deploy.zip .
cd ..
eb create aws-a365-agent-env
eb deploy

    This command:

    • Creates an Elastic Beanstalk application.
    • Creates an environment with a load balancer.
    • Deploys your application.
    • Provisions necessary AWS resources.

  5. When finished, get your Elastic Beanstalk endpoint:

    eb status

    Note your endpoint. It should look something like this:

    http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com

    This endpoint is the messagingEndpoint used by the Agent 365 Dev Tools CLI.

Note

For production environments, configure HTTPS by adding an SSL/TLS certificate in Elastic Beanstalk. The Bot Framework requires HTTPS for production endpoints.

Configure for non-Azure hosting

Create a365.config.json in your Elastic Beanstalk project folder by running a365 config init:

Important

For non-Azure hosting, set these values:

  • messagingEndpoint: your Elastic Beanstalk URL with the /api/messages path
  • needDeployment: false

The a365.config.json file should look something like this:

{
  "tenantId": "YOUR_TENANT_ID",
  "subscriptionId": "YOUR_AZURE_SUBSCRIPTION_ID",
  "resourceGroup": "a365-aws-demo",
  "location": "westus",
  "environment": "prod",

  "messagingEndpoint": "http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/api/messages",
  "needDeployment": false,

  "agentIdentityDisplayName": "MyAwsAgent Identity",
  "agentBlueprintDisplayName": "MyAwsAgent Blueprint",
  "agentUserDisplayName": "MyAwsAgent User",
  "agentUserPrincipalName": "myawsagent@testTenant.onmicrosoft.com",
  "agentUserUsageLocation": "US",
  "managerEmail": "myManager@testTenant.onmicrosoft.com",

  "deploymentProjectPath": ".",
  "agentDescription": "AWS-hosted Agent 365 Agent"
}

The following table summarizes important configuration fields and their purpose.

Field Meaning
messagingEndpoint Your Elastic Beanstalk URL + /api/messages
"needDeployment": false Tells CLI 'I host my own server; don't deploy to Azure'
deploymentProjectPath Where .env stamping happens

Build Agent 365 agent

After your agent code runs against an AWS endpoint, follow the remaining steps from Agent 365 Development Lifecycle to set up your Agent 365 agent.

Verify the agent end-to-end

Use these checks to confirm your AWS-hosted agent is reachable, receiving Bot Framework activities, and responding correctly across Agent 365 surfaces.

Verify Elastic Beanstalk connectivity

Send a GET request to your Elastic Beanstalk endpoint.

curl http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/

The request should return this message:

AWS Agent is running.

Check Elastic Beanstalk logs for incoming Bot Framework messages

Use Elastic Beanstalk logging to verify your agent is receiving Bot Framework activities and responding correctly.

eb logs

Or stream logs in real-time:

eb logs --stream

After a message hits your agent, you see:

POST 200 /api/messages
Received activity: { ... }

Test agent from Agent 365 surfaces

Depending on your environment, you can test your agent from different surfaces:

  • Agents Playground
  • Teams (if published)
  • Agent Shell
  • Federated surfaces

You can send messages and verify your Elastic Beanstalk logs. Learn how to test agents using the Microsoft Agent 365 SDK and validating your agent's functionality with the Agents Playground testing tool.

Developer workflow

Once setup is complete, follow this workflow for iterative development:

Develop and test locally

Use watch mode for rapid development with automatic reloading:

# Automatically rebuild and restart on file changes
dotnet watch run

Make your code changes, save, and test locally before deploying.

Build and redeploy to AWS Elastic Beanstalk

When ready to deploy your changes:

# Clean previous builds (optional but recommended)
dotnet clean

# Publish optimized release build
dotnet publish -c Release -o ./publish --runtime linux-x64

# Create deployment package
cd publish
zip -r ../deploy.zip .
cd ..

# Deploy to AWS
eb deploy

Test and monitor

Test by using Agent 365 surfaces and monitor Elastic Beanstalk logs:

# Stream logs in real-time
eb logs --stream

You don't need to recreate your identity, blueprint, bot endpoint, or permissions.

Troubleshooting

Use this section to diagnose and resolve common problems when deploying and running an Agent 365 agent on AWS Elastic Beanstalk. It covers connectivity and health checks. It also addresses port binding, build errors, and licensing problems.

Tip

Agent 365 Troubleshooting Guide contains high-level troubleshooting recommendations, best practices, and links to troubleshooting content for each part of the Agent 365 development lifecycle.

Messaging endpoint isn't receiving requests

Check the following details:

  • Your endpoint is exactly:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Your Elastic Beanstalk environment is healthy. Use the check by using eb health.
  • Your security group allows inbound HTTP or HTTPS traffic.
  • There are no firewall rules or VPC restrictions.

Application health problems

Check environment health:

eb health --refresh

View detailed logs:

eb logs

Port binding problems

Make sure your application listens on the port specified by the PORT environment variable (Elastic Beanstalk sets this value automatically).

.NET build or runtime problems

Check for build errors by using these commands:

# Clean and rebuild
dotnet clean
dotnet build --verbosity detailed

Verify .NET version:

dotnet --version
dotnet --list-sdks

Check for package problems:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

License assignment fails

Manually assign a valid Microsoft 365 license, or use an unlicensed user path if supported.

  • Last updated on