agents-sdk-typescript-debugging

Debugging Agents Built with Microsoft Agents SDK

Overview

Most agent failures fall into one of three categories: the code doesn't build or start, the configuration is wrong, or the agent isn't reachable. Work through this checklist in order — each step confirms a prerequisite for the next.

Checklist

You MUST create a task for each of these items and complete them in order:

1. Make sure the code builds successfully.
2. Make sure the application starts and runs without crashing.
3. Make sure the application opens a port and listens for incoming requests.
4. Validate the .env configuration.
5. Validate the bot's credentials against Azure AD.
6. Use the Agents Playground to test the agent end-to-end locally.

---

1. Build the code

npm run build

Expected: exits with code 0, no errors. Fix any TypeScript or import errors before continuing.

---

2. Start the application

Run with debug logging enabled to get detailed output from the SDK internals:

DEBUG=agents:* npm start

Or for anonymous local dev:

DEBUG=agents:* node ./dist/index.js

The DEBUG=agents:* flag enables verbose logging across all SDK namespaces. Scope down to reduce noise:

DEBUG=agents:* npm start                    # everything
DEBUG=agents:authorization:* npm start      # all auth (most useful starting point)
DEBUG=agents:msal npm start                 # token acquisition only

Auth & connections

Adapter & request handling

Application & state

Streaming, attachments & transcripts

Agent-to-agent

Watch for crash output. Common startup errors:

• Cannot find module — missing npm install, or dist/ not built yet
• ERR_MODULE_NOT_FOUND — check "type": "module" in package.json and that imports use .js extensions
• Port already in use — another process is on port 3978; kill it or set PORT in .env

If the agent starts cleanly, you should see output like:

Server listening on port 3978

---

3. Confirm the agent is reachable

curl -s -o /dev/null -w "%{http_code}" \
  -X POST http://localhost:3978/api/messages \
  -H "Content-Type: application/json" \
  -d '{}'

---

4. Validate .env configuration

Configuration mistakes are the most common source of failures. Check each area below.

4a. Confirm the file is being loaded

The SDK requires node --env-file .env (Node 20+) or a manual dotenv call. If you're using npm start, check that package.json uses --env-file:

"start": "node --env-file .env ./dist/index.js"

Without --env-file, environment variables silently don't load and the agent starts with no auth config.

4b. Check for the correct env var format

The SDK uses the modern connections__ format. Using the legacy flat format (clientId=, clientSecret=, tenantId=) still works but is only for backwards compatibility. Mixing the two formats causes silent misconfiguration.

Modern format (use this):

connections__serviceConnection__settings__clientId=<your-app-id>
connections__serviceConnection__settings__clientSecret=<your-secret>
connections__serviceConnection__settings__tenantId=<your-tenant-id>
connectionsMap__0__connection=serviceConnection
connectionsMap__0__serviceUrl=*

Legacy format (avoid for new agents):

clientId=<your-app-id>
clientSecret=<your-secret>
tenantId=<your-tenant-id>

4c. Check double-underscore separators

A single underscore (_) is not the same as a double underscore (__). The SDK uses __ to separate path segments. A typo like connections_serviceConnection_settings_clientId will be silently ignored.

4d. Check connectionsMap entries

If you have multiple connections, each must have a connectionsMap entry. The first entry whose serviceUrl pattern matches the incoming request wins. Always include a serviceUrl=* fallback as the last entry.

With a single connection, connectionsMap can be omitted — the SDK defaults to serviceUrl=*.

4e. Check OAuth handler variables

If your agent uses user sign-in (authorization: { graph: { ... } }), the OAuth connection name must be set:

AgentApplication__UserAuthorization__Handlers__graph__Settings__azureBotOAuthConnectionName=GraphOAuthConnection

The handler ID (graph) must match the key used in the authorization config in your code. A mismatch causes the sign-in flow to fail silently or with a cryptic error.

---

5. Validate bot credentials against Azure AD

Once the .env looks correct, confirm the credentials actually work by requesting a token:

curl -s -X POST \
  "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" \
  -d "grant_type=client_credentials\
&client_id=$clientId\
&client_secret=$clientSecret\
&scope=https://api.botframework.com/.default" \
  | jq '{token_type, expires_in, error, error_description}'

A successful response includes access_token. Common errors:

---

6. Test with Agents Playground

The Agents Playground acts as a mock connector and channel client. It lets you test the full message flow locally without deploying to Azure or configuring a real Bot resource.

Install:

npm install -g agentsplayground

Run against an anonymous agent (no .env needed):

npm test

This assumes your package.json has:

"start:anon": "node ./dist/index.js",
"test-tool": "agentsplayground -c emulator",
"test": "npm-run-all -p -r start:anon test-tool"

Run against an authenticated agent:

agentsplayground -c msteams \
  --client-id <your-app-id> \
  --client-secret <your-secret> \
  --tenant-id <your-tenant-id>

Channel options (-c): msteams, webchat, directline, emulator, agents

If the playground connects but messages don't get responses, the agent is running but a message handler may be missing or the route isn't matching. Add a fallback handler to confirm:

this.onActivity('message', async (ctx: TurnContext) => {
  await ctx.sendActivity(`Echo: ${ctx.activity.text}`)
}, [], RouteRank.Last)

---

Validate an OAuth connection name

OAuth connection names can only be tested end-to-end through a real sign-in flow:

Azure Portal → Your Bot Resource → Settings → OAuth Connection Settings → [your connection] → Test Connection

This confirms the connection name matches, the OAuth app has the right scopes, and the redirect URI (https://token.botframework.com/.auth/web/redirect) is registered on the app registration.

Contributing

If you hit a problem this skill couldn't solve, found a workaround, or noticed something wrong or outdated, that's valuable — please help improve this skill for everyone.

Draft a suggested issue title and body based on the conversation, then ask the user to open it at: https://github.com/microsoft/agents/issues/new

A good issue includes:

• What the user was trying to do
• What went wrong (errors, unexpected behavior)
• What worked — including any workaround found during this conversation
• Relevant code or config snippets