Add Activity Protocol adapter (Microsoft Copilot / Teams ingress)

[jrosskopf]

Background / why now. Triton's Microsoft-surface story was split across two
paths that each fall short: the MCP-App widget (rich, but M365-Copilot
declarative agents only — needs a paid Copilot seat, and Copilot Studio
can't render it) and A2A (works in Copilot Studio, but the UI is dropped
on the wire). The substrate interactive-UI epic chased the MCP-App widget and
hit that licensing/host wall. This issue is the pivot: an Activity Protocol
adapter emitting Adaptive Cards reaches Copilot Studio (connected agent),
Teams, and M365 Copilot Chat over an open spec, with real interactive controls
and no paid-Copilot dependency. It supersedes the MCP-App-widget path for the
Microsoft surface (substrate #657 and children are being closed against this).

Add Activity Protocol adapter (Microsoft Copilot / Teams ingress)

Labels: adapter, enhancement, interop

Problem

Triton currently exposes MCP, A2A, REST and chat adapters, with A2UI as the
lowest-common-denominator UI wire format. None of these can deliver rich UI into
Microsoft Copilot.

Microsoft has two rendering paths into Copilot, and A2A is not one of them:

Path	Wire format	Reaches	Notes
Activity Protocol	Adaptive Card as Attachment	Copilot Studio (connected agent), Teams, M365 Copilot Chat, WebChat, Agents Client SDK	Open spec, no SDK required
MCP Apps	HTML widget in sandboxed iframe	M365 Copilot declarative agents only	Toolkit-built agents; Copilot Studio does tool calls but no widgets
A2A	text parts	Copilot Studio orchestrator	UI is dropped — see below

Copilot Studio's A2A connection is an orchestration channel only. Microsoft's own
integration table routes "agents built with Microsoft 365 Agents SDK" to Activity
Protocol, not A2A. Worse, Microsoft Agent Framework's A2A layer converts only
TextContent and UriContent to A2A parts and silently drops everything else
(DataContent → DataPart is unimplemented, microsoft/agent-framework#2677), so
even a spec-legal structured payload would not survive the trip.

Consequence: without an Activity adapter, Triton is text-only on every Microsoft
surface.

Proposal

Add adapters/activity as a fourth ingress, siblings to the existing MCP/A2A/REST
adapters, with an A2UI → Adaptive Card 1.5 transpiler in the shared UI layer.

Scope — adapter

• POST /api/messages accepting an Activity JSON object
• Handle activity types: message, conversationUpdate, invoke,
  endOfConversation, typing; 200-ack anything else
• invoke names: adaptiveCard/action (Action.Execute round-trip) and
  signin/tokenExchange (deferred, see below)
• Inbound auth: validate Entra bearer JWT against the Bot Framework OpenID
  metadata endpoint; None mode for local dev
• Outbound, synchronous: when inbound carries deliveryMode: "expectReplies",
  return reply activities in the HTTP response body — implement first,
  this is the path Copilot Studio's skill/connected-agent model has used
• Outbound, asynchronous: POST {serviceUrl}/v3/conversations/{conversationId}/activities
  with a client-credentials token (scope https://api.botframework.com/.default)
• Conversation/turn state keyed on conversationId + id, mapped onto the
  existing session abstraction (same role contextId plays for A2A)

Scope — UI transpile

• A2UI basic catalog → Adaptive Card 1.5, emitted as an Attachment with
  contentType: application/vnd.microsoft.card.adaptive
• Target 1.5, not 1.6: Copilot Studio accepts 1.6 but Teams and the D365
  chat widget cap at 1.5
• Mapping (14 of 18 basic-catalog components are direct):
  • Row/Column → ColumnSet/Container
  • Card → Container with style, or the card root
  • Text/Image/Icon/Divider → TextBlock/Image/Icon†/separator
  • Video/AudioPlayer → Media
  • Button → Action.Submit (fire-and-forget) or Action.Execute (needs response)
  • TextField/CheckBox/DateTimeInput/MultipleChoice → Input.Text/Input.Toggle/
    Input.Date+Input.Time/Input.ChoiceSet
  • Slider → Input.Number (lossy, no track UI)
  • Tabs → stacked Containers + Action.ToggleVisibility (lossy)
  • Modal → Action.ShowCard (lossy, inline expansion not overlay)
  • List with template → expand server-side against the data model
• Set fallbackText on every emitted card

Out of scope for this issue

• MCP Apps widget path for M365 declarative agents — separate issue, different
  host, different capability matrix
• Streaming (typing activities carrying a streaminfo entity) — nice for
  Copilot Chat, unnecessary for Copilot Studio delegation
• Teams-specific channelData and Teams invoke names
• SSO / on-behalf-of token exchange

Open question — blocks the transpiler, not the adapter

Does an orchestrating Copilot Studio agent relay a connected agent's card
attachments to the end user, or does it flatten them to text?

Under the old Bot Framework skill model attachments were forwarded. The current
connected-agent docs describe text round-trips only and say nothing about
attachments. Everything in "Scope — UI transpile" is wasted effort if the
orchestrator flattens.

Spike (timebox 1h): run CopilotStudioSamples/extensibility/agents-sdk/relay-bot
(or copilotstudio-skill) behind a dev tunnel, register it in Copilot Studio as a
Microsoft 365 Agents SDK agent with auth None, have it reply with a trivial
Adaptive Card, and observe what the orchestrator renders in the test canvas.

If it flattens, cards still reach the user via Azure Bot registration → Teams /
M365 Copilot Chat directly, bypassing the Copilot Studio orchestrator. The
adapter is worth building either way; only the deployment topology changes.

Notes / risks

• No official Rust SDK for the Agents SDK. The spec in microsoft/Agents
  (specs/activity/protocol-activity.md, protocol-cards.md) is the only
  contract. Note it explicitly excludes card definitions — those live in the
  Adaptive Cards and Activity Protocol Cards specs and travel as attachments.
• Legacy fixed-schema cards (Hero, Thumbnail, Receipt, SignIn, OAuth) are
  deliberately ignored. Teams already treats them as second class.
• Local testing needs no Azure resources: the M365 Agents Playground (formerly
  Teams App Test Tool) speaks Activity Protocol to any local endpoint without a
  bot registration.

Acceptance criteria

• Triton registers as a connected agent in Copilot Studio and completes a
  text round-trip
• An A2UI surface with Row/Column/Text/Button/TextField renders as an
  Adaptive Card in at least one Microsoft host
• A card button press arrives back as an invoke and mutates the A2UI data
  model
• Spike result documented in this issue, transpiler scope confirmed or cut

† Adaptive Cards 1.6 / Teams extension — omit from the 1.5 baseline mapping.

[jrosskopf]

Spike result (2026-09-04) — Copilot Studio connect paths + relay-vs-flatten

Ran the spike live: stood up an Activity endpoint (/api/messages, auth None, replies with an Adaptive Card: title + Input.ChoiceSet dropdown + Action.Submit), exposed it publicly via Tailscale Funnel (https://…:8443, verified public via Google DoH → Tailscale ingress — note: cloudflared quick tunnels are DNS-blocked on this network), and drove the Copilot Studio console.

What Copilot Studio actually offers to connect an external agent (new "standard harness" experience):

UI path	Takes	Verdict for us
Connected agents → Add connected agent	only other published tenant agents ("No agents available") — no external URL	not for an external endpoint
Add skill	a SKILL.md upload (YAML name+description)	not an HTTP/Activity endpoint
Add agent → A2A agent → endpoint URL (per docs)	an A2A JSON-RPC endpoint (message/send); builds a custom connector	wrong protocol for us + see below

Two decisive findings:

1. A2A ≠ Activity. The "A2A agent" connect expects A2A JSON-RPC, not Bot Framework Activity (/api/messages). Our Activity endpoint can't be connected via that flow at all. And per the docs, A2A returns text (chat history + text parts, "appears in the test chat") — cards flatten. The docs' own integration table routes "agents built with Microsoft 365 Agents SDK → Activity Protocol", not A2A. So A2A is a text-orchestration channel; it is not a rich-UI path.
2. The card path is Activity Protocol via a Bot channel — which we already have for Teams. triton-chat-msteams already speaks Bot Framework Activity + renders Adaptive Cards (Input.ChoiceSet, Action.Execute) to Teams. So "cards into the Microsoft ecosystem" = Activity Protocol → Adaptive Cards over a Bot channel (Azure Bot), and Teams renders them today.

Conclusion (confirms the issue's fallback): the reliable card-rendering topology is Azure Bot → Teams / M365 Copilot Chat (direct), not the Copilot Studio orchestrator (which, via A2A, flattens). So:

• Transpiler scope stands — Adaptive Cards are the right target; they render in Teams via the Bot channel regardless of the orchestrator.
• The "does the orchestrator relay attachments" question is effectively moot for our path: we don't reach Copilot Studio via A2A (flattens); we reach Teams/M365 Copilot Chat via the Bot channel where cards render.
• Build shape (matches the "unify" decision): the Activity adapter = generalize triton-chat-msteams (already Bot Framework Activity + Adaptive Cards) into a host-agnostic /api/messages ingress; deploy behind an Azure Bot registration; Teams is the DoD (cards already render there). Copilot Studio can consume it as a Bot channel too if wanted — but not via the A2A connector.

Spike infra (Tailscale Funnel + the Python Activity endpoint) is still up for a definitive Azure-Bot→Teams live test when we wire that in Phase 3/4.

[jrosskopf]

Phase 1 landing as #248 (host-agnostic Activity ingress).

After the Phase-0 spike + a crew review, the adapter/transpiler work reduces to one genuinely valuable, correct change: an opt-in canonical POST /api/messages route on the (now generalized) msteams adapter, single-claimant and fail-closed. Rationale for what was cut:

• expectReplies / dev-None-auth — the spike showed Copilot Studio's external-connect (A2A JSON-RPC) flattens Adaptive Cards; the rich-card path is Activity Protocol over an Azure Bot channel → Teams, which the adapter already does (async POST to the JWT-asserted serviceUrl). Those items target the A2A-orchestrator/skill model, so building them would be dead code.
• Adaptive Card 1.4→1.5 — reverted: the transpiler emits no property above AC 1.3, and declaring 1.5 downgrades cards to fallbackText on <1.5 hosts (the non-Teams surfaces this ingress serves). Bump when a 1.5-only feature is actually emitted.
• Transpiler "extend" — no gap: the card builder already maps triton's full Surface set (Text/Narration/Dashboard/Sources/Report/Button/Selection/Form/Diff). The agent is deliberately buttons-only in chat today (followups.rs), so Selection/Form render support is latent-but-ready, not missing.

Follow-up filed: #249 (rate-limit pre-auth audit emission on public webhook paths — pre-existing).

Next: merge #248 → vendor bump + TRITON_MSTEAMS_CANONICAL_PATH opt-in in datazoo-agent-template → substrate image bump + deploy → live E2E (route mounted + auth fail-closed + card no-regression in Teams).

[jrosskopf]

Shipped & verified live on agent-lab (2026-09-04).

Pipeline (all merged, each green, red-green TDD): triton#248 → datazoo-agent-template#221 (image 169a2a5cc7a2) → hetzner-agent-substrate#710 (deploy helm upgrade --atomic, success).

Live E2E on https://agent-lab.data-zoo.de (real system, no mocks):

check	result
GET /healthz	200
POST /api/messages (no auth)	401 missing bearer — route mounted + fail-closed
POST /api/messages (forged bearer)	401
GET /api/messages	405 (route exists, POST-only)
POST /msteams/webhook (no auth / forged)	401 / 401 — no regression

The 404→401 flip on /api/messages across the rollout is itself the deploy discriminator (old image had no such route).

Human-gated remainder (by design): a valid signed Teams round-trip needs a Bot Framework-signed JWT, which cannot be forged, so a live Adaptive-Card render is a human checklist step. The live card path is unchanged by this work — the image only added a route; the card builder is byte-identical (AC 1.4), and the Azure Bot's messaging endpoint still targets /msteams/webhook. To make /api/messages the live Teams path, repoint the Bot's endpoint to .../api/messages (infra-backplane, operator pulumi up) — both paths work, so this is optional and low-risk.