chat-sdk

Chat via Copilot Studio SDK

Send a single utterance to a published agent via the Copilot Studio Client SDK. Use this for agents with integrated authentication / Entra ID SSO (authenticationmode 2).

Prerequisites

Requires prior authentication via /copilot-studio:test-auth. Do NOT ask the user for a client ID yourself — the test-auth skill handles app registration setup and authentication.

Instructions

1. Run the script with --client-id and the utterance from $ARGUMENTS:

   node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js \
     --client-id "<clientId>" "<utterance>" [--agent-dir <path>]
   

2. Authentication: Requires prior authentication via /copilot-studio:test-auth. The token is cached in the "test-agent" slot and shared with the eval API. If auth fails or the SDK hangs, tell the caller to re-run test-auth.

3. Parse the JSON output from stdout:

{
  "status": "ok",
  "protocol": "m365",
  "utterance": "hello",
  "conversation_id": "abc123-...",
  "start_activities": [ ... ],
  "activities": [ ... ]
}

Display the agent's response from the activities array:

• Text: activities where type === "message" — show text
• Suggested actions: suggestedActions.actions array
• Adaptive cards: attachments with contentType === "application/vnd.microsoft.card.adaptive"

Save conversation_id for follow-ups.

Multi-turn

Pass --conversation-id from the previous response:

node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js \
  --client-id "<id>" "<follow-up>" --conversation-id "<id>"

SDK sessions do not expire as quickly as DirectLine. Reuse conversation_id automatically for follow-ups.

Error Handling

Error	Cause	Resolution
Authentication failed	Wrong client ID or tenant	Verify app registration and permissions
Could not obtain conversation_id	Agent not published or wrong config	Verify agent is published