n8n-nodes-agents-sdk

Build Microsoft Teams, M365 Copilot, WebChat, and Direct Line bots with n8n as your orchestration layer.

This is a community node for self-hosted n8n. It wraps the Microsoft 365 Agents SDK (the supported successor to botbuilder) so you get JWT validation, MSAL token management, Bot Connector routing, and the full CardFactory surface — Adaptive, Hero, Thumbnail, Animation, Audio, Video, Sign-In, Receipt, O365 Connector, and Raw Attachment — as first-class n8n operations. No raw HTTP, no hand-assembled Activity JSON, no OAuth plumbing.

0.4.0 breaking change. The single Card resource was split into ten first-class card resources (Adaptive, Animation, Audio, Hero, O365 Connector, Raw Attachment, Receipt, Sign-In, Thumbnail, Video). Workflows saved on 0.3.x with resource: "card" will fail loudly on load — rebuild them on resource: "adaptiveCard" (for templated Adaptive Cards) or the appropriate new card resource. See CHANGELOG.md for the full list.

What you get

Requirements

• n8n 1.54+ (self-hosted — n8n Cloud's sandbox cannot load this package's runtime dependencies)
• Node.js 20 or later
• An Azure Bot registration (free F0 tier is fine) with App ID + client secret + tenant
• A channel configured in Azure (Teams, M365 Copilot, WebChat, or Direct Line)

Install

From the n8n UI (single-instance self-hosted)

Settings → Community Nodes → Install → n8n-nodes-agents-sdk

From npm

npm install n8n-nodes-agents-sdk

Queue mode (separate app + worker)

n8n's UI installer does not work in queue mode — it only installs on the node that handled the UI click, leaving workers out of sync. Install at container start instead:

# In your entrypoint, before exec /docker-entrypoint.sh:
cd /home/node/.n8n/nodes
npm install --no-audit --no-fund --omit=dev --omit=peer --omit=optional \
  n8n-nodes-agents-sdk@<pinned-version>

Both app and worker services need the package available. Use per-service bind mounts to avoid install races on shared volumes.

Nodes

M365 Agent Trigger

Receives POSTs from Azure Bot Service, validates the Bot Framework JWT, and emits a parsed envelope.

• Validates the inbound JWT against the live Microsoft JWKS on every request
• Handles Azure's GET endpoint-verification ping automatically
• Filter by Activity type (message, invoke, conversationUpdate, etc.)
• Response Mode parameter: Immediate (default — reply 200 right away) or Wait For Response Node (keep the HTTP connection open for a downstream M365 Agent → Invoke Response node — required for Action.Execute invokes and messaging-extension flows)

M365 Agent

Unified action node. Pick a Resource and an Operation; the canvas subtitle renders as <operation> <resource> (for example send heroCard, update adaptiveCard).

The Conversation Source toggle picks between From Envelope (default — read the conversation routing from the inbound item, works for every reply/update/delete flow) and Specify Manually (fill serviceUrl, conversation.id, channelId, and optional activityId yourself — for proactive sends originating outside the bot webhook).

Both nodes use the same credential — either M365 Agent API (classic bot) or M365 Agent 365 API (Agent 365). Neither is exposed as an AI-agent tool — side effects (sending to Azure Bot Service) and external webhook triggers aren't safe for autonomous LLM invocation.

Credential

M365 Agent API — your Azure Bot registration's App ID, client secret, and tenant. Three app types:

• SingleTenant (recommended) — token scoped to a single Entra tenant
• MultiTenant — kept for legacy registrations; Microsoft deprecated this path for new bots after 2025-07-31
• UserAssignedMsi — Azure managed identity

The built-in credential test hits login.microsoftonline.com to verify network reachability. Full token-acquisition validation runs inside the Trigger on every inbound webhook.

Agent 365 support

v0.3.0 added first-class support for the Entra Agent Identity Blueprint alongside the classic Azure Bot credential. Register your bot as a Microsoft 365 Agent Identity (preview) and issue tokens through MSAL or an isolated auth sidecar — no changes required for existing classic bot deployments.

authKind parameter

Identity modes (Agent 365 only)

Further reading

• Sidecar deployment: examples/sidecar/README.md
• Auth guide (choosing between classic, inline, and sidecar): docs/auth-guide.md
• OBO guide (what interactiveOBO is and why it's router-only today): docs/obo-guide.md
• Licensing notes (Frontier preview vs GA cost implications): docs/licensing-notes.md

Quick start — echo bot in 3 nodes

[M365 Agent Trigger]  →  [Set]  →  [M365 Agent — Message: Reply]

1. Credential. Create an M365 Agent API credential with your Azure Bot App ID, client secret, and tenant.
2. Trigger. Drop an M365 Agent Trigger, attach the credential. Copy the node's Production webhook URL.
3. Messaging endpoint. Paste the URL into your Azure Bot registration's Messaging endpoint field.
4. Compose the reply. Drop a Set node (or just write an expression directly in step 5's Text field): Echo: {{ $json.activity.text }}.
5. Reply. Drop an M365 Agent node. Set Resource = Message, Operation = Reply. Leave Conversation Source at From Envelope. Fill Text with the expression from step 4.
6. Activate the workflow, message your bot in Teams, and the echo comes back within a second.

Envelope contract

Every node in this package reads and writes items of this shape:

{
  "conversationReference": {
    "serviceUrl", "conversation": { "id", "conversationType" },
    "activityId", "channelId", "bot", "user", "locale"
  },
  "activity": { "type", "text", "attachments", ... },
  "parsed": {      // Trigger only — convenience fields
    "action", "submitData", "userName", "userId", ...
  },
  "raw": { ... }    // Trigger only — full incoming Activity
}

Contract:

• The Trigger emits the full envelope on every inbound activity.
• The M365 Agent node reads conversationReference (via the From Envelope default) to route the outbound call. On output it spreads every input field through unchanged and adds an operation-specific result field (sendResult / replyResult / updateResult / deleteResult / replyInThreadResult / cardSendResult / cardUpdateResult).

Ancillary state you carry through your workflow (correlation IDs, cached state, upstream webhook payloads, etc.) survives the M365 Agent node unchanged.

Cards

Ten card resources cover every shape the Bot Framework / Teams renders. Pick the one that matches your UX — they fall into three authoring styles:

1. Builder cards — fill in a form, no JSON

Hero Card, Thumbnail Card, Animation Card, Audio Card, Video Card, Sign-In Card all expose a form UI. You fill in title, subtitle, text, images, buttons, media URLs — the node assembles the correct SDK shape for you. This is the simplest path for the common case (an order-update card, a "click here to sign in" card, a notification with quick-reply buttons).

The media-family (Animation / Audio / Video) requires at least one media URL and lets you set autoloop / autostart / aspect / duration under Options. Every builder card's Buttons and Tap Action share the same unified CardAction row (Type + Title + Value + optional Channel Data / Value JSON / image / text / displayText) across all 11 SDK action types (openUrl, imBack, messageBack, postBack, call, downloadFile, openApp, playAudio, playVideo, showImage, signin). Channel support varies — Teams, WebChat, and Direct Line each render a subset.

Minimal Hero Card workflow parameters:

resource: heroCard
operation: send
title: 'Order #{{$json.orderId}}'
subtitle: 'Ready for pickup'
text: 'Tap to confirm'
buttons:
  button:
    - type: openUrl
      title: 'View order'
      value: '{{$json.orderUrl}}'
options:
  fallbackText: 'Order ready'
  tapAction:
    type: openUrl
    value: '{{$json.orderUrl}}'

2. Adaptive Card — templated JSON with bindings

Paste a template from the Adaptive Cards Designer into Card Template. Use ${field} for placeholders. ${field} bindings resolve against whatever object you put in Binding Data (defaults to the whole inbound item ={{ $json }}):

{
	"type": "AdaptiveCard",
	"version": "1.6",
	"body": [
		{ "type": "TextBlock", "text": "Order #${orderId}", "weight": "bolder", "size": "large" },
		{ "type": "TextBlock", "text": "${status}" }
	],
	"actions": [
		{
			"type": "Action.Submit",
			"title": "Acknowledge",
			"data": { "action": "ack", "orderId": "${orderId}" }
		}
	]
}

Any [Parsing] Unknown property warnings the designer shows on Action.Submit.data custom keys are false positives — they're part of the Adaptive Cards spec, just not typed in the designer's bundled schema.

State-driven variants. You don't need a separate "pick-a-template-by-state" node. adaptivecards-templating supports this directly:

1. ${field} — scalar binding. Change a value across the card with one variable: "style": "${statusStyle}", "text": "${statusBadgeText}".
2. $when — conditional rendering. Show/hide whole sections per state: { "$when": "${status == 'completed'}", "type": "TextBlock", "text": "Done" }.
3. $data — iterate over an array. Render one button per item in cardButtons.

A single template handles every state (new / accepted / in_progress / paused / completed, etc.) — no picker node needed. See the upstream adaptivecards-templating docs for the full reference.

3. JSON-content cards — paste the whole card

Receipt Card, O365 Connector Card, and Raw Attachment take the full card object as JSON in a single field. Use these when the card shape is fixed (Teams connector cards with their own schema) or when you want an escape hatch for attachment types not yet first-class here.

• Receipt — { title, facts[], items[], total, tax?, vat?, tap?, buttons[] }.
• O365 Connector — Teams-specific: { title, summary, themeColor, sections[], potentialAction[] }. See the cards reference.
• Raw Attachment — you provide contentType + content directly. Useful for card families not yet first-class in this package.

Proactive sends (no inbound activity)

To message a channel from a workflow that wasn't triggered by the Trigger (a schedule, an external webhook, a database row, anything), switch Conversation Source to Specify Manually and fill in the fields. For Teams channels, conversation.id looks like 19:xxx@thread.tacv2 and you'll typically have captured it from a prior bot interaction.

[Schedule Trigger]  →  [HTTP Request: fetch data]  →  [M365 Agent — Adaptive Card: Send (manual)]

Issues & contributions

Bug reports, feature requests, and PRs are welcome at github.com/mrkhachaturov/n8n-nodes-agents-sdk. Please include your n8n version, the resource/operation you're using, and the relevant workflow JSON or error message.

Links

• npm package
• GitHub repository
• Microsoft 365 Agents SDK documentation
• Azure Bot Service documentation
• Adaptive Cards Designer

License

MIT © Ruben Khachaturov