Del via

Create agent instances

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.

After you publish your agent and make it available in the Microsoft admin center, you can create agent instances and agent users. These instances and users use the agent blueprint and agent code you created.

This article breaks down the process into three main steps:

  1. Configure agent in Teams developer portal
  2. Create agent instance
  3. Test your deployed agent

If you have challenges, refer to the Troubleshooting section.

Prerequisites

1. Configure agent in Teams developer portal

After publishing, configure the agent blueprint in Teams Developer Portal to connect your agent to the Microsoft 365 messaging infrastructure. Without this configuration, your agent doesn't receive messages from Teams, email, or other Microsoft 365 services.

  1. Get your blueprint ID

    Run the a365 config display -g command to display your configuration:

    a365 config display -g

    Copy the agentBlueprintId value from the output.

  2. Navigate to Developer Portal

    Open your browser and go to the configuration page:

    https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

    Replace <your-blueprint-id> with the agentBlueprintId value you copied.

    Note

    If you don't have access to the Developer Portal, contact your tenant administrator to grant you access or complete this configuration on your behalf.

  3. Configure the agent

    In the Developer Portal:

    1. Set Agent Type to Bot Based
    2. Set Bot ID to your agentBlueprintId value
    3. Select Save

    Screenshot showing the Developer Portal configuration page with Agent Type set to Bot Based and Bot ID field filled in.

You need this configuration before you can create agent instances in Teams.

Learn more about Agent Identity Blueprints and Developer Portal configuration.

2. Create agent instance

Now you can request an instance of your agent blueprint from Teams. Learn more about how to discover, create, and onboard an agent.

When you request an agent instance, Teams sends the request to your tenant admin for approval. Admins can review and approve requests from the Microsoft admin center - Requested Agents page.

After the admin approves your request, Teams creates your agent instance and makes it available in Teams.

3. Test your deployed agent

After creating an agent instance, test it in Microsoft 365 to ensure it works correctly in production.

After deployment, and with agent notifications enabled in the Agent 365 SDK, your agent integrates with Microsoft 365 services. It works with Teams for chats, channels, and meetings; with email and calendar for sending, receiving, and scheduling; and with SharePoint and OneDrive for document access and file sharing. It also supports collaboration features such as organizational presence, Planner tasks, and document comments.

Important

Just like regular users, agent users also require appropriate Microsoft 365 licenses to access services. Common licenses include Microsoft 365 E5, Teams Enterprise, and Microsoft 365 Copilot.

View deployed agent in admin center

After you publish your agent, it appears in Microsoft admin center for hiring. It might take some time to propagate.

Go to the Microsoft 365 admin center - Agents to:

  • View your published agent
  • Manage agent settings
  • Monitor agent usage
  • Configure permissions

Test agent in Teams

After deploying, publishing, and configuring your agent blueprint, and creating an agent user, test the agent user directly in Microsoft Teams:

Note

Frontier required: Ensure that Microsoft Agent 365 Frontier is enabled for your tenant and your admin needs to grant you access. This access is required to create agent instances and interact with agents in Microsoft Teams while Agent 365 is in preview. Learn more about frontier Contact your tenant administrator if you don't have access.

Start testing

  1. Search for your new agent user in Teams

    Note

    The agent user creation process is asynchronous and can take a few minutes to a few hours for the agent user to become searchable after it's created.

  2. Start a new chat with your newly created agent instance.

  3. Send test messages to verify agent functionality.

Example test message

If you configured the agent with Email, send this message to test email functionality. Update the recipient recipient@contoso.com email value.

Send an email to <recipient@contoso.com> with subject "Hello from Teams" and message "This is a test message from my agent!"

The agent processes the request and sends the email without requiring more confirmation.

Verification checklist

After creating your agent instance, verify it's working correctly in Teams.

✅ Developer portal configuration saved
✅ Agent appears in Teams apps search
✅ You can create instance agent to teams
✅ Agent instance created
✅ Agent user appears in organization
✅ Agent responds to messages
✅ Agent can perform actions
✅ Application logs show no errors
✅ Observability working in admin center

If your agent instance isn't working as expected, see the Troubleshooting section for detailed solutions to common problems.

Verify developer portal configuration is saved

Navigate to: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

✅ Agent Type shows: Bot Based
✅ Bot ID matches your agentBlueprintId
✅ Shows Saved successfully message

Verify agent appears in Teams

  1. Open Teams > Apps

  2. Search for your agent name

    ✅ Agent appears in search results
    ✅ Shows your agent icon and description

Verify you can create instance agent to teams

Select your agent in Teams Apps

✅ Request Instance/Create Instance button is enabled
✅ Can request instance without errors

Verify agent instance created

After selecting Request Instance:

✅ Request sends successfully to admin

Verify agent user appears in organization

In Microsoft 365 admin center:

  1. Go to: https://admin.cloud.microsoft/#/agents/all
  2. Navigate to All Agents Requests tab

✅ Your agent instance request is listed with state as pending review
✅ Admin can approve the agent instance for use
✅ User can then create instance from Teams and give it a name.

Verify agent responds to messages

In Teams chat with your agent - Send a test message: Hello!

✅ Agent shows typing indicator
✅ Agent responds within a few seconds
✅ Response is coherent and relevant

Verify agent can perform actions

If tools are configured, test tool functionality. For example, if you added the Mail MCP server, send a test email to yourself.

Agent should:

✅ Acknowledge the request
✅ Execute the tool call
✅ Confirm successful completion

You should verify the email arrives in your inbox.

Verify functionality

The following checklist provides a systematic testing approach for your agent:

Basic functionality:

✅ Agent responds to simple greetings.
✅ Agent handles multistep conversations.
✅ Agent provides relevant responses.

Tool functionality:

Depends on the MCP server configuration

✅ Can send emails.
✅ Can access calendar.
✅ Can search documents.
✅ Can perform configured actions.

Error handling:

✅ Handles invalid requests gracefully.
✅ Provides helpful error messages.
✅ Doesn't crash on unexpected input.

Performance:

✅ Responds within a few seconds.
✅ No timeout errors.
✅ Consistent response times.

Verify application logs

To see what your agent is doing, check the application logs using the az webapp log tail command.

# Real-time logs from Azure
az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

What to look for in logs:

✅ Incoming requests from Teams
✅ Successful authentication
✅ Tool calls being executed
✅ Responses being sent
❌ Error messages or exceptions

Verify observability in admin center

After your agent starts running:

  1. Go to: https://admin.cloud.microsoft/#/agents/all

  2. Select your agent and open the Activity tab.

    You should see:

    ✅ Sessions appearing.
    ✅ Each session shows triggers and actions.
    ✅ Tool calls are logged with timestamps.

Next steps

Your agent is now live in the cloud and ready to work alongside your team in Microsoft 365. What started as local code is now a discoverable, enterprise-ready assistant where users can create agent instances across your organization.

Your agent's development lifecycle is complete, but its impact is just beginning. Much of what you built in the agent 365 developer lifecycle is open source and welcomes community contributions. Raise bugs, feature requests, and pull requests:

Troubleshooting

This section contains common issues when creating and testing agent instances.

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.

Agent doesn't appear in Teams

Symptom: Agent appears in admin center but can't find it in Teams Apps.

Root cause: Missing Developer Portal configuration.

Solution:

  1. Get your blueprint ID:

    a365 config display -g
# Copy the agentBlueprintId value

  2. Configure in Developer Portal:

    1. Go to: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration
    2. Set Agent Type to Bot Based
    3. Set Bot ID to your agentBlueprintId
    4. Select Save

  3. Wait 5-10 minutes for propagation.

Verification:

  • Open Teams > Apps > Search for your agent
  • Agent appears and is available to add

Can't create agent instance in Teams

Symptom: Agent appears in Teams but can't add or create instance; Request Instance button doesn't work.

Root cause: Microsoft Agent 365 Frontier isn't enabled for the tenant.

Solution: Contact your tenant administrator to verify Microsoft Agent 365 Frontier is enabled for the tenant

Learn more about Frontier

Verification:

Frontier features appear within Microsoft 365 Copilot and Microsoft 365 apps once your license and admin settings allow it.

Agent not responding to messages

Symptom: Created agent instance but it doesn't respond to messages; no logs in the application.

Root cause: Multiple possible causes - messaging endpoint issues, authentication problems, or configuration errors.

Basic troubleshooting

  1. Verify the web app is running:

    az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Should be: "Running"

  2. Check the messaging endpoint:

    • It should be: https://<your-app-root-url>/api/messages
    • Verify it in a365.config.json and a365.generated.config.json

  3. Test the endpoint directly:

    curl https://<your-app-root-url>/api/messages
# Should not return 404

  4. Check application logs:

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
# Look for incoming requests and errors

Advanced diagnostics

  1. Verify authentication:

    • Check if tokens are expired. Renew them if needed.
    • Verify credentials in Web App configuration.

  2. Check tool/MCP configuration:

    • Verify MCP servers are configured.
    • Check permissions are granted.

  3. Test locally:

    • Run agent locally with same configuration.
    • Test with Agents Playground.
    • If works locally but not in cloud > deployment issue

Common solutions

  • Messaging endpoint incorrect: Update in Azure portal and Developer Portal
  • Web app stopped: Start it using Azure portal or CLI
  • Token expired: Update tokens in Web App environment variables
  • Missing environment variables: Check App Settings in Azure portal
  • MCP server problems: Verify service principal and permissions
  • Code errors: Check application logs for exceptions

Verification

Send a message to your agent in Teams and check application logs for incoming requests.

You may also want to try:

Tool calls failing

Symptom: Agent responds to messages but tool calls fail. You see permission denied or timeout errors.

Root cause: Missing MCP server permissions, service principal not configured, network connectivity problems, or incorrect tool configuration.

Solutions

Try the following solutions when tool calls fail:

  • Verify permissions in admin center

    Review and approve required MCP server permissions:

    • Go to: https://admin.cloud.microsoft/#/agents/all
    • Select your agent > Permissions
    • Make sure the list includes and approves the required MCP servers

  • Check service principal

    Run the one-time setup script if you didn't run it before:

    # Download and run:
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • Verify MCP endpoint configuration

    Ensure you're using the production MCP endpoint:

    # Should be production endpoint, not mock
MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft/mcp/v1

  • Check managed identity

    Verify managed identity is enabled on your Web App:

    # Verify managed identity is enabled
az webapp identity show --name <your-app-name> --resource-group <your-resource-group>

Verification

Test tool calls through Teams and check the logs for successful execution.

You may also want to try these steps:

License assignment fails

Symptom: Can't assign license to agentic user; license errors in admin center.

Root cause: Insufficient licenses available, incorrect license type, or permissions issue.

Solutions

Try the following solutions when license assignment fails:

  1. Verify licenses are available:

    • Check Microsoft 365 admin center > Billing > Licenses
    • Ensure Microsoft Agent 365 Frontier is enabled for the tenant

  2. Manually assign license:

    • Go to Microsoft 365 admin center > Users
    • Find the agentic user
    • Assign appropriate license

  3. Required licenses for full functionality:

    • Microsoft 365 E5 (or equivalent)
    • Teams Enterprise
    • Microsoft 365 Copilot (for Copilot features)

Verification

Check user profile in admin center shows assigned licenses.

  • Last updated on