agents-sdk-typescript-debugging

name

agents-sdk-typescript-debugging

description

Use when troubleshooting an agent built with the Microsoft Agents SDK (@microsoft/agents-hosting and related packages). Trigger on any of these symptoms: build or TypeScript errors, crashes on startup, 401 or auth errors on incoming requests, the bot not responding to messages, .env configuration problems, Azure AD credential failures (AADSTS errors), port conflicts, or the agent not connecting in Teams or the Agents Playground. Use even if the user doesn't mention the SDK by name — trigger on symptoms like "my bot won't start", "getting 401s", or "bot isn't responding."

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

Namespace	What it logs
agents:authorization:connections	Auth connections loaded at startup (clientId, tenantId, authType); which connection is selected per request
agents:authorization:manager	Auth handlers configured at startup (type, scopes); which handler is invoked per request
agents:authorization:azurebot	Azure Bot sign-in flow detail (token exchange, magic code, SSO)
agents:authorization:agentic	Agentic auth flow detail (token acquisition, OBO)
agents:authorization	High-level authorization middleware decisions
agents:msal	MSAL token acquisition (token requests, cache hits, OBO)
agents:jwt-middleware	Incoming JWT validation
agents:authConfiguration	Auth configuration loading

Adapter & request handling

Namespace	What it logs
agents:cloud-adapter	Incoming request processing, activity dispatch
agents:base-adapter	Base adapter lifecycle
agents:connector-client	Outbound calls to the Bot Connector service
agents:user-token-client	User token client requests

Application & state

Namespace	What it logs
agents:app	AgentApplication routing and lifecycle
agents:activity-handler	ActivityHandler event dispatch
agents:state	State read/write operations
agents:turnState	Turn state access
agents:memory-storage	MemoryStorage read/write
agents:middleware	Middleware pipeline execution

Streaming, attachments & transcripts

Namespace	What it logs
agents:streamingResponse	Streaming response lifecycle
agents:attachmentDownloader	Attachment download requests
agents:M365AttachmentDownloader	M365-specific attachment downloads
agents:file-transcript-logger	File transcript write operations
agents:rest-client	REST client calls (transcript middleware)

Agent-to-agent

Namespace	What it logs
agents:agent-client	Outbound agent client calls and response handling

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 '{}'

Response	Meaning
401	Agent is running, auth is active — this is correct for a configured agent
200	Agent is running with auth disabled (blank clientId) — correct for anonymous local dev
000 or connection refused	Agent is not running, wrong port, or crashed on startup

---

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:

Error code	Cause
AADSTS700016	clientId not found in tenant — wrong ID or wrong tenant
AADSTS7000215	Invalid clientSecret — expired or incorrect
AADSTS90002	tenantId not found

---

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