@pmcollab/coworkstream-engine-copilot-studio

Coding agents: read packages/workstream-engine/AGENTS.md for the engine integration recipe before wiring this adapter. Migrating an existing setup? See packages/workstream-engine/MIGRATION.md.

Microsoft Copilot Studio AgentRunner adapter for @pmcollab/coworkstream-engine. Talks to a Copilot Studio agent over Direct Line v3.

⚠ Data residency. The default baseUrl is https://directline.botframework.com/v3/directline, a globally-routed Microsoft endpoint. Requests carry the full work item (title, summary, meta) and the trust context. For data-residency-sensitive deployments (EU, UK, government cloud, sovereign clouds), pass baseUrl explicitly to a regional endpoint and confirm with your Microsoft tenant admin that the chosen Direct Line region is in your data-residency boundary. Do NOT default to the global endpoint for regulated customer data.

Install

npm install @pmcollab/coworkstream-engine-copilot-studio

Use

import { createEngine } from '@pmcollab/coworkstream-engine'
import { createCopilotStudioAgent } from '@pmcollab/coworkstream-engine-copilot-studio'

const agent = createCopilotStudioAgent({
  id: 'helpdesk',
  directLineSecret: process.env.DIRECT_LINE_SECRET,
})

const engine = createEngine({ agents: [agent], /* ... */ })

The Direct Line secret comes from your Copilot Studio agent's channel settings — Channels → Mobile / Custom → Direct Line.

How position extraction works

The adapter looks for a decision in this priority order:

1. Adaptive Card data with a position field (recommended). Have your topic emit an Adaptive Card whose data includes { position, reasoning, confidence }.
2. suggestedActions[0].value — if it's an object with position.
3. Text fallback — searches the bot's message text for known position keywords (approve, reject, acknowledge, etc.).

Customize via extractPosition(activity, item, ctx) → { position, reasoning, confidence } if your topic uses a different shape.

Recommended Copilot Studio topic pattern

Configure your topic to end with a Question node that emits an Adaptive Card:

{
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    { "type": "TextBlock", "text": "I recommend ${decision}" }
  ],
  "data": {
    "position": "${decision}",
    "reasoning": "${rationale}",
    "confidence": "${confidence}"
  }
}

The adapter picks data straight off the card.

Options

createCopilotStudioAgent({
  id, directLineSecret,           // required
  name?, avatar?, capabilities?,
  baseUrl?: string,               // default Direct Line v3 endpoint
  fetchFn?: typeof fetch,
  pollIntervalMs?: number,        // default 1000
  timeoutMs?: number,             // default 60_000
  defaultConfidence?: number,
  formatItem?: (item, ctx) => string,
  extractPosition?: (activity, item, ctx) => { position, reasoning, confidence },
})

License

Commercial. See LICENSE in the repository root.