/chat-directline

user-invocable: false
description: Send a message to a Copilot Studio agent via DirectLine v3. Use for agents with no auth or manual auth. Requires a token endpoint URL or DirectLine secret.
argument-hint: <utterance>
allowed-tools: Bash(node *chat-with-agent.bundle.js *), Read, Glob
agent: copilot-studio-test

Chat via DirectLine

Send a single utterance to a published agent via the DirectLine v3 REST API. Use this for agents with **no authentication** (authenticationmode 1) or **manual authentication** (authenticationmode 3).

Instructions

1. Run the script with `--token-endpoint` (from detect-mode output) and the utterance from `$ARGUMENTS`:

   node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js \
     --token-endpoint "<tokenEndpoint>" "<utterance>"

If the user provided a DirectLine secret instead:

   node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js \
     --directline-secret "<secret>" "<utterance>"

2. Parse the JSON output from stdout.

Normal response (`status: "ok"`)

{
  "status": "ok",
  "protocol": "directline",
  "utterance": "hello",
  "conversation_id": "abc123-XYZ",
  "directline_token": "eyJ...",
  "watermark": "3",
  "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`, `directline_token`, and `watermark`** — needed for follow-ups.

Sign-in required (`status: "signin_required"`)

The agent requires the user to authenticate (manual auth agents):

{
  "status": "signin_required",
  "protocol": "directline",
  "signin_url": "https://...",
  "resume_command": "...",
  "followup_command": "..."
}

1. Show the `signin_url` to the user, ask for the validation code 2. Send the code: `node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js <resume_command with code substituted>` 3. Re-send the utterance: `node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js <followup_command>`

Use `resume_command` and `followup_command` exactly as given.

Multi-turn

Pass all three values from the previous response:

node ${CLAUDE_SKILL_DIR}/../../scripts/chat-with-agent.bundle.js \
  --token-endpoint "<url>" "<follow-up>" \
  --conversation-id "<id>" --directline-token "<token>" --watermark "<watermark>"

• **`directline_token`** is bound to the conversation — do NOT fetch a new token. Always reuse from the previous response.
• **`watermark`** tracks seen activities — pass it to avoid duplicates.
• Tokens expire after **~30 minutes**. If expired, start a new conversation (omit `--conversation-id`).

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | `Token endpoint rejected` | Agent not published or wrong URL | Verify agent is published | | `Conversation not found` | Token expired (>30 min) | Start a new conversation |