Test agents by using Dev Tunnels

By using Dev Tunnels, you can test your Agent 365 agent with Microsoft 365 applications (such as Teams, Outlook, or Word) while your agent runs locally on your development machine. This approach bridges local development and real-world testing, so you can validate agent behavior in actual Microsoft 365 environments before deploying to the cloud.

Prerequisites

Before using Dev Tunnels, make sure you install the Dev Tunnels command-line tool.

• Windows: winget install Microsoft.devtunnel
• macOS/Linux: Download from aka.ms/devtunnels/download

Set up Dev Tunnel

Configure a Dev Tunnel to expose your local agent endpoint to Microsoft 365 services.

Create and start a tunnel

1. Sign in to Dev Tunnel:

   devtunnel user login
   

2. Create a persistent tunnel:

   devtunnel create --allow-anonymous
   

   This command returns a tunnel ID. Save this identifier for future use.

3. Configure the tunnel port:

   Assign the port your agent server uses (typically 3978):

   devtunnel port create <tunnel-id> -p <port-number>
   

4. Start the tunnel:

   devtunnel host <tunnel-id>
   

   The command displays your tunnel URL (for example, https://abc123xyz.devtunnels.ms:3978). Copy this URL for the next step.

Configure agent messaging endpoint

Register your Dev Tunnel URL (for example, https://abc123xyz.devtunnels.ms:3978/api/messages) as the agent messaging endpoint so Microsoft 365 knows where to route messages. Don't forget the /api/messages suffix to the endpoint.

Please see Set agent messaging endpoint

Test with Microsoft 365

With your Dev Tunnel active and endpoint registered, test your agent in Microsoft 365 applications.

Test in Microsoft Teams

1. Start your local agent by using the instructions in Install dependencies and start the agent application server.

2. Verify tunnel connectivity:

   devtunnel list
   

   Check that your tunnel shows active host connections. The "Host Connections" column should show a number greater than 0.

3. Interact with your agent in Teams:

   • Open Microsoft Teams (web or desktop)
   • In the Teams search bar, search for your agent by name or email
   • Start a conversation with the agent
   • Send a message and observe the response
   • Check your local console for incoming requests and agent activity

Test email notifications

If your agent is configured for email notifications:

1. Send an email to your agent's email address
2. CC your agent on an email thread
3. Monitor your local console for the notification webhook
4. Verify your agent processes and responds to the email

Test Word integration

For agents that respond to Word comments:

1. Open a Word document where your agent has access.
2. Add a comment mentioning your agent.
3. Check your local console for the notification.
4. Verify your agent's response appears in Word.

Monitor tunnel activity

Dev Tunnels provides traffic inspection to help debug connection problems and understand request flow:

devtunnel show <tunnel-id>

This command displays:

• Active connections and session details.
• Request and response information.
• Traffic volume statistics.
• Connection errors and warnings.

You can also monitor tunnel activity in real-time by watching the output from the devtunnel host command.

Maintain tunnel connections

Dev Tunnels require the devtunnel host process to stay running. If inactivity, network problems, or your computer going to sleep causes the connection to drop, you need to restart it.

Check tunnel status

Verify if your tunnel is active:

devtunnel list

The output displays:

• Tunnel ID: Your tunnel identifier
• Host Connections: Number of active connections (should be one or more when devtunnel host is running)
• Ports: Configured ports
• Expiration: Tunnel expiration time

If Host Connections shows 0, the tunnel exists but isn't currently hosted.

Restart a disconnected tunnel

If your tunnel connection drops, restart it by using the same tunnel ID:

devtunnel host <tunnel-id>

The tunnel URL stays the same, so you don't need to update your agent messaging endpoint configuration.

Keep tunnels active during development

To maintain stable connections:

• Keep the terminal window open - Don't close the terminal running devtunnel host.
• Prevent computer sleep - Configure your system to stay awake during testing sessions.
• Watch for connection errors - Monitor the devtunnel host terminal output for disconnection messages.
• Restart after network changes - If you switch networks or reconnect to VPN, restart the tunnel.

Clean up

When you finish testing with Dev Tunnels:

Stop the tunnel

Press Ctrl+C in the terminal running devtunnel host to stop the tunnel.

This command removes the Dev Tunnel URL from your agent's messaging endpoint. When you deploy to production, set the cloud-hosted endpoint URL.

Limitations

Consider these limitations when testing with Dev Tunnels:

• Development only: Use Dev Tunnels for development and testing, not for production.
• Performance: Expect higher latency compared to cloud-hosted agents due to network routing.
• Connection stability: Tunnel connections might occasionally drop and require manual restart.
• Security considerations: The --allow-anonymous flag is convenient for testing but don't use it with sensitive data.
• Session management: You might need to re-authenticate periodically depending on your session duration.

Next steps

After successful Dev Tunnel testing:

• Deploy your agent to the cloud: Deploy to Azure, Set agent messaging endpoint in AWS, or Set agent messaging endpoint in GCP.
• Configure agent messaging endpoints: Agent messaging endpoint.
• Follow the complete development lifecycle: Agent 365 Development Lifecycle.

Troubleshooting

If you're encountering issues while testing through Dev Tunnels, start here for common tunnel, connectivity, and endpoint fixes. For broader Agent 365 troubleshooting (setup, authentication, and messaging), see Troubleshooting.

Tunnel connection fails

Symptoms: Dev Tunnel doesn't start or immediately disconnects.

Solutions:

• Verify you're logged in: devtunnel user login
• Check if another process is using the same port
• Ensure your firewall allows Dev Tunnel connections
• Delete and recreate the tunnel: devtunnel delete <tunnel-id> then create a new one

Messages don't reach local agent

Symptoms: Microsoft 365 indicates the message was sent, but your local agent doesn't receive it.

Solutions:

• Confirm your agent is running locally
• Verify the tunnel is active: devtunnel list should show "Connected"
• Check the endpoint configuration: a365 config display should show your Dev Tunnel URL
• Review Dev Tunnel logs in the terminal running devtunnel host for connection errors
• Ensure your local port matches the tunnel port (both should be 3978 by default)

Authentication errors through Dev Tunnel

Symptoms: 401 or 403 errors when testing through Dev Tunnel.

Solutions:

• Verify agentic authentication is configured (bearer token authentication doesn't work with Dev Tunnels for Microsoft 365 integration).
• Check agent blueprint credentials by using a365 config display -g.
• Confirm your agent has the required permissions for the operations you're testing.
• Ensure your authentication tokens haven't expired.

Tunnel URL changed or expired

Symptoms: Previously working tunnel URL no longer routes to your agent.

Solutions:

• Check tunnel status by using devtunnel list.
• Restart the tunnel by using devtunnel host <tunnel-id>.
• Update the messaging endpoint if the URL changed by using a365 setup blueprint --endpoint-only.